ClawHub

DevTrace - 技术决策五算子

Other

为技术决策提供依赖拓扑、抽象分层、腐烂风险、硬约束与生态依赖的系统性自检与评估框架，辅助架构与选型判断。

Install

openclaw skills install devtrace

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

【否决红线】（任一命中必须明确输出）

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

✅ 强制输出格式（每次使用本 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），迭代算子的默认追问与反模式库。