告别猜谜式修复：Superpowers系统化调试4阶段法完整拆解，AI找根因不再靠运气-育师

告别猜谜式修复：Superpowers系统化调试4阶段法完整拆解，AI找根因不再靠运气

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers是一个面向 AI 编程助手的技能框架与软件开发方法论，其中的系统化调试（Systematic Debugging）技能用一套 4 阶段流程强制 AI 先找根因、再动手修复，让根因分析不再靠运气。今天带你完整拆解这套调试方法，并教你让 AI 在遇到 Bug、测试失败或异常行为时自动遵循它 🔧

为什么"猜谜式修复"最坑？

你有没有见过 AI 助手这样修 Bug：改一行 → 不行 → 再改一行 → 又改一行……每次改动都"看起来合理"，但问题要么没修好，要么在别处冒出新问题。

Superpowers 把这称为症状修复（Symptom Fixes），并把它定为调试失败的标志。整个技能的第一条铁律写得很直白：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST未完成根因调查之前，不许提出任何修复。

这条规则在 SKILL.md 中被反复强调——不是"建议"，而是"强制工作流"。

4 阶段法总览：从"猜"到"证"

这套方法论把调试拆成 4 个必须按顺序完成的阶段：

阶段	关键活动	成功标准
1️⃣ 根因调查	读错误信息、稳定复现、查近期改动、收集证据	理解"是什么"和"为什么"
2️⃣ 模式分析	找能跑通的相似代码，对比差异	找出差异点
3️⃣ 假设与验证	提出单一假设，做最小化测试	假设被证实或推翻
4️⃣ 实施修复	先写失败测试，再单点修复并验证	Bug 解决、测试通过

下面逐一拆解。

阶段 1：根因调查——修之前先"取证"

这是最容易被跳过、却最值钱的一步。SKILL.md 给出了 5 个具体动作：

逐字读错误信息：错误消息里往往就藏着答案，堆栈跟踪要读完，记下行号、文件路径、错误码
稳定复现：能可靠触发吗？如果不能复现，先去收集更多数据，而不是猜
检查近期改动：git diff、最近提交、新依赖、配置变化、环境差异
在组件边界收集证据：多组件系统（比如 API → 服务 → 数据库）中，先在每个边界处记录"进入什么数据、出去什么数据"，跑一遍就能定位断在哪一层
追溯数据流：错误出现在调用栈深处时，向上追"坏值是从哪来的"，在源头修，不在症状处修

阶段 2：模式分析——先找"好榜样"

在同一代码库里找能正常工作的相似代码
如果是实现某个模式，完整读参考实现（不要扫一眼就套用）
列出正常与异常之间的每一处差异，再小也不假设"它应该不影响"
弄清依赖：需要哪些配置、环境、隐含假设？

阶段 3：假设与验证——科学方法上 AI 课

这一步借鉴科学实验法，核心是"一次只动一个变量"：

只提一个假设，并写下来："我认为 X 是根因，因为 Y"
最小化测试：做能验证假设的最小改动，不要同时修多处
验证后再前进：不行就回到阶段 1 提新假设，而不是在旧修复上叠新修复
不知道就直说：承认"我不理解 X"，去查资料，而不是装懂硬改

技能文档里还专门列了一张"合理化借口表"，比如"问题很简单不用走流程""先随便试一下再调查"——每个借口旁边都写了对应的现实反驳，专治各种"偷懒冲动" 🎯

阶段 4：实施修复——先写失败测试，再动刀

先创建失败测试用例：最简复现，能自动化就自动化，修复前必须存在
单点修复：只针对根因做一次改动，不顺手重构、不"while I'm here"
验证修复：测试通过了吗？其他测试没坏吗？问题真的解决了吗？

还有一个很少见但很硬核的规则：连续 3 次修复失败，停下来质疑架构。如果每次修复都在别处暴露新问题，说明不是"假设错了"，而是"架构错了"——此时应与人类搭档讨论，而不是尝试第 4 次修复。

配套工具箱：4 个实用调试技巧

systematic-debugging 目录里还内置了 3 个配套技术文档和 1 个脚本，都是实战沉淀：

技巧	解决什么问题	资料位置
根因追溯	错误藏在调用栈深处，向上追到最初触发点	root-cause-tracing.md
纵深防御	找到根因后，在每一层都加校验，让 Bug 结构性不可能复现	defense-in-depth.md
条件等待	消灭`sleep(500)`猜时间导致的 flaky 测试	condition-based-waiting.md
污染测试二分查找	不知道哪个测试污染了环境？逐个跑，锁定"肇事者"	find-polluter.sh

其中 defense-in-depth.md 来自真实调试会话：一个空字符串让git init跑进了源码目录，修复后团队在入口、业务逻辑、环境守卫、调试日志 4 个层次各加一道校验，最终 1847 个测试全部通过，Bug 无法复现——不是"修好了"，而是"修到不可能再坏"。

而 CREATION-LOG.md 更记录了这套技能如何被"压力测试"：作者设计了 4 个验证场景（无压力、时间紧迫+看似简单的快捷修复、复杂系统、首次修复失败），AI 在全部场景中都没有走捷径，完整执行了流程。

修完之后：声明"修好了"之前先验证

Superpowers 还配了一个姊妹技能 verification-before-completion，铁律同样干脆：没有新鲜的验证证据，不许宣称完成。"应该好了""看起来没问题"都算红线——必须真跑一遍验证命令、读完输出、确认退出码，然后带着证据宣布修复成功。

如何让你的 AI 助手用上这套调试法

这套技能位于 skills/systematic-debugging/ 目录，安装 Superpowers 后（支持 Claude Code、Cursor、Codex、Gemini CLI、Kimi Code 等多种 AI 编程工具，安装方式见 README.md），它会自动触发——当 AI 遇到测试失败、生产 Bug、异常行为时，无需你专门下达指令就会先走根因调查。

如果你更想显式调用，直接对 AI 说一句即可：