debug-methodical

Debug-Methodical — 分 4 个阶段进行调试

灵感来自 obra/superpowers。目标： 强制采用严谨的方法，而不是“随机尝试修复，直到问题消失”。

黄金法则： 无法稳定复现的 Bug，说明还没有被真正理解。绝对不要在复现之前修复。

4 个阶段（严格按顺序进行）

阶段 1：REPRODUCE（复现）

目标： 在受控环境中随时复现 Bug。

检查清单：

• 记录复现步骤（Given/When/Then）
• 可确定性复现（连续 >= 3 次结果相同）
• 环境隔离（本地、容器、测试环境）
• 最少输入（尽可能减少数据和步骤）
• 确认准确的版本和 commit

产出： 一个能暴露 Bug 的自动化失败测试（回归测试）。

危险信号：“在我的机器上能运行”/“有时候会失败” → 复现不充分，返回阶段 1。

阶段 2：ISOLATE（隔离）

目标： 找出根本原因，而不只是症状。

技巧：

• 二分定位：使用 git bisect 找出问题 commit
• 代码二分搜索：注释掉一半代码，然后逐步迭代
• 打印调试：在边界处记录日志（函数的输入和输出）
• 调试器：断点、单步执行、监视变量
• 比较环境：“能运行”和“会出错”的环境有哪些差异？
• 质疑前提：最初的假设是否正确？

检查清单：

• 找到原因（准确的代码行、条件或输入）
• 解释为什么（而不只是是什么）
• 记录因果链（A 导致 B，B 导致 C）
• 找出同一 Bug 可能引发的其他表现

危险信号：“我觉得是 X”，但没有证据 → 返回隔离阶段并添加检测手段。

阶段 3：FIX（修复）

目标： 以最小改动修复根本原因。

检查清单：

• 在正确的层级修复（根本原因，而非症状）
• 改动最小化（KISS，参见 rule 05）
• 不影响其他功能
• 不进行“以防万一”的修复或臆测性修复（参见 rule 23 Karpathy）
• 在正确的层级修复（domain / infra / UI）

危险信号：

• 添加 try/catch 来掩盖错误的修复 → 处理的是症状，而非原因
• 需要可疑地修改现有测试的修复
• 不清楚原因却“能用”的修复

阶段 4：VERIFY（验证）

目标： 证明修复有效，且没有破坏其他内容。

检查清单：

• 回归测试（阶段 1）现在通过
• 完整测试套件通过
• 手动复现不再出现 Bug
• 测试相邻场景（相关边缘情况）
• 性能没有下降
• 如果问题严重，在 staging 环境检查日志和监控

回归规则： 阶段 1 编写的测试必须永久保留在代码库中。已修复的 Bug 绝不能再次出现（参见 /qa:regression）。

关键反模式

反模式	为什么不好
Shotgun debugging（乱枪式调试）	随机改 10 处，没有任何收获
修复症状	Bug 会以另一种形式再次出现
跳过复现	无法验证修复
跳过验证	“应该能用”——没有证据就不算完成
没有回归测试	Bug 会在 3 个月后再次出现
使用通用的 catch (Exception) 修复	掩盖其他 Bug
在同一个 commit 中混合修复和重构	git bisect 将无法使用

高级技巧

并发 Bug

• 强制触发不同的交错执行（有策略地 sleep、压力测试）
• 线程转储 / 性能分析器
• 原子地检查不变量

集成 Bug

• 获取准确 payload 的快照（HAR、日志）
• 使用 curl 或最小化客户端复现
• 检查依赖项的准确版本

针对不稳定测试

• 运行 100x，测量不稳定率
• 找出依赖因素（时间、顺序、共享资源）
• 绝不要在没有修复工单的情况下将测试标记为 @Flaky

Claude Craft 集成

• /qa:tdd — 以 TDD 模式修复 Bug（先编写失败的测试）
• /qa:fix — 自动修复 QA 发现的 Bug
• /qa:regression — 回归测试登记表
• Skill atomic-tasks — 将调试拆分为原子阶段
• Rule 07 (testing) — 修复 Bug 必须编写回归测试

资源

• obra/superpowers
• Rule .claude/rules/07-testing.md
• Command /qa:tdd、/qa:regression

---

最后更新日期： 2026-04-15 版本： 1.0.0