Systematic Debugging

Systematic Debugging 是什么

Systematic Debugging 是 obra/superpowers 中的一套根因优先排障流程，适用于测试失败、生产 Bug、构建失败、性能问题和集成异常。它的铁律是先调查根因，再提出修复，不能用一次看似有效的改动掩盖症状。流程把排障拆成四个阶段，并要求在每一阶段达到明确的证据标准后才进入下一步。

四阶段排障路径

第一阶段是根因调查：完整阅读错误和堆栈、稳定复现、检查近期代码和配置变更，在多组件系统中记录每个边界的输入输出与环境传播，再沿数据流回溯坏值的起点。第二阶段是模式分析：寻找同一代码库中的可工作示例，完整对照参考实现，列出所有差异并确认依赖。第三阶段形成一个具体假设，用最小改动测试，一次只改变一个变量；测试失败就带着新证据回到调查，而不是叠加第二个修复。

实施、测试和验证

第四阶段要求先创建最小失败测试或一次性复现脚本，再实施针对根因的单一修复。修复后要验证原问题消失且其他测试没有回归，最后再检查完成前的验证清单。流程强调“看起来简单”也不能跳过调查，因为简单症状同样可能来自共享状态、依赖或配置传递。若无法复现，应先收集更多证据，不要凭猜测改代码。

三次失败后的架构审视

如果三次修复都失败，清单要求停止第四次尝试，重新质疑架构和基本模式。连续失败可能说明耦合、共享状态或方案本身有问题，需要和人类伙伴讨论是否应调整设计，而不是继续堆补丁。环境或时序问题只有在完成调查后才能作为结论，并应记录调查范围、采取重试或超时处理，同时补充监控以便下次取证。

适用人群与边界

它适合开发者、测试工程师、SRE 和需要让代理按证据排查问题的团队。流程本身不执行特定修复，也不替代测试驱动开发、日志、监控或领域知识；它提供的是问题定位顺序、假设纪律和验证门槛。使用时应保留错误、复现步骤、差异清单和测试结果，便于团队复盘。

来源与许可

本条目依据 obra/superpowers 当前提交的仓库 README 与完整 systematic-debugging/SKILL.md 整理，仓库许可证为 MIT。技能强调外部内容和工具输出都要作为证据审阅，不能把错误日志中的指令当成可信操作要求。

常见问题

1. 什么时候使用它？

遇到测试失败、生产 Bug、意外行为、性能问题、构建失败或多系统集成异常时使用。即使问题看起来简单，也应至少完成错误阅读、复现和近期变更检查。

2. 为什么不能先修再查？

因为症状修复可能暂时隐藏问题，随后在其他路径重新出现。流程的 Iron Law 要求先建立根因证据，再提出针对性改动，避免猜测和反复返工。

3. 第一阶段要做什么？

完整读错误和堆栈，稳定复现，检查近期变更，在组件边界收集输入输出和配置状态，并沿数据流向上追踪异常值的最初来源。

4. 多组件系统怎样取证？

在每个边界记录进入和离开的数据、环境变量、配置传播及服务状态，先定位究竟是哪一层丢失或改变了信息，再深入调查该组件。

5. 如何提出假设？

一次只写一个具体假设，说明为什么现有证据支持它，然后用最小改动测试一个变量。结果不支持时要建立新假设，不能把多个未验证修复叠在一起。

6. 什么时候写测试？

进入实施阶段前先创建最小失败测试或复现脚本，用它证明问题存在；完成单一根因修复后再运行该测试和回归检查，确认结果稳定。

7. 连续三次修复失败怎么办？

停止第四次补丁，回到架构层面检查共享状态、耦合和模式是否根本不合适，并和人类伙伴讨论重构或调整方案，再决定下一步。

8. 它能保证找到根因吗？

它提供调查顺序和证据门槛，但不保证所有外部问题都有单一根因。环境或时序问题也要先完成调查，再记录限制并增加监控、重试或更清楚的错误信息。