入门 约 25 分钟 2026-10-15 02:35:37 · 35 阅读

diagnosing-bugs Agent Skill 实操:先造一条会变红的反馈回路

「Build the right feedback loop, and the bug is 90% fixed.」——造对一条反馈回路,bug 就修好了九成。这句断言写在 diagnosing-bugs 技能 SKILL.md 的 Phase 1 末尾,也是整套方法的重心:拿到一条对这个 bug 能变红的 pass/fail 信号,后面的二分、假设检验、插桩都只是消费这条信号。反过来,没有信号,「no amount of staring at code will save you」——盯着代码看再久也救不了你。这个技能是 mattpocock/skills 仓库 engineering 目录的一员,挂上之后 AI 遇到疑难 bug 或性能退化,会先走完一套六阶段诊断循环才被允许提修复。本篇按 SKILL.md 的结构拆解这套流程,配脱敏纪律、反馈回路构造十式与人机协作模板的真实运行记录。

相关背景见站内 AI 编程总纲。同仓库的 domain-modeling 管设计期的术语沉淀,站内另一套技能库 superpowers 也有个调试技能(Systematic Debugging,四阶段根因调查),两套思路的差异文末单独说。

先立一条纪律:输出的东西先脱敏

SKILL.md 把 Redact 节放在所有阶段之前,因为整个诊断过程要展示命令、输出和抓取的工件,每一步都可能带出密钥。规则三条:每个 secret 先脱敏,原位写 <REDACTED>;回路要对着环境变量构建,让凭证留在环境里而不是留在你展示的东西里;抓取的工件自带 auth 头,只引用携带信号的那几行。脱敏后的输出不够诊断用怎么办?技能的答案很直接:明说,然后去问用户。

六阶段流水线

diagnosing-bugs 六阶段诊断流水线

六阶段与各阶段的完成判据:Phase 1 是技能本体,其余阶段被它称作机械劳动

六个阶段各带闸门:①造反馈回路 ②复现+最小化 ③列假设 ④插桩 ⑤修复+回归测试 ⑥清理。技能开头一句「Skip phases only when explicitly justified」——跳阶段可以,但必须明说理由。开始探索代码库时还有个前置动作:读 GLOSSARY.md(存在的话)建立模块心智模型,翻一翻待改区域的 ADR——这正是同仓库 domain-modeling 技能沉淀下的两份文件,两个技能在这里咬合。

Phase 1 的完成判据是四个勾:能点名一条命令(脚本路径、测试调用或 curl),已经跑过至少一次(展示调用与输出,已脱敏),且满足 Red-capable(跑的是真实 bug 路径、断言用户说的那个症状,修好会变绿)、Deterministic(每次同样结论)、Fast(秒级不是分钟级)、Agent-runnable(无人值守可跑)。SKILL.md 在这里放了一句给 AI 自己看的话:如果发现自己在读代码建理论、而这条命令还不存在——停。「Jumping straight to a hypothesis is the exact failure this skill prevents」,直接跳去假设,正是这个技能要防的那个失败。

十种回路构造法与收紧三问

反馈回路十式优先顺序表

十式按官方给定的优先顺序排列,HITL 脚本是第十式的最后手段

构造回路的十条路由 SKILL.md 按「大致顺序」给出:失败测试优先,curl/HTTP 脚本次之,往下是 CLI 快照 diff、无头浏览器、重放抓包、一次性测试桩、属性/模糊循环、二分测试桩、差分循环,最后才是 HITL 脚本。前五条针对确定性 bug,六到九条各有专门场景——「偶尔输出错」交给一千个随机输入,bug 出现在两个版本之间就交给 git bisect run,新旧版本对 diff 就用差分循环。

回路造出来只是及格,官方要求把它当产品来打磨:能更快吗(缓存 setup、跳过无关初始化、缩小测试范围);信号更尖吗(断言具体症状,不是「没崩」);更确定吗(钉住时间、固定 RNG、隔离文件系统、冻结网络)。量化标尺写在后面那句话里:30 秒的摇摆回路勉强强过没有回路,2 秒且确定的才叫 tight——「a debugging superpower」。

非确定性 bug 的目标被特意改写过:不是干净的复现,而是更高的复现率。循环触发一百次、并行加压、收窄时间窗、注入 sleep。理由给了数字:「A 50%-flake bug is debuggable; 1% is not」——50% 概率的 bug 可调试,1% 的不可调试,所以持续抬高复现率直到可调试为止。真造不出回路时,技能要求停下来明说、列出试过什么,然后向用户要三样东西之一:能复现的环境访问权、脱敏后的工件(HAR、日志、core dump、带时间戳的录屏)、加临时生产插桩的许可。不许在没有回路的情况下进入假设阶段。

复现、假设、插桩:三个阶段的快走

Phase 2 看着回路变红,然后开始砍:输入、调用方、配置、数据、步骤,一次砍一样,砍完重跑。完成判据是「every remaining element is load-bearing」——留下的每个元素都承重,去掉任何一个回路就变绿。官方给的理由很实在:最小化复现收窄了 Phase 3 的假设空间(可怀疑的活动部件变少),而且它就是 Phase 5 那条干净的回归测试。这一阶段还有个容易踩的坑被点名:回路变红时要确认失败模式是用户描述的那个,不是碰巧在旁边的另一个失败——「Wrong bug = wrong fix」。

