diagnose — 结构化调试,拒绝乱试代码

diagnose 快速入门

用科学方法调 Bug:先假设,再找证据,再下结论,最后改代码——告别乱试。

这是什么?解决什么问题?

调 Bug 的”民间方法”通常是:猜。“我猜是 X 引起的,改改看”,不行再改改看,改到放弃或撞大运。这种方法在 5-10 行代码里能行,在 5 万-10 万行的系统里几乎注定失败。 Matt Pocock 的 diagnose Skill 把”科学调试法”打包成可被 AI 严格执行的流程:

1. 复现:把 bug 稳定复现成最小用例;
2. 观察:收集日志、变量值、调用栈,记录实际发生了什么;
3. 假设:基于观察提出若干”如果……那么……”的假设;
4. 验证:用最小实验(打印、断点、单元测试)逐一排除或证实;
5. 根因:找到那个”满足所有观察”的唯一解释;
6. 修复:改最小代码并加回归测试。 AI 在开启 diagnose 后,不允许直接动业务代码,必须先走完 1-5 步,得到清晰的根因报告后,才动第 6 步。这避免了大量”改了 5 个地方,bug 突然消失,但你不知道是哪个改好的”。 适合:中级以上工程师、复杂业务系统维护、on-call 同学。

准备工作

• 一个支持 SKILL.md 的 agent
• 一段有 bug 的代码 + 报错信息
• 5 分钟时间
• 一颗不浮躁的心(诊断不是改代码,慢一点)

3 步快速上手

第 1 步:克隆并软链

git clone https://github.com/mattpocock/skills.git
ln -sf "$(pwd)/skills/diagnose" ~/.claude/skills/diagnose

OpenCode 用户把目标路径改为 ~/.config/opencode/skills/,Cursor 用户改为 ~/.cursor/skills/。

第 2 步:验证 Skill 加载

ls ~/.claude/skills/diagnose/SKILL.md
head -30 ~/.claude/skills/diagnose/SKILL.md

应当能看到”复现 / 观察 / 假设 / 验证 / 根因 / 修复”6 个阶段。重启 agent,/skills list 看到 diagnose 即 OK。

第 3 步:用 Skill 调第一个真实 Bug

准备一个 bug 场景(下面给一个示范)。在 agent 对话里说:

[开 diagnose]
我的 Node.js 服务在收到 POST /api/login 请求时偶尔返回 502,
成功率和时间相关,白天 95% 晚上 30%。日志只有一行 upstream timeout。
请按 diagnose 流程帮我定位。

观察 AI 行为:

• 第 1 步,它会问”先复现,你能不能在测试环境稳定触发”或者”贴一段请求复现脚本”;
• 第 2 步,它会建议”在 4 个关键节点加日志”或”用 distributed trace”;
• 第 3 步,它会列出 3-5 个候选假设(下游慢 / 缓存击穿 / GC 暂停 / DNS 抖动 / 连接池耗尽);
• 第 4 步,它会为每个假设设计一个”一次只动一个变量”的实验;
• 第 5-6 步,在你确认根因后再改代码并加回归测试。 重点:AI 在第 5 步前不会动业务代码,这是这个 Skill 的精髓。

常见踩坑

1. 跳过第 1 步”复现”:很多人直接说”线上有 bug 快调”,AI 拿不到最小复现,只能瞎猜。坚持”先复现再诊断”。
2. 假设列得太少:3 个假设里几乎一定有一个是真因,列 5-8 个才稳,Skill 会主动催你”再列几个”。
3. 验证实验一次动了两个变量:“我把超时从 3s 改成 5s,又重启了 2 台机器”——这种实验 0 信息量。Skill 会要求你一次只改一个变量。
4. 不收集证据就改代码:看到 502 就直接重试/加超时,根因没找到。Skill 会一直停在”假设/验证”阶段。
5. 根因找到后”顺便”重构:诊断归诊断,重构归重构,混在一起会引入新 bug。Skill 会要求先 fix,另开 PR 重构。
6. 回归测试不写:“我改完没复现了” 不算 fix,必须有自动化测试覆盖这个 case,Skill 会强制要求。

初级用法

• 复现本地 bug:把生产报错信息贴进对话,先让 AI 帮你写一个最小复现脚本,再走诊断。
• Code Review 找潜在 bug:对一段新写的代码,跑 diagnose 的”假设”步骤,看 AI 能不能列出 5 个潜在失败模式。

高级玩法

• 跨服务调用链诊断:把 trace_id 喂给 AI,让它同时看 4 个服务的日志,做”分布式”诊断。
• 配合火焰图/Profiler:把 pprof 输出、火焰图 SVG 一起贴进去,AI 能直接看到热点函数,跳过大量猜测。
• 知识库沉淀:把”根因报告”自动归档到 Notion / 飞书,长期形成”故障案例库”,新人入职直接看。

小技巧

• 假设阶段写”如果……那么……”句式,而不是”可能是 X”,后者不可证伪。
• 验证实验的代码,记得在 git stash 后写,失败能秒回退。
• 一次只跑一个 Skill,不要同时开 tdd + diagnose,会冲突。
• 写完根因报告后,顺手写一个 POSTMORTEM.md,记录时间线、影响、根因、Action Items,团队复盘用。
• “根因”不是”症状”——连接池满不是根因,慢查询/慢下游是根因。多问一个”为什么”。

参考链接

• 仓库主页
• Matt Pocock 个人站
• 《Debugging: The 9 Indispensable Rules》
• 分布式追踪 OpenTelemetry
• pprof 文档
• 相关 Skill:tdd、grill-me、security-auditor

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。