Superpowers Systematic Debugging

Superpowers 系统性调试

核心准则

随机修 bug 浪费时间内制造新 bug。快速补丁掩盖根本问题。

核心原则：永远先找根本原因再尝试修复。症状修复 = 失败。

违反调试流程的字面意思 = 违反调试流程的精神。

铁律

未经根本原因调查，不许修复

如果没完成第 1 阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

• 测试失败
• 生产 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

特别要用于：

• 时间压力大时（紧急情况容易猜）
• "就一个快速修复"看起来很明显时
• 已经尝试了多个修复时
• 上次修复没用时
• 没有完全理解问题时

四阶段流程

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 通常包含准确解决方案
   • 读完堆栈跟踪
   • 记下行号、文件路径、错误码

2. 稳定复现

   • 能可靠地触发吗？
   • 具体步骤是什么？
   • 每次都发生吗？
   • 如果不能复现 → 收集更多数据，不要猜

3. 检查最近变更

   • 什么变更可能导致这个？
   • Git diff、最近提交
   • 新依赖、配置变更
   • 环境差异

4. 追踪数据流

   当错误在调用栈深处：

   • 坏值从哪里产生？
   • 什么调用时传入了坏值？
   • 一直追踪到找到源头
   • 在源头修复，不是在症状处

阶段 2：模式分析

修复前找到模式：

1. 找类似工作的例子

   • 在同一代码库找类似正常工作的代码
   • 什么能正常工作而什么坏了？

2. 对比参考

   • 如果在实现某个模式，彻底读完参考实现
   • 不要略读——每一行都要读
   • 应用前完全理解模式

3. 识别差异

   • 工作的和坏的区别是什么？
   • 列出每个差异，不管多小
   • 不要假设"那个不重要"

4. 理解依赖

   • 这个还需要什么其他组件？
   • 什么设置、配置、环境？
   • 它做什么假设？

阶段 3：假设与测试

科学方法：

1. 形成一个假设

   • 清晰陈述："我认为 X 是根本原因，因为 Y"
   • 写下来
   • 要具体，不要模糊

2. 最小化测试

   • 做最小可能的变更来测试假设
   • 一次只改一个变量
   • 不要一次修多个东西

3. 验证后再继续

   • 有效？→ 阶段 4
   • 无效？→ 形成新假设
   • 不要在顶上加更多修复

4. 当不知道时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 做更多研究

阶段 4：实现

修复根本原因，不修复症状：

1. 创建失败的测试用例

   • 最简单的复现方式
   • 能自动化就自动化
   • 修复前必须有
   • 用 superpowers-tdd 技能写正确的失败测试

2. 实现单一修复

   • 解决识别的根本原因
   • 一次改一个
   • 不要"既然在这里"就改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在通过了吗？
   • 其他测试坏了吗？
   • 问题真的解决了吗？

4. 如果修复没用

   • 停止
   • 数：已经尝试了多少次修复？
   • 如果 < 3：回到阶段 1，用新信息重新分析
   • 如果 ≥ 3：停止并质疑架构（见下）
   • 没有架构讨论不要再尝试修复 #4

5. 如果 3+ 修复都失败：质疑架构

   表明架构问题的模式：

   • 每个修复在不同地方揭示新的共享状态/耦合/问题
   • 修复需要"大规模重构"才能实现
   • 每个修复在其他地方产生新症状

   停止并质疑基本原理：

   • 这个模式根本上是合理的吗？
   • 我们是在"靠惯性坚持"吗？
   • 应该是重构架构还是继续修症状？

   在尝试更多修复之前与主人讨论

红旗

如果发现自己想：

• "先快速修复，以后再调查"
• "就试试改 X 看看行不行"
• "加多个变更，一起跑测试"
• "跳过测试，我手动验证"
• "大概是 X，让我修那个"
• "我没有完全理解但这可能行"
• "再试一次修复"（已经尝试了 2+ 次）
• 每个修复在不同地方揭示新问题

所有这些意味着：停止。回到阶段 1。

如果 3+ 修复失败： 质疑架构。

主人发出的信号（你在做错）

• "那没有发生吗？" - 你假定了没有验证
• "这会告诉我们……？" - 应该加了证据收集
• "别猜了" - 你在没理解的情况下提修复
• "再想清楚" - 质疑基本原理，不只是症状

看到这些时： 停止。回到阶段 1。

快速参考

当过程显示"没有根本原因"时

如果系统性调查发现问题是真正环境相关、时序相关或外部的：

1. 已完成调查流程
2. 记录调查了什么
3. 实现适当处理（重试、超时、错误信息）
4. 为未来调查添加监控/日志

但是： 95% 的"没有根本原因"是调查不完整。