DevTrace - 技术决策五算子

SKILL.md

# DevTrace 技术决策五算子（Agent Skill）
**skill_name:** `DevTrace_Technical_Decision_Framework` 
**version:** `1.1` 
**定位:** 给 Agent 增加"综合开发/架构判断能力"的决策自检框架（偏工程落地，不强制量化） 
**适用场景:** 架构决策、技术选型、代码审查、重构方案评估、技术债务评估、项目风险预判 
**触发条件（自动启用）:** 当用户讨论"要不要做/怎么做/选哪个/改动影响/风险如何/能否上线/是否重构/是否拆分/是否引入依赖"等技术决策时启用 
**核心约束:** 不凭空臆测。信息不足时先追问；若必须回答，用"条件化结论 + 前置条件"表达。

---

## 0. Skill 行为准则（Agent Operating Rules）
1. **先画拓扑再谈方案**：任何建议先说明影响范围、关键路径、故障域。
2. **先守边界再谈优化**：先检查抽象边界/契约是否被破坏，再谈实现细节。
3. **默认可逆**：优先推荐可灰度、可回滚、可旁路、可降级的方案。
4. **默认先问缺口**：如果缺少关键上下文，先问最小问题集；否则输出"需要补充的信息"。
5. **红线触发就否决**：任一算子出现"高风险且无可行缓解"必须输出"不建议实施"或"需先解决前置条件"。

---

## 1️⃣ 拓扑（Topology）——结构算子
### 核心定义
这不是孤立的代码，是依赖网络中的一个节点——改动它，依赖图会传导；依赖图变了，它会失效。

### 需要关注的工程问题
- **调用链深度**：影响直接下游/间接下游/是否可能级联雪崩？
- **数据流向**：是数据源（SSOT）还是数据汇（Consumer）？改动会污染、断裂、还是扩散？
- **故障域边界**：故障可隔离在进程/容器/服务/集群？是否会跨边界扩散？
- **循环依赖/隐性耦合**：是否形成 A→B→C→A，或"共享DB/共享缓存/共享配置"的隐性环？

### 默认追问（信息不足时至少问其中3个）
- 变更发生在哪：服务/模块/仓库/接口/表/队列/定时任务？
- 关键入口是什么（API/消息/批任务）？关键出口是什么（DB/外部服务）？
- 同步调用还是异步事件？超时/重试/熔断策略是什么？
- 故障时如何降级：返回兜底/跳过步骤/排队/人工介入？
- 是否属于关键路径（支付/登录/下单/结算等）？

### 必出产物（输出中必须出现）
- **拓扑图（文字描述）**：节点+边+关键路径+故障传播点（见输出模板）

---

## 2️⃣ 抽象（Abstraction）——分层算子
### 核心定义
你写的代码是接口还是实现？稳定层在哪，易变层在哪？——混淆层级是技术债务的主要源头。

### 需要关注的工程问题
- **Leaky Abstraction**：抽象是否泄漏实现细节（ORM/框架/云厂商细节渗透到业务层）？
- **依赖倒置**：高层策略是否依赖低层细节？能否依赖接口/契约？
- **正交性**：变更是横向跨模块（容易扩散）还是纵向穿层（容易破坏边界）？
- **API 契约**：对外暴露的是稳定承诺还是临时实现？是否有版本策略？

### 默认追问
- 对外契约是什么：API/事件schema/表结构/配置字段？
- 是否允许破坏性变更？有没有版本兼容策略（v1/v2、双写、双读）？
- 上层代码是否出现基础设施细节（SQL方言、SDK对象、云服务特性）？
- 是否出现"上帝类/上帝函数"跨层协调所有事情？

### 典型反模式提示（用于代码审查/方案评估）
- 业务层直接拼SQL、直接依赖云SDK类型、直接跨服务读写别人的数据库
- 为了"快"把基础设施对象一路透传到Controller/Domain
- 以"内部接口"为名实际对外扩散，后续无法演进

---

## 3️⃣ 熵增（Entropy）——腐烂算子
### 核心定义
代码天然在腐烂——你要评估的不是"现在能跑"，而是"6个月后维护它的痛苦程度"。

