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,团队复盘用。
• “根因”不是”症状”——连接池满不是根因,慢查询/慢下游是根因。多问一个”为什么”。

常见问题 FAQ

Q1: diagnose 适合哪些编程语言?

A: diagnose 通常支持主流编程语言(Python、JavaScript/TypeScript、Java、Go、C++、Rust 等)。支持程度因语言而异:Python/JavaScript/TypeScript 最佳,小众语言(如 Haskell、Elixir)可能较弱。

Q2: diagnose 生成的代码可以直接用吗?

A: 简单的 CRUD、工具函数、单元测试可以直接用;复杂的业务逻辑、算法实现需要人工 review。永远不要盲目复制 AI 生成的代码——先理解再使用。

Q3: diagnose 怎么收费?

A: 通常分免费版(基础功能,有限次数)、付费版(高级模型、无限次数、团队协作)。个人开发者 Pro 版约 $10-20/月,企业版 $30-50/用户/月。具体以 https://github.com/mattpocock/skills 定价为准。

Q4: diagnose 会上传我的代码到云端吗?有隐私问题吗?

A: 大部分 AI 编程工具会保存你的代码用于服务提供(模型推理)和模型改进(除非关闭)。敏感代码(企业核心、商业秘密)建议:1) 使用本地部署版本;2) 关闭”使用我的代码改进模型”选项;3) 考虑企业版(有更强隐私保护)。

Q5: 怎么让 diagnose 生成更高质量的代码?

A: 关键技巧:1) 写清晰的 prompt,说明输入输出和约束;2) 提供代码示例(让 AI 学习你的风格);3) 拆分任务,不要一次生成太多;4) 用 TODO 注释让 AI 补充具体实现;5) review + 单元测试保证质量。

进阶学习建议

如果想进一步用好 diagnose,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/mattpocock/skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 仓库主页:https://github.com/mattpocock/skills
• Matt Pocock 个人站:https://www.mattpocock.com/
• 《Debugging: The 9 Indispensable Rules》:https://debuggingbook.com/
• 分布式追踪 OpenTelemetry:https://opentelemetry.io/
• pprof 文档:https://github.com/google/pprof
• 相关 Skill:tdd、grill-me、security-auditor

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