diagnosing-bugs:插件完全指南,从安装到实战的结构化调试利器

写代码的人都知道，最难的不是写新功能，是修那些藏得极深的 Bug。尤其是那种时好时坏、无法稳定复现的“幽灵 Bug”——你盯着屏幕看了半天，改了几处代码，问题还在；又改了几处，问题好像没了，但过两天又冒出来了。

Matt Pocock 开发的 diagnosing-bugs 技能，正是为了解决这类问题而生的。它不是传统意义上的 IDE 插件，而是一个可以加载到 Claude Code、Cursor、Windsurf 等 AI 编程助手里的工作流技能。截至目前，它在 GitHub 上已经获得了超过 18 万 Star。

这篇文章会把 diagnosing-bugs 是什么、怎么装、怎么用，以及它到底能解决什么问题，一次性讲清楚。

一、Diagnosing-Bugs 是什么

diagnosing-bugs 是一套结构化的调试流程规范。它把调试硬 Bug 和性能回归的过程拆解成六个强制阶段，AI 助手在它的引导下，会按顺序执行：构建反馈环、复现并最小化、提出假设、添加日志定位、修复并添加回归测试、清理与复盘。

这个技能的核心原则只有一句话：在没有一个能稳定复现 Bug 的命令之前，不要开始猜原因。

很多开发者（包括 AI 助手）看到报错后的第一反应是“这段代码可能有问题”，然后直接动手改。但 diagnosing-bugs 会强制你停下来，先做一个能准确捕获当前 Bug 的反馈环——可以是一条失败的测试、一段 curl 命令、一个 Playwright 脚本，或者任何能让 Bug 稳定“现形”的东西。

反馈环是 diagnosing-bugs 里最核心的概念——一个能稳定复现 Bug、输出明确“红/绿”信号的命令或脚本。有了它，后面的二分查找、假设验证、添加日志都只是机械操作；没有它，盯着代码看再多也没用。

这个技能的独特之处在于：它拒绝在反馈环建立之前做任何假设。用作者 Matt Pocock 的原话说：“If you catch yourself reading code to build a theory before this command exists, stop — jumping straight to a hypothesis is the exact failure this skill prevents.”

二、主要功能

2.1 六阶段调试流程

diagnosing-bugs 把调试过程划分为六个清晰的阶段，每个阶段都有明确的目标和产出：

Phase 1 — 构建反馈环（Build a feedback loop）

这是整个技能的重中之重。你需要创建一个能稳定复现 Bug 的“红/绿”信号——一个命令或脚本，运行后能明确告诉你 Bug 是否还存在。构建方式有很多种，按推荐顺序包括：

• 编写一个会失败的测试（单元测试、集成测试或端到端测试）

• 写一段 curl/HTTP 脚本，对运行中的开发服务器发起请求

• 使用 CLI 命令配合固定输入，对比输出与已知正确的快照

• 用 Playwright 或 Puppeteer 编写无头浏览器脚本

• 回放捕获的流量或事件日志

• 搭建一个临时测试环境，只加载 Bug 相关的代码路径

反馈环建立之后还要持续优化：能不能让它跑得更快？能不能让信号更精确？能不能让它更稳定（固定时间、固定随机数种子、隔离文件系统）？作者的说法很直接：“一个 30 秒且不稳定的反馈环，和没有差不多；一个 2 秒且确定性的反馈环，就是调试的超能力。”

Phase 2 — 复现并最小化（Reproduce + minimise）

有了反馈环之后，反复运行它，观察失败模式。然后逐步缩小范围——减少无关的初始化步骤、缩小测试范围、去掉不必要的依赖。目标是把复现 Bug 所需的条件压缩到最小。

Phase 3 — 提出假设（Hypothesise）

基于已有的观察，列出所有可能的根因假设，并按可能性排序。这些假设必须是可证伪的——也就是说，你能通过修改代码或添加日志来验证或推翻它们。

Phase 4 — 添加日志定位（Instrument）

在关键路径上添加调试日志（统一标记为 [DEBUG-...]），运行反馈环，观察日志输出，验证或排除假设。

Phase 5 — 修复并添加回归测试（Fix + regression test）

确认根因后实施修复，然后把反馈环转换成回归测试，确保同一个 Bug 不会再回来。

Phase 6 — 清理与复盘（Cleanup + post-mortem）

移除调试日志，提交代码。如果发现根本问题是代码架构缺少合适的“接缝”来锁定 Bug，可以将发现反馈给架构改进流程。

2.2 适用场景

diagnosing-bugs 在以下场景中会自动被触发：

• 用户说“diagnose”或“debug this”

• 用户报告功能损坏、程序报错、运行失败或性能缓慢

它特别适合那些“看一眼猜不出原因”的硬 Bug：间歇性出现的 flaky test、在两个已知正常状态之间悄悄引入的性能回归。

三、如何安装

diagnosing-bugs 是一个 Agent Skill，可以安装到多种 AI 编程助手中，包括 Claude Code、Cursor、Windsurf、GitHub Copilot、Cline 等。

3.1 最简安装方式

在项目目录下运行以下命令：

npx skills add https://github.com/mattpocock/skills --skill diagnosing-bugs

这条命令需要 npx（随 Node.js 一起安装）。运行后，技能会被安装到当前项目的对应目录中。

3.2 为特定 Agent 安装

如果你想安装到 Claude Code：

npx -y skills add mattpocock/skills --skill diagnosing-bugs --agent claude-code