### 需要关注的工程问题（不强制量化）
- **可维护性半衰期**：新成员6个月后能否理解？是否依赖隐式知识？
- **Bug Surface**：复杂度、影响范围、新颖度叠加后的缺陷暴露面
- **技术债利息**：现在省下的时间，将来以排障/返工/上线风险的形式偿还
- **Bus Factor**：关键知识是否集中在少数人？

### 默认追问
- 这段改动是否有自动化测试覆盖？（单测/集成/回归）
- 可观测性如何：日志、指标、trace 是否能定位问题？
- 是否存在 TODO/FIXME、临时开关、手工步骤、隐式约定？
- 谁维护/谁值班？关键人是否单点？

### 必出产物（输出中必须出现）
- **熵增评估（概率/成本，允许定性）**
 - 可维护性：高/中/低（理由）
 - 未来风险来源：人员/测试/观测性/变更频率/跨服务联调
 - 成本形态：主要消耗在排障、回滚、联调等待、上下文切换等

---

## 4️⃣ 约束（Constraint）——边界算子
### 核心定义
什么是物理上、法规上、经济上不可能突破的硬边界？——在这些墙内跳舞。

### 需要关注的工程问题
- **可靠性/一致性边界**：CAP 取舍、分布式事务可行性、幂等/重试的边界
- **性能墙**：QPS、P95、带宽、内存、冷启动、网络RTT 等硬限制
- **合规约束**：隐私、审计、数据驻留、等保/SOC2 等强约束
- **交付/预算/人力**：时间窗口、值班能力、运维成熟度

### 默认追问
- 绝对不可协商的约束有哪些？（延迟/可用性/成本/合规/交付期）
- 允许的最差退化是什么？（降级策略、可接受丢失/延迟/不一致）
- 运维能力：CI/CD、回滚、灰度、应急预案是否具备？

### 判定规则（不量化版）
- **触碰硬约束且无替代路径** => 直接否决/先解决前置条件
- **关键链路没有降级/回滚/隔离手段** => 不建议上线

---

## 5️⃣ 依赖（Dependency）——生态算子
### 核心定义
你不是在写代码，你是在加入一个生态——第三方库、云服务、团队能力、标准，谁在控制你的命脉？

### 需要关注的工程问题
- **Supply Chain Risk**：开源依赖的维护活跃度、漏洞响应、许可证风险
- **Vendor Lock-in**：云厂商/中间件绑定，迁移成本与退出策略
- **团队博弈**：是否只有少数人懂？是否偏离团队共识？
- **标准战争**：协议/格式是事实标准还是私货？

### 默认追问
- 引入了哪些新的外部依赖（库/服务/平台能力）？
- 若依赖弃坑/涨价/变更协议，退出路径是什么？
- 团队是否具备运维/排障能力？是否会把复杂度转嫁给值班？

### 必出产物（输出中必须出现）
- **依赖清单（含风险等级）**：依赖项 | 用途 | 风险等级(高/中/低) | 退出/替代路径

---

## 🔄 DevTrace 决策流程（Agent 执行链）
> Agent 在输出前按顺序自检；遇到红线要明确给出"否决/前置条件"。

1. **【拓扑】** 画出改动影响的依赖网络图 → 识别关键路径、故障传播点 
 - 若影响范围不可控且无法隔离：**先解耦再推进**
2. **【抽象】** 检查是否破坏分层边界 → 确保接口与实现分离 
 - 若层间泄漏：**先重构边界/契约再推进**
3. **【熵增】** 估算 6 个月后的维护形态 → 明确风险来源与成本形态 
 - 若腐烂速度明显高于业务价值：**否决或必须预留重构与保障**
4. **【约束】** 列出硬边界 → 判断是否触墙 
 - 若触碰硬墙：**回退寻找替代路径**
5. **【依赖】** 审查第三方/团队/市场依赖 → 给出退出策略 
 - 若存在单点依赖且无法隔离：**否决或增加隔离层/备选方案**

---

