{/* 本页面由 website/scripts/generate-skill-docs.py 从技能 SKILL.md 自动生成。请编辑源 SKILL.md 而非本页面。 */}
系统调试
4 阶段根因调试：修复前先理解 Bug。
技能元数据
| 来源 | 内置（默认安装） |
| 路径 | skills/software-development/systematic-debugging |
| 版本 | 1.1.0 |
| 作者 | Hermes Agent（改编自 obra/superpowers） |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | debugging, troubleshooting, problem-solving, root-cause, investigation |
| 相关技能 | test-driven-development, writing-plans, subagent-driven-development |
参考：完整 SKILL.md
:::info 以下是此技能被触发时 Hermes 加载的完整技能定义。这是技能激活时代理所看到的指令。 :::
系统调试
概述
随机修复浪费时间并制造新 bug。快速补丁掩盖根本问题。
核心原则： 始终在尝试修复前找到根因。修复症状就是失败。
违反此过程的文字就是违反调试的精神。
铁律
没有先进行根因调查就不得有修复
如果你没有完成阶段 1，就不能提出修复。
使用时机
用于任何技术问题：
- 测试失败
- 生产环境 Bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
四个阶段
你必须在进入下一阶段前完成每个阶段。
阶段 1：根因调查
在尝试任何修复之前：
1. 仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误码
2. 一致重现
- 你能可靠触发它吗？
- 确切的步骤是什么？
- 每次都发生吗？
- 如果不能重现 → 收集更多数据，不要猜测
3. 检查最近的更改
- 什么变化可能导致这个？
- Git diff、最近的提交
- 新的依赖、配置变更
4. 在多组件系统中收集证据
当系统有多个组件时（API → 服务 → 数据库，CI → 构建 → 部署）：
在提出修复前，添加诊断仪表：
对于每个组件边界：
- 记录什么数据进入组件
- 记录什么数据离开组件
- 验证环境/配置传播
- 检查每层的状态
运行一次收集证据，显示它在哪里中断。然后分析证据以识别故障组件。然后调查该特定组件。
5. 追踪数据流
当错误在调用栈深处时：
- 坏值从哪里起源？
- 哪个函数用坏值调用了这个？
- 持续向上游追踪直到找到源头
- 在源头修复，不在症状处修复
阶段 1 完成清单
- 错误消息已完整阅读并理解
- 问题已一致重现
- 最近的更改已识别并审查
- 证据已收集（日志、状态、数据流）
- 问题已隔离到特定组件/代码
- 根因假设已形成
阶段 2：模式分析
修复前找到模式：
1. 找到工作示例
- 在相同代码库中找到类似的工作代码
- 什么工作代码类似于损坏的代码？
2. 对照参考比较
- 如果实现某种模式，完整阅读参考实现
- 不要略读——阅读每一行
- 应用前完全理解模式
3. 识别差异
- 工作和损坏的代码之间有什么不同？
- 列出每个差异，无论多小
- 不要假设”那个不重要”
4. 理解依赖
- 这需要哪些其他组件？
- 哪些设置、配置、环境？
- 它做了哪些假设？
阶段 3：假设与测试
科学方法：
1. 形成单一假设
- 清晰陈述：“我认为 X 是根因，因为 Y”
- 写下来
- 具体，不模糊
2. 最简测试
- 对假设进行最小的更改
- 一次一个变量
- 不要同时修复多个东西
3. 继续前验证
- 有效？→ 阶段 4
- 无效？→ 形成新的假设
- 不要在上面添加更多修复
4. 当你不确定时
- 说”我不理解 X”
- 不要假装知道
- 向用户寻求帮助
- 进一步研究
阶段 4：实现
修复根因，不是症状：
1. 创建失败测试用例
- 最简单的重现方式
- 如果可能，自动化测试
- 修复前必须有
2. 实现单一修复
- 解决已识别的根因
- 一次一个更改
- 没有”既然我在做”的改进
- 没有捆绑的重构
3. 验证修复
4. 如果修复无效 — 三击法则
- 停下。
- 计数：你试了多少次修复？
- 如果 < 3：返回阶段 1，用新信息重新分析
- 如果 ≥ 3：停下并质疑架构
- 不要在未进行架构讨论的情况下尝试第 4 次修复
5. 如果 3+ 次修复失败：质疑架构
表明架构问题的模式：
- 每次修复在不同地方揭示新的共享状态/耦合
- 修复需要”大规模重构”才能实现
- 每次修复在其他地方产生新症状
红牌 — 停下并遵循过程
如果你发现自己想：
- “先快速修复，之后调查”
- “就试试改 X 看看是否有效”
- “添加多个更改，运行测试”
- “跳过测试，我会手动验证”
- “大概是 X，让我修复那个”
所有这些意味着：停下。返回阶段 1。
快速参考
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根因 | 阅读错误、重现、检查更改、收集证据、追踪数据流 | 理解 WHAT 和 WHY |
| 2. 模式 | 找到工作示例、比较、识别差异 | 知道什么不同 |
| 3. 假设 | 形成理论、最简测试、一次一个变量 | 确认或新假设 |
| 4. 实现 | 创建回归测试、修复根因、验证 | Bug 已解决，所有测试通过 |