这会把技能安装到当前项目的 .claude/skills 目录下。

3.3 全局安装

使用 SkillsAuth 可以全局安装：

npx skillsauth add mattpocock/skills diagnosing-bugs

全局安装后，所有项目都可以使用这个技能。

3.4 通过 Claude Code 对话安装

如果你已经在使用 Claude Code，可以直接在对话中说：

“装一下 diagnosing-bugs 这个技能”

Claude Code 会自动获取并安装，不用离开聊天界面。

3.5 手动安装

你也可以手动从 GitHub 克隆仓库，然后把 SKILL.md 文件复制到项目目录中：

git clone https://github.com/mattpocock/skills.git

你的 AI 助手会自动识别并使用。

3.6 验证安装

安装完成后，在 AI 助手中输入 /diagnosing-bugs，如果能正常唤起技能说明安装成功。

四、应用场景

4.1 间歇性出现的 Flaky Test

这是 diagnosing-bugs 最擅长的场景之一。一个测试有时候过、有时候挂，你跑十次能绿六次。传统的做法是“再跑一次试试”，但 diagnosing-bugs 的做法完全不同——它不会去猜原因，而是先构建一个能提高复现率的反馈环。比如把测试循环跑 100 次、增加并发压力、缩小时间窗口，直到 flaky 变得可调试。

4.2 线上性能回归

某个接口的响应时间从 200ms 涨到了 800ms，但代码最近没什么大改动。 diagnosing-bugs 会引导你构建一个差分反馈环——用相同的输入分别跑旧版本和新版本，对比输出和性能数据，精准定位是哪个 commit 引入了回归。

4.3 复杂业务逻辑 Bug

用户报告了一个“偶尔出现”的数据错误，但开发环境无法复现。 diagnosing-bugs 会建议你保存真实的网络请求或事件日志到本地，然后在隔离环境中回放。把“线上偶尔发生”变成“本地稳定复现”，问题就解决了一大半。

4.4 AI 辅助编程中的调试

这是 diagnosing-bugs 最实际的应用场景。很多开发者用 AI 写代码时遇到的问题是：AI 看到报错就开始“猜”原因、改代码，越改越乱。装上 diagnosing-bugs 之后，AI 会被强制先建立反馈环再动手，调试效率明显提升。

五、使用案例

案例一：修复一个偶发的空指针异常

背景：一个电商项目的订单处理服务偶尔抛出 NullPointerException，但日志里看不出规律，大约每 50 笔订单出现一次。

使用 diagnosing-bugs 的过程：

1. 构建反馈环：写了一个脚本，循环调用订单处理接口 100 次，每次使用不同的测试订单数据，捕获异常输出。

2. 复现并最小化：运行后发现异常集中在“使用优惠券且订单金额小于 10 元”的场景。把测试数据缩小到这个范围，复现率从 2% 提升到了 80%。

3. 提出假设：列出三个可能的原因——优惠券折扣计算返回了 null、金额校验逻辑有边界问题、数据库查询返回了空值。

4. 添加日志定位：在三个关键位置加了 [DEBUG-...] 日志。运行反馈环，发现是优惠券折扣计算在特定条件下返回了 null。

5. 修复并添加回归测试：修复了折扣计算的边界条件，把反馈环脚本转换成了单元测试。

6. 清理与复盘：移除调试日志，提交代码。整个调试过程用了大约 20 分钟，如果靠“看代码猜原因”可能得花一两个小时。

案例二：定位一个前端性能回归

背景：一个 React 应用的首屏加载时间从 1.2 秒涨到了 2.8 秒，但最近两周的代码提交有 40 多个，不知道是哪个引起的。

使用 diagnosing-bugs 的过程：

1. 构建反馈环：写了一个 Playwright 脚本，自动打开应用、记录首屏加载时间、输出 pass/fail。

2. 复现并最小化：运行脚本确认 2.8 秒稳定复现。然后用 git bisect 配合这个脚本自动二分查找。

3. 定位根因：git bisect 定位到了某个合并请求——里面引入了一个大型第三方库的同步加载。

4. 修复：把同步加载改为动态 import，首屏时间回到了 1.3 秒。

5. 添加回归测试：把 Playwright 脚本保留为性能回归测试，确保以后不会再变慢。

这个案例的关键在于： diagnosing-bugs 的反馈环可以和 git bisect 无缝配合，实现自动化定位。

六、常见问题

Q：diagnosing-bugs 是免费的还是付费的？

A：技能本身是开源的（MIT 协议），免费使用。但运行它需要 AI 编程助手，部分助手有使用费用。

Q：必须按六个阶段严格执行吗？

A：技能文档里写了“Skip phases only when explicitly justified”——只有在明确说明理由的情况下才能跳过某个阶段。这不是死板，而是因为跳过阶段往往会回到“猜 Bug”的老路上。

Q：和 TDD 技能有什么区别？

A：TDD（测试驱动开发）是在写代码之前先写测试，确保代码有反馈信号。diagnosing-bugs 是在 Bug 已经存在之后，用类似的思路去定位和修复它。两者可以搭配使用。

Q：支持哪些编程语言？

A： diagnosing-bugs 不限制编程语言。它是一套调试方法论，可以用在任何语言、任何框架的项目中。

Q：安装后怎么用？

A：在 AI 助手中输入 /diagnosing-bugs，然后描述你遇到的 Bug 即可。技能会自动引导调试流程。