DevTrace - 技术决策五算子

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

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "DevTrace - 技术决策五算子" with this command: npx skills add kings0527/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），迭代算子的默认追问与反模式库。

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

Trunkate AI

Semantically optimizes context history and large text blocks via the Trunkate AI API. Includes proactive context pruning hooks for automated token management.

Registry SourceRecently Updated
140engineering-trunkate-ai
General

Long-term Task Progress Manager

Manages multi-session, multi-stage projects by maintaining and syncing MISSION.md, PROGRESS.md, and NEXT_STEPS.md for seamless long-term progress tracking.

Registry SourceRecently Updated
10bono5137
General

Event Planner Pro

活动策划助手。活动方案(婚礼/生日/年会)、预算编制、准备清单、邀请函文案、时间轴、供应商清单。Event planner for weddings, birthdays, corporate events with budgets, checklists, invitations, timelines. 活动策...

Registry SourceRecently Updated
1241bytesagain
General

Trigger

Trigger - command-line tool for everyday use

Registry SourceRecently Updated
420ckchzh