Phase 3 禁止单假设:「Single-hypothesis generation anchors on the first plausible idea」,先想到一个说得通的就被锚住了。要求一次生成三到五条、排好序、逐条可证伪。每条假设必须能说清预测,格式原文是:

If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse.

说不清预测的假设是「a vibe」(一种感觉),丢弃或磨尖。排序后的清单先给用户看一眼再开测——用户往往一句「我们刚部署过 #3 那个改动」就能瞬间重排,或者直接告诉你哪条早被排除过。便宜的检查点,大的时间节省;用户不在就按自己的排序继续。

Phase 4 插桩的纪律是一次只动一个变量,每个探针对应 Phase 3 的一条预测。工具偏好三级:调试器/REPL 优先(「One breakpoint beats ten logs」,一个断点顶十条日志),其次放在能区分假设的边界上的定向日志,明令禁止「log everything and grep」。所有调试日志必须带唯一前缀,示例给的是 [DEBUG-a4f2]——清理阶段一条 grep 全灭,没打标签的日志会活下来。性能退化走另一条分支:日志通常是错的工具,先建基线测量(计时桩、performance.now()、profiler、查询计划)再二分,「Measure first, fix second」。

修复、接缝与清理

Phase 5 的顺序是回归测试先于修复,但有个前置条件:存在正确的接缝(seam)。正确接缝指测试能在真实调用场景里命中真实的 bug 模式——如果唯一可用的接缝太浅(bug 需要多调用方才能触发,你却只能写单调用方测试),在那里写回归测试只会给出虚假信心。SKILL.md 对这种情况的判定出人意料:「If no correct seam exists, that itself is the finding」——接缝不存在这件事本身就是发现,是代码库架构在阻止这个 bug 被测试锁死,记下来,标记给下一阶段。有接缝时五步走:最小化复现转成失败测试、亲眼看它失败(如果是改代码或夹具强制的红,diff 一份原始副本证明改动落了地)、上修复、看它变绿、再用 Phase 1 的回路对未最小化的原始场景重跑一遍。

Phase 6 的收尾清单五项:原始复现不再复现(重跑 Phase 1 回路);回归测试通过(或接缝缺失已记录);所有 [DEBUG-...] 插桩 grep 删净;一次性原型删除或挪到明确标记的调试位置;命中的那条假设写进 commit 或 PR message——「so the next debugger learns」,让下一个调试的人学到。

第十式实测:HITL 模板脚本

HITL 模板脚本示例与本机实测输出

模板自带的 step/capture 示例与本机运行记录:应答按 KEY=VALUE 原样回收

必须人来点鼠标的场景,技能没有放弃结构化,而是给了 scripts/hitl-loop.template.sh:代理跑脚本,人跟着终端提示走。两个原语分工明确——step "指令" 显示指令等人按 Enter,capture VAR "问题" 把人的回答读进变量、结尾按 KEY=VALUE 打印回去给代理解析。脚本注释里写明了设计意图:capture 的值会打印回终端由代理读取,所以观察类动作用 capture,登录授权类动作用 step 留给人。本机跑了一遍模板自带的两步示例(应答 y 和一条 TypeError 消息),两个变量原样回收、exit 0——顺带验证了非交互输入(应答预先录制成文件)也成立,CI 场景可用。

安装与同库搭配

安装通道与同仓库其它技能一致:Claude Code 用 claude plugin install mattpocock-skills@claude-plugins-official,Codex/Copilot 走各自 marketplace,Gemini CLI 与 cursor 等代理用 npx skills@latest add mattpocock/skills -a cursor,装完每仓库跑一次 /setup-matt-pocock-skills。完整命令与双通道注意事项(plugin 自更新、skills.sh 手动更新、两条路别都装)在同仓库 domain-modeling 篇(id=11155)有逐条展开,此处不重复。

它是 model-invoked 技能:不需要打斜杠命令,用户说「diagnose」「debug this」,或报告有东西坏了、报错、失败、变慢,任务对口时代理自动伸手。

与 superpowers 调试技能的差异

站内已上线的 Systematic Debugging(id=10849)来自另一作者 Jesse Vincent 的 obra/superpowers 仓库,核心是「没查到根因不许提修复」的四阶段调查流程(根因调查、模式分析、假设验证、实施修复)。mattpocock 这套的重心明显不同:不谈根因调查的阶段划分,把全部赌注押在 Phase 1 的反馈回路上——回路对、信号红,九成已赢;后面即便谈假设,谈的也是三到五条排好序、先给用户过目再测,与 superpowers 的单假设深挖路线各有侧重。另外这套的 Redact 节把脱敏立为全程纪律、HITL 脚本把人也纳入循环,都是 superpowers 那边没有的构件。两套并不互斥:一个管「先调查再修」的纪律,一个管「先造回路再查」的方法。

本文步骤与图片依据 mattpocock/skills 仓库官方 README 与 skills/engineering/diagnosing-bugs/SKILL.md、scripts/hitl-loop.template.sh 整理,HITL 运行输出为本机实测记录,版权归原作者所有。

评论 (0)