| name | superpowers-systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior. Enforces
systematic four-phase debugging: root cause investigation, pattern analysis,
hypothesis testing, and evidence-based fix verification.
|
Superpowers 系统性调试
核心准则
随机修 bug 浪费时间内制造新 bug。快速补丁掩盖根本问题。
核心原则：永远先找根本原因再尝试修复。症状修复 = 失败。
违反调试流程的字面意思 = 违反调试流程的精神。
铁律
未经根本原因调查，不许修复
如果没完成第 1 阶段，就不能提出修复方案。
何时使用
用于任何技术问题：
- 测试失败
- 生产 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
特别要用于：
- 时间压力大时（紧急情况容易猜）
- "就一个快速修复"看起来很明显时
- 已经尝试了多个修复时
- 上次修复没用时
- 没有完全理解问题时
四阶段流程
阶段 1：根本原因调查
在尝试任何修复之前：
-
仔细阅读错误信息
- 不要跳过错误或警告
- 通常包含准确解决方案
- 读完堆栈跟踪
- 记下行号、文件路径、错误码
-
稳定复现
- 能可靠地触发吗？
- 具体步骤是什么？
- 每次都发生吗？
- 如果不能复现 → 收集更多数据，不要猜
-
检查最近变更
- 什么变更可能导致这个？
- Git diff、最近提交
- 新依赖、配置变更
- 环境差异
-
追踪数据流
当错误在调用栈深处：
- 坏值从哪里产生？
- 什么调用时传入了坏值？
- 一直追踪到找到源头
- 在源头修复，不是在症状处
阶段 2：模式分析
修复前找到模式：
-
找类似工作的例子
- 在同一代码库找类似正常工作的代码
- 什么能正常工作而什么坏了？
-
对比参考
- 如果在实现某个模式，彻底读完参考实现
- 不要略读——每一行都要读
- 应用前完全理解模式
-
识别差异
- 工作的和坏的区别是什么？
- 列出每个差异，不管多小
- 不要假设"那个不重要"
-
理解依赖
- 这个还需要什么其他组件？
- 什么设置、配置、环境？
- 它做什么假设？
阶段 3：假设与测试
科学方法：
-
形成一个假设
- 清晰陈述："我认为 X 是根本原因，因为 Y"
- 写下来
- 要具体，不要模糊
-
最小化测试
- 做最小可能的变更来测试假设
- 一次只改一个变量
- 不要一次修多个东西
-
验证后再继续
- 有效？→ 阶段 4
- 无效？→ 形成新假设
- 不要在顶上加更多修复
-
当不知道时
- 说"我不理解 X"
- 不要假装知道
- 寻求帮助
- 做更多研究
阶段 4：实现
修复根本原因，不修复症状：
-
创建失败的测试用例
- 最简单的复现方式
- 能自动化就自动化
- 修复前必须有
- 用
superpowers-tdd 技能写正确的失败测试
-
实现单一修复
- 解决识别的根本原因
- 一次改一个
- 不要"既然在这里"就改进
- 不要捆绑重构
-
验证修复
- 测试现在通过了吗？
- 其他测试坏了吗？
- 问题真的解决了吗？
-
如果修复没用
- 停止
- 数：已经尝试了多少次修复？
- 如果 < 3：回到阶段 1，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（见下）
- 没有架构讨论不要再尝试修复 #4
-
如果 3+ 修复都失败：质疑架构
表明架构问题的模式：
- 每个修复在不同地方揭示新的共享状态/耦合/问题
- 修复需要"大规模重构"才能实现
- 每个修复在其他地方产生新症状
停止并质疑基本原理：
- 这个模式根本上是合理的吗？
- 我们是在"靠惯性坚持"吗？
- 应该是重构架构还是继续修症状？
在尝试更多修复之前与主人讨论
红旗
如果发现自己想：
- "先快速修复，以后再调查"
- "就试试改 X 看看行不行"
- "加多个变更，一起跑测试"
- "跳过测试，我手动验证"
- "大概是 X，让我修那个"
- "我没有完全理解但这可能行"
- "再试一次修复"（已经尝试了 2+ 次）
- 每个修复在不同地方揭示新问题
所有这些意味着：停止。回到阶段 1。
如果 3+ 修复失败： 质疑架构。
主人发出的信号（你在做错）
- "那没有发生吗？" - 你假定了没有验证
- "这会告诉我们……？" - 应该加了证据收集
- "别猜了" - 你在没理解的情况下提修复
- "再想清楚" - 质疑基本原理，不只是症状
看到这些时： 停止。回到阶段 1。
快速参考
| 阶段 | 关键活动 | 成功标准 |
|---|
| 1. 根本原因 | 读错误，复现，检查变更，收集证据 | 理解了什么和为什么 |
| 2. 模式 | 找工作例子，对比 | 识别差异 |
| 3. 假设 | 形成理论，最小测试 | 确认或新假设 |
| 4. 实现 | 创建测试，修复，验证 | Bug 解决，测试通过 |
当过程显示"没有根本原因"时
如果系统性调查发现问题是真正环境相关、时序相关或外部的：
- 已完成调查流程
- 记录调查了什么
- 实现适当处理（重试、超时、错误信息）
- 为未来调查添加监控/日志
但是： 95% 的"没有根本原因"是调查不完整。
