Systematic Debugging Agent Skill 实操:给 AI 立下「先查根因再修」的铁律
修 bug 先立规矩:没查到根因,一个修复都不许提
让 AI 写代码最气人的时刻不是它写不出来,而是它「修」坏了三次还在第四次跃跃欲试。obra/superpowers 技能库里的 systematic-debugging 就是治这个的:它是一个 Agent Skill,挂上之后,AI 客户端遇到任何 bug、测试失败、意外行为,都会先走完一套四阶段调查流程,拿到根因才被允许动手修。本文依据该技能的 SKILL.md 原文整理,可直接挂到 Claude Code、Cursor、Codex、Gemini CLI 等主流客户端。相关背景见站内 AI 工具导航。
先认识一下出处:obra/superpowers 是 Jesse Vincent 维护的编码代理技能库,覆盖设计、计划、TDD、调试、评审全流程,安装一次全套技能自动触发。站内已有 brainstorming(10409)、requesting-code-review(10798)、subagent-driven-development(10799)等多篇姊妹篇,本篇补上调试这块拼图。
铁律与适用面
SKILL.md 开篇就是一条不容商量的铁律,原文用代码块单独框出:
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
翻译过来:没完成第一阶段(根因调查),就不能提出任何修复。紧接着一句加重的话——「Violating the letter of this process is violating the spirit of debugging」(违反流程的字面就是违反调试的精神)。适用面写得很宽:测试失败、生产 bug、意外行为、性能问题、构建失败、集成问题,全部适用;并特别点名四种越紧张越要用它的场景——时间压力下、直觉说「就一个小修」时、已经试过多个修复时、上一个修复没奏效时。反向清单同样有力:问题看着简单也要走流程(简单 bug 也有根因)、再赶时间也要走流程(原文的账算得很直白:systematic is faster than thrashing,系统化比反复折腾快)、经理催着「现在就修好」也要走流程。
触发方式是全自动的:技能挂在会话上,AI 一遇到技术问题就按这份 SKILL.md 执行,不需要人工喊口令。这也是 Agent Skill 与传统 CLI 工具的区别——它改变的是模型的行为模式,而不是给模型加新命令。
四阶段流水线
整套流程四个阶段,前一阶段没走完不许进下一阶段:

四阶段流水线(依据 skills/systematic-debugging/SKILL.md 绘制)
阶段 1 的动作清单值得逐条记:认真读错误信息(栈要读完整,记下行号、文件路径、错误码——原文说它们「often contain the exact solution」);稳定复现(复现不了就去收集更多数据,不许猜);检查最近变更(git diff、新依赖、配置改动、环境差异)。多组件系统(CI→构建→签名、API→服务→数据库这类链路)还有专门一招:动手修之前先在每个组件边界加日志,记录数据进什么、出什么,跑一遍拿到证据链,定位是哪一层断的。SKILL.md 给了一段四层取证的 shell 示例(workflow 层查环境变量、build 层查 printenv、keychain 层查证书状态、最后 verbose 模式跑签名),思路是「先让证据说话,再谈修复」。
把那段取证示例的骨架拆开看,它演示的是「分层排除」:第一层确认密钥已经在 workflow 环境里(SET 还是 UNSET);第二层确认 build 脚本能不能看到同一个变量(printenv 探测);第三层查看钥匙串与签名身份的状态;第四层才真正带 verbose=4 跑一次签名。原文给这组命令标注的产出是「Which layer fails (secrets → workflow ✓, workflow → build ✗)」——用打勾打叉把断点钉死在某一层。日常排障完全可以套用:Web 应用就把「入口网关→应用日志→数据库查询→外部依赖」当四层,每层先记录进出数据再谈修复。
错误深藏在调用栈里时另有技法:沿栈反向回溯——这个坏值从哪来、谁用它调的这层、一路追到源头,在源头修而不是在症状处修(Fix at source, not at symptom)。SKILL.md 把完整步骤放在同目录的 root-cause-tracing.md。
阶段 2 找模式:在同代码库里找能正常工作的相似实现,对照参考实现要完整读完不许略读,把工作版本与坏版本之间的差异全部列出来——原文强调别假设「这个不可能有影响」。阶段 3 是科学方法:一次只立一个假设(「我认为 X 是根因,因为 Y」),写下来,用最小改动验证,单变量;不成立就换新假设,不许在失败的基础上叠修复。阶段 4 才是动手:先写一个复现 bug 的失败测试(SKILL.md 原话:MUST have before fixing),只修根因一处,不做「顺手改进」,验证测试转绿、无其他测试被带崩。
三次修复失败的熔断条款
这份 SKILL.md 最有意思的是阶段 4 里的熔断设计:修复不奏效就停下来数一数已试了几次。少于 3 次回阶段 1 重新分析;达到 3 次,强制进入架构质疑——如果每次修复都暴露出新的共享状态、新的耦合、别处的新症状,如果修复需要「大规模重构」才能落地,那这不是假设失败,是架构错了。原文的判断句很锋利:Is this pattern fundamentally sound? Are we "sticking with it through sheer inertia"?(是模式本身就不对,还是我们纯粹靠惯性硬撑?)此时必须与人类搭档讨论,而不是尝试第四次修复。
配套的还有两张自查表。Red Flags 表列出 11 条「出现这些念头就停」的想法,从「先快速修一下回头再查」到「已经试了两次,再来一次」;人类搭档信号表则教 AI 识别口风——听到「Stop guessing」「Ultra-think this」这类话,说明当前路线已经偏了,回阶段 1。合理化对照表把八条常见借口逐条驳回:

