用 systematic-debugging 找出 Bug 的根本原因
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
原文：用 systematic-debugging 找出 Bug 的根本原因（cccskills）
技能页面：systematic-debugging
本文结论
安装 systematic-debugging 后，Claude Code 和 Codex 会在确认 Bug 或测试失败的原因之后再进行修复。
这是一个按顺序执行的技能：从复现步骤、日志和最近的变更建立假设并加以验证，最终通过失败测试确认修复效果。
本文将介绍排查的 4 个阶段、安装方法、请求示例以及使用注意事项。
安装 systematic-debugging 后，AI 在确认原因之前不会给出修复方案。
例如，当你发出如下请求时：
请复现这个测试失败，并从最近的变更和日志中找出原因
AI 会先完整阅读错误信息和堆栈跟踪，记录行号、文件路径和错误码。
然后执行测试，确认问题是否每次都能复现。
接下来，AI 会查看 git diff、最近的提交，以及依赖项和配置的变更。
即使无法复现，也不会凭猜测直接修复，而是按步骤收集更多数据。
找到候选原因后，AI 会将其与同一代码库中正常运行的类似代码进行对比，逐一列出细微差异。
在此基础上，AI 只会提出一个假设，格式为"原因是 X，理由是 Y"，并用最小化变更加以验证。
假设不成立时，不会在原修复上叠加更多改动，而是重新建立新假设。
即便假设成立，也不会立即修改代码。
AI 会先创建一个能复现缺陷的失败测试，再针对根本原因进行唯一一处修复。
最后确认该测试是否通过、其他测试是否未受影响，然后才返回结果。
systematic-debugging 将调试分为 4 个阶段，前一阶段完成前不会进入下一阶段。
其核心原则是"在查明根本原因之前不进行修复"，仅消除症状的修复会被视为失败。
各阶段内容如下：
| 阶段 | AI 的行为 | 进入下一阶段的条件 |
|---|---|---|
| 1. 根本原因调查 | 阅读错误、复现问题、确认近期变更、收集证据 | 明确发生了什么以及为何发生 |
| 2. 模式分析 | 找到正常运行的示例或参考实现并进行对比 | 确定与有缺陷代码的差异 |
| 3. 假设与验证 | 建立一个假设，用最小化变更验证（失败则重建新假设） | 假设得到验证 |
| 4. 实现 | 创建失败测试，进行一处修复，并确认结果 | 缺陷消除，测试通过 |
对于跨多个处理层的缺陷，AI 会在修复前先添加诊断日志。
适用场景包括从 CI 到构建再到签名的流程，以及从 API 到服务再到数据库的链路。
在每个处理层的边界，AI 会记录输入数据、输出数据，以及环境变量和配置的传递情况。
然后执行一次，确认问题出在哪里。
明确有问题的层之后，再对该层进行详细排查。
若错误出现在调用链较深的位置，AI 会向上追溯调用方，找出非法值的来源。
修复的原则是在值产生的位置处理，而不是在症状出现的位置。
这一逆向追溯流程附有说明文档，涵盖确认根本原因后如何在多个层进行输入验证，以及如何将固定等待时间替换为条件检查等内容。
AI 会计算每次修复的尝试次数，失败 3 次或以上后，不会进行第 4 次修复。
每次修复后在其他地方出现新问题、或修复需要大规模重构的情况，都被视为设计本身的问题。
此时 AI 会停止继续修复，并与用户讨论是否需要重新审视设计。
深入排查后，有时会发现原因在于环境、时序或外部因素。
这种情况下，AI 会记录排查内容，并通过重试、超时或错误信息进行处理，同时添加监控和日志以备下次排查。
systematic-debugging 是 GitHub 上 obra/superpowers 中的技能之一。
该仓库的 Star 数为 309,845。
同一仓库中还包含头脑风暴、代码审查等覆盖开发全流程的技能。
在终端执行以下命令，即可从 obra/superpowers 单独添加 systematic-debugging。
目标 AI 可在执行时从 Claude Code、Codex 等中选择。
npx skills add https://github.com/obra/superpowers --skill systematic-debugging
若委托给 AI 安装，请直接发送以下内容。
这种写法会先要求 AI 确认内容，确认无可疑操作后再进行配置。
次の Agent Skill をインストールしてください。
https://github.com/obra/superpowers/tree/main/skills/systematic-debugging
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/systematic-debugging/、Codex なら ~/.agents/skills/systematic-debugging/ に配置してください。
存放位置取决于所使用的 AI 和适用范围。
| AI | 所有项目中使用 | 仅在特定项目中使用 |
|---|---|---|
| Claude Code | ~/.claude/skills/systematic-debugging/ | 项目的 .claude/skills/systematic-debugging/ |
| Codex | ~/.agents/skills/systematic-debugging/ | 项目的 .agents/skills/systematic-debugging/ |
判断是否安装成功的标准是文件夹中是否存在 SKILL.md。
若作为全局配置安装到 Claude Code，可通过以下命令查看内容：
ls ~/.claude/skills/systematic-debugging/
如果除 SKILL.md 外，还有说明用 Markdown 文件、TypeScript 示例和 Shell 脚本，则说明配置已完成。
本技能的设计前提是在提出修复方案之前使用。
适用于遇到 Bug、测试失败或意外行为的场合。
在请求中描述症状和希望排查的范围，可以让排查有一个清晰的起点。
从昨天开始，登录流程的测试一直在失败。
请在修复之前确认复现步骤和最近的提交，找出原因。
返回内容包括：是否成功复现、相关提交或配置变更，以及有据可查的假设。
假设得到验证后，再给出失败测试和一处修复。
请追踪从 API 到数据库的处理流程，确认非法值在哪里被引入。
这是追踪生产环境问题的请求。
AI 会在各层边界添加诊断日志并执行一次，指出哪一层出现了异常值。
修复方案会针对非法值产生的位置提出。
CI 构建中签名失败。
请确认工作流、构建脚本和签名各阶段分别传递了什么内容。
对于构建或集成失败，AI 会在各阶段添加确认步骤进行隔离排查。
密钥不显示具体值，而以"已配置／未配置"表示，同时确认密钥链状态。
最终定位到问题所在阶段，例如"工作流阶段数据正常，但未传递到构建脚本"。
排查能进展到哪一步，取决于最初提供的信息。
本技能对无法复现的缺陷不会凭猜测修复，而是回到数据收集阶段。
最初提供的复现步骤、完整错误信息、日志以及问题开始出现的时间越详细，排查就能越快接近根本原因。
修复内容的最终确认由人工完成。
请检查用于诊断而添加的日志和确认处理是否未残留在修复提交中。
当修复失败 3 次或以上时，AI 会主动发起设计讨论。
是否继续修复还是重构，由用户来决定。
失败测试的编写方式和完成前的确认流程，参考的是同一 superpowers 仓库中的其他技能（测试驱动开发和完成前验证）。
若仅安装了 systematic-debugging，这两个技能的指令将不在本地。
请根据需要考虑从仓库中额外添加。
许可证为 MIT。SKILL.md 以英文编写，附带文件中还包含 Shell 脚本和 TypeScript 示例。
安装前请先阅读 SKILL.md 及附带文件的内容。
obra/superpowers 同一仓库中还有可在调试前后使用的技能。
dispatching-parallel-agents 是一个将相互独立的缺陷或测试失败分配给不同 AI 并行排查和修复的技能。
当多处同时出现失败时，可用于分担 systematic-debugging 的排查工作。
requesting-code-review 是一个在实现后或合并前向另一个 AI 发起代码审查请求的技能。
适合在修复根本原因后，希望用第三方视角确认变更内容时使用。
finishing-a-development-branch 是一个在确认所有测试通过后，选择合并或创建 Pull Request 的技能。
可在完成修复后，继续将分支的收尾工作一并委托给 AI。
是的。
本技能的设计理念是即使看似简单的问题也有其根本原因，越是情况紧急越应遵守流程。
对于简单的 Bug，每个阶段预计会很快结束。
有意义。
已经尝试多次修复却未成功，正是本技能特别建议使用的场景。
如果失败次数达到 3 次或以上，将优先讨论设计重构，而非继续追加修复。
若确认原因在于环境、时序或外部因素，AI 会记录排查内容并通过重试、超时等方式处理，同时添加监控和日志以备下次排查。
不过，"找不到原因"的情况大多会被视为排查不足，因此第一步是检查是否有排查遗漏。
可以。
执行安装命令时选择 Codex，或将技能配置到 ~/.agents/skills/systematic-debugging/ 即可。
若按项目使用，请放置在项目的 .agents/skills/ 下。
systematic-debugging 是一个让 AI 遵循"查明根本原因之前不进行修复"这一顺序的技能。
它按步骤依次完成错误读取、复现、变更历史确认、假设验证，最终通过失败测试确认修复效果。
失败 3 次后会切换为设计讨论，因此可以终止"头痛医头"式的反复修复。
如果委托 AI 进行的修复一再重复同样的失败，不妨先安装这个技能，从排查阶段开始委托给 AI。
本文转载自 cccskills 的文章「用 systematic-debugging 找出 Bug 的根本原因」。
技能详情和安装方法请参阅 cccskills 的 systematic-debugging 页面。