Skill: kings0527/devtrace (version 1.0.0)

# DevTrace 技术决策五算子（Agent Skill） **skill_name:** [REDACTED_SECRET] **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），迭代算子的默认追问与反模式库。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)