Debug-Methodical 是一个调试技能，灵感来自 obra/superpowers。它的目标是强制采用一套严谨的方法，而不是“随机尝试各种修复直到碰巧能用”。
核心规则：没有稳定复现的 bug 就是没被真正理解的 bug。绝不能在复现之前动手修复。
该技能包含四个严格按顺序执行的阶段。
第一阶段：REPRODUCE（复现） 目标是在受控环境中随意触发该 bug。 检查清单：记录复现步骤（Given/When/Then）；确定性复现（连续至少 3 次运行结果一致）；隔离环境（本地、容器、测试环境）；最小输入（尽可能少的数据和步骤）；确定确切的版本/提交。 产出：一个能暴露该 bug 的失败自动化测试（回归测试）。 红色信号：“在我机器上是好的”或“有时会失败”，说明复现不充分，返回第一阶段。
第二阶段：ISOLATE（隔离） 目标是找到根本原因，而不只是症状。 技术手段：使用 git bisect 找到出错的提交；在代码中二分查找（注释掉一半再迭代）；打印驱动调试（在函数输入/输出边界加日志）；调试器（断点、单步执行、变量监视）；对比环境差异（“能工作”和“会失败”之间有什么不同）；质疑前提（最初的假设是否正确）。 检查清单：确定原因（确切的行/条件/输入）；解释为什么（而不只是是什么）；记录因果链（A 导致 B 导致 C）；识别同一 bug 的其他潜在表现。 红色信号：“我觉得是 X”但没有证据，返回隔离阶段并加装检测手段。
第三阶段：FIX（修复） 目标是以最小改动修复根本原因。 检查清单：在正确层级修复（根本原因而非症状）；最小改动（KISS 原则）；不对其他功能产生副作用；不做“以防万一”或推测性的修复；在正确的层修复（领域/基础设施/UI）。 红色信号：通过加 try/catch 掩盖错误的修复，是在处理症状而非原因；需要可疑地修改现有测试的修复；修复“能用”但不知道为什么。
第四阶段：VERIFY（验证） 目标是证明修复有效且没有破坏其他东西。 检查清单：第一阶段的回归测试现在通过；完整测试套件通过；手动复现不再出现该 bug；测试相邻场景（相近的边界情况）；性能未下降；关键场景在预发布环境检查日志/监控。 回归规则：第一阶段编写的测试永久保留在代码库中。已修复的 bug 绝不应再次出现。
关键反模式：散弹式调试（随机改十处，毫无学习）；修复症状（bug 以另一种形式回归）；跳过复现（修复无法验证）；跳过验证（“应该能行”——没有证据就没完成）；没有回归测试（bug 三个月后重现）；使用通用 catch (Exception) 的修复（掩盖其他 bug）；提交混合了修复与重构（导致 git bisect 无法进行）。
高级技术： 并发 bug：强制交错执行（策略性 sleep、压力测试）；线程转储/分析器；原子地验证不变量。 集成 bug：快照确切的载荷（HAR、日志）；用 curl 或最小客户端复现；验证依赖的确切版本。 不稳定测试：运行 100 次以测量不稳定率；识别依赖（时间、顺序、共享资源）；绝不在没有修复工单的情况下将测试标记为 @Flaky。
与 Claude Craft 的集成：/qa:tdd（以 TDD 模式修复 bug，先写失败测试）；/qa:fix（自动化修复 QA bug）；/qa:regression（回归测试登记）；Skill atomic-tasks（将调试拆分为原子阶段）；Rule 07（测试）——bug 修复必须附带回归测试。
资源：obra/superpowers；Rule .claude/rules/07-testing.md；命令 /qa:tdd、/qa:regression。
最后更新日期：2026-04-15；版本：1.0.0。