## 【否决红线】（任一命中必须明确输出）
- **关键路径故障域扩大** 且没有隔离/降级/回滚可行方案
- **触碰硬约束**（合规/交付期/物理极限/预算）且无替代路径
- **引入单点外部依赖** 且无抽象隔离/无备选/无退出策略
- **抽象层明显泄漏** 导致上层被实现细节绑死，且短期不可修复

---

## ✅ 强制输出格式（每次使用本 skill 必须包含）
> 允许使用要点列表；信息不足时，用"假设/条件化结论"并列出追问。

### 1) 【拓扑图（文字描述）】
- **节点（Nodes）**：列出服务/模块/DB/队列/外部依赖
- **边（Edges）**：A → B（同步/异步、关键参数、超时/重试要点）
- **关键路径（Critical Path）**：入口 → … → 出口（标注最脆弱环节）
- **故障传播点**：哪些失败会扩散？在哪里做隔离/熔断/降级？

### 2) 【熵增评估（概率/成本：允许定性）】
- **可维护性（高/中/低）**：理由（复杂度/隐式知识/跨服务联调/可观测性）
- **6个月后主要风险来源**：人员、测试缺口、观测性、变更频率等
- **成本形态**：排障时间、回滚频率、联调等待、上下文切换、知识传递成本

### 3) 【依赖清单（含风险等级）】
- 依赖项 | 用途 | 风险等级（高/中/低） | 退出/替代路径（一句话）

### 4) 【结论与建议】
- **结论**：建议实施 / 不建议实施 / 建议但需前置条件
- **前置条件（如有）**：必须先完成什么
- **下一步（最多5条）**：按执行顺序给出可落地动作（含"先补什么信息/先做什么保障"）

### 5) 【需要补充的信息】（如适用）
- 列出缺失的问题（优先级从高到低），以便进入下一轮决策

---

## 使用示例（输出风格参考）
**场景：单体拆微服务**

【拓扑图（文字描述）】 
- 节点：Monolith(下单)、Payment、Inventory、DB(OrderDB/PayDB)、MQ、Gateway 
- 边：Gateway→Monolith(同步HTTP)；Monolith→Payment(同步RPC)；Monolith→Inventory(同步RPC)；Payment→PayDB(写)；Monolith→OrderDB(写)；事件：Payment→MQ(PaymentSucceeded)→Monolith(消费) 
- 关键路径：下单→支付→库存扣减（任一步超时会导致整体失败或重试风暴） 
- 故障传播点：Payment超时会触发Monolith重试；MQ堆积会造成订单状态不一致；需要在RPC边界做超时/熔断/降级，并设计幂等

【熵增评估（概率/成本：允许定性）】 
- 可维护性：中→低（跨服务排障、状态机复杂度上升、需要观测性与幂等纪律） 
- 6个月风险来源：微服务治理经验不足、日志/trace不完善、联调成本上升 
- 成本形态：排障与联调等待显著增加；状态不一致导致补偿与人工介入

【依赖清单（含风险等级）】 
- Service Mesh | 流量治理/可观测 | 中 | 可先用轻量网关+客户端重试替代 
- 分布式追踪系统 | 排障定位 | 低 | OpenTelemetry标准化，后端可替换 
- 新消息队列能力 | 事件驱动 | 中 | 抽象消息接口，支持切换Kafka/RabbitMQ等

【结论与建议】 
- 结论：建议但需前置条件（不建议全量一次性拆分） 
- 前置条件：补齐链路追踪/统一日志规范/幂等与重试策略/回滚与灰度能力 
- 下一步： 
 1) 先识别边界上下文与关键路径，选非关键模块试点 
 2) 落地契约版本策略（API/事件schema） 
 3) 建立观测性与故障演练（超时、重试、MQ堆积） 
 4) 小流量灰度 + 可回滚发布 
 5) 逐步扩大范围

【需要补充的信息】 
- 当前关键路径的调用链与超时策略？是否已有统一追踪与日志？团队值班/运维能力现状？

---

## 维护与演进建议（可选）
- 每次使用后，将"触发的红线/前置条件/真实事故反馈"回写到团队知识库（ADR/RFC），迭代算子的默认追问与反模式库。