合理化对照表(译自 SKILL.md Common Rationalizations 一节原文)
给「查无根因」留的出口
流程走完确实查不出根因怎么办?SKILL.md 承认存在这类情况——环境相关、时序相关、外部依赖问题。此时:确认调查已做完整、把调查过什么记录下来、实现恰当的应对(重试/超时/报错信息)、加上监控日志备查。但它同时补了一刀:95% 的「查无根因」其实是调查不彻底。目录里还附了三份支援文档:root-cause-tracing.md(沿调用栈反向回溯的完整技法)、defense-in-depth.md(找到根因后多层加验证)、condition-based-waiting.md(用条件轮询替换拍脑袋的 sleep)。
安装:一条命令的事
Superpowers 以插件形式分发,各客户端的安装命令 README 里给了十七家之多,常用的几条:

八家常用客户端的安装命令(依据仓库根 README Installation 一节整理,全量 17 家见原文)
Claude Code 用户在官方插件市场一条 /plugin install superpowers@claude-plugins-official 完成;Cursor 在 Agent 聊天里输 /add-plugin superpowers;Gemini CLI 用 gemini extensions install https://github.com/obra/superpowers。装完即全局生效——技能按需自动触发,不需要每次手动调用。
验证装没装好,README 的说法是直接开个会话让它修个 bug,观察它是否先走调查流程再提修复;站内 diagnosing-superpowers 篇(10410)另有一套七步诊断法,专查 superpowers 本身装歪了的情况。
日常用起来是什么体感:没有额外命令要记。你照常说「这个接口 500 了帮我看看」,差别在 AI 的第一反应——装了技能的客户端会先复现、先读栈、先问最近改了什么,然后才给结论;没装的多数直接甩一个「可能是缓存问题,清一下试试」。对改 bug 有经验的人,前者省掉的是反复拉扯的轮次;对没经验的人,等于随身带了位按流程办事的老工程师。写代码请求也一样:让 AI「加个重试逻辑」,它会先问你重试几次、什么算失败、要不要退避——这些恰恰是测试要先写清楚的东西。
边界与提醒
如实说局限:其一,这套流程对「改一行配置就好」的小问题也一视同仁地走四阶段,嫌重的读者可以把 SKILL.md 里的 When to Use 当裁剪依据;其二,技能的强制力来自提示词约束,执行者是 LLM,红旗表和熔断条款降低但不消除跳步概率;其三,Hermes Agent 一节的 README 自己注明:长会话压缩后可能丢失引导,技能不再触发时重开会话即可。仓库 296k star、活跃维护,SKILL.md 措辞随版本可能调整,以官方原文为准。
本文依据 obra/superpowers 仓库 skills/systematic-debugging/SKILL.md 与根 README 整理,步骤与引文版权归原作者所有。