先建立能触发具体故障的反馈，再缩小范围、验证假设，最后检查修复是否有效。
安装与准备
在项目目录的终端执行以下命令，安装后在 Claude Code 中输入下方提示。这里选择项目内的可编辑文件安装。
npx skills@latest add mattpocock/skills --skill diagnosing-bugs --agent claude-code
使用 Codex 时，把安装命令最后的 claude-code 换成 codex，对话里把 /diagnosing-bugs 换成 $diagnosing-bugs。如果使用完整的 Claude Code 插件，则选择 /mattpocock-skills:diagnosing-bugs，不要再重复安装文件版本。
需要能运行项目的环境、触发步骤和预期结果。准备最小输入或已脱敏日志；性能问题还要写清测量条件和正常基线。
第一次使用
把下面的场景和路径替换成你的项目情况，在 Agent 对话里输入：
/diagnosing-bugs
购物车连续点击两次结算会生成两张订单。复现环境是本地开发，预期同一次操作只生成一张。请先建立能捕获重复订单的检查，再定位原因。
怎样推进任务
建立针对症状的检查
让 Agent 从测试、HTTP 请求或浏览器操作中选择最短的有效路径。对于重复订单，检查必须验证订单数量或幂等结果，仅仅确认按钮可点击、接口返回成功都不够。先看到错误确实发生，再进入原因分析。
缩小输入并比较假设
每次只减少一个条件，保留仍会失败的最小场景。随后比较多种原因，例如前端重复提交、后端缺少幂等键、并发事务竞争。让每种假设给出能被实验推翻的预测，而不是先改最像问题的文件。
修复后回到原始场景
在能覆盖真实调用链的位置留下回归检查，应用最小修复后重新运行。最后还要回到最初的双击操作，检查修复没有只照顾简化输入。移除临时日志和探针，保留根因解释。
完成后检查什么
检查应在修复前能失败、修复后能通过，并覆盖最初描述的症状。若问题无法稳定复现，记录复现率和还缺少的环境信息，不用“没有再次看到”代替原因结论。
常见问题
一直停在复现阶段？ 提供发生问题的输入、环境差异或最小日志，有助于建立有效检查。
只是问一句错误含义，也启动完整流程？ 明确说“先解释错误，暂不运行诊断”。
性能问题怎么用？ 先固定数据量和计时方式，再比较各次改动。
偶发导入错误从哪里开始
假设 CSV 导入偶尔把同一行写两次。可以输入：“使用 diagnosing-bugs 调查 import.csv 重试后偶发重复记录；先用固定测试数据构造能统计重复行的命令，运行并展示红色结果，在此之前不要猜是队列还是数据库。”让反馈循环返回具体记录 ID 和次数，连续运行能看到复现率；如果一百次里只有一次失败，就先提高触发率，而不是马上修改生产逻辑。
接下来分别检查客户端重试、后台任务重复投递与数据库唯一约束，每个假设都应预测一条可观察证据。若只能写出“导入命令退出 0”的检查，它捕获不到重复记录，必须把断言改成业务结果。修复后保留真实调用边界的回归测试，并用最初的重试步骤复验；测试能绿但原始流程仍重复，说明测试边界选错了。
简短解释与完整排障要分清
有使用者发现，在只想快速理解代码中的一个问题时，Agent 也会自动调用 diagnosing-bugs，花时间搭一个价值不大的模拟复现。若你只需解释现有代码，明确说“先给初步判断，不启动完整排障”；若缺陷会影响用户或需要修复，则让它进入真实反馈循环，提供原始失败步骤和业务断言，别用虚构的 mock 场景代替实际故障。