Superpowers 系统性调试

---

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 阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

**特别要用于：**

四阶段流程

阶段 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+ 修复都失败：质疑架构**

**表明架构问题的模式：**

- 每个修复在不同地方揭示新的共享状态/耦合/问题

- 修复需要"大规模重构"才能实现

- 每个修复在其他地方产生新症状

**停止并质疑基本原理：**

- 这个模式根本上是合理的吗？

- 我们是在"靠惯性坚持"吗？

- 应该是重构架构还是继续修症状？

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

红旗

如果发现自己想：

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

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

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

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

快速参考

| 阶段 | 关键活动 | 成功标准 |

|------|---------|---------|

| **1. 根本原因** | 读错误，复现，检查变更，收集证据 | 理解了什么和为什么 |

| **2. 模式** | 找工作例子，对比 | 识别差异 |

| **3. 假设** | 形成理论，最小测试 | 确认或新假设 |

| **4. 实现** | 创建测试，修复，验证 | Bug 解决，测试通过 |

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

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

1. 已完成调查流程

2. 记录调查了什么

3. 实现适当处理（重试、超时、错误信息）

4. 为未来调查添加监控/日志

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