系统化调试

四阶段根因调试：先理解缺陷，再修复。

技能元数据

来源	内置（默认安装）
路径	skills/software-development/systematic-debugging
版本	1.1.0
作者	Hermes 智能体（改编自 obra/superpowers）
许可证	MIT
平台	linux, macos, windows
标签	debugging, troubleshooting, problem-solving, root-cause, investigation
相关技能	test-driven-development, writing-plans, subagent-driven-development

信息

以下是当此技能触发时，Hermes 加载的完整技能定义。这是智能体在技能激活时看到的指令。

系统化调试

概述

随机修复会浪费时间并制造新 bug。快速补丁会掩盖底层问题。

核心原则： 在尝试修复前，必须找到根本原因。症状修复等于失败。

违反此流程的字面规定，就是违反调试的精神。

铁律

未经根本原因调查，绝不修复

如果你没有完成第一阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

• 测试失败
• 生产环境中的 Bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其在以下情况使用：

• 时间紧迫（紧急情况容易让人想猜测）
• "一个快速修复"似乎显而易见
• 你已经尝试了多种修复方法
• 之前的修复不起作用
• 你没有完全理解问题

不要跳过的情况：

• 问题看起来简单（简单的 bug 也有根本原因）
• 你很赶时间（匆忙保证了返工）
• 有人要求现在就修复（系统化比反复折腾更快）

四个阶段

你必须在进入下一阶段之前完成每个阶段。

---

第一阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

• 不要跳过错误或警告
• 它们通常包含确切的解决方案
• 完整阅读堆栈跟踪
• 注意行号、文件路径、错误代码

操作： 使用 read_file 读取相关源文件。使用 search_files 在代码库中查找错误字符串。

2. 稳定复现

• 你能可靠地触发它吗？
• 确切的步骤是什么？
• 每次都会发生吗？
• 如果不可复现 → 收集更多数据，不要猜测

操作： 使用 terminal 工具运行失败的测试或触发 bug：

# 运行特定的失败测试
pytest tests/test_module.py::test_name -v

# 以详细输出运行
pytest tests/test_module.py -v --tb=long

3. 检查近期更改

• 有什么更改可能导致了这个问题？
• Git diff，近期提交
• 新依赖项，配置更改

操作：

# 近期提交
git log --oneline -10

# 未提交的更改
git diff

# 特定文件的更改
git log -p --follow src/problematic_file.py | head -100

4. 在多组件系统中收集证据

当系统包含多个组件时（API → 服务 → 数据库，CI → 构建 → 部署）：

在提出修复方案之前，添加诊断日志：

对于每个组件边界：

• 记录进入组件的数据
• 记录退出组件的数据
• 验证环境/配置传播
• 检查每一层的状态

运行一次以收集显示问题发生位置的证据。 然后分析证据以识别故障组件。 然后调查该特定组件。

5. 追踪数据流

当错误在调用栈深处时：

• 坏数据源自哪里？
• 是什么用这个坏数据调用了这个函数？
• 持续向上游追踪，直到找到源头
• 在源头修复，而不是在症状处

操作： 使用 search_files 追踪引用：

# 查找函数被调用的位置
search_files("function_name(", path="src/", file_glob="*.py")

# 查找变量被设置的位置
search_files("variable_name\\s*=", path="src/", file_glob="*.py")

第一阶段完成清单

• 错误信息已完整阅读并理解
• 问题已稳定复现
• 近期更改已识别并审查
• 已收集证据（日志、状态、数据流）
• 问题已隔离到特定组件/代码
• 已形成根本原因假设

停止： 在理解为什么发生之前，不要进入第二阶段。

---

第二阶段：模式分析

修复前先找到模式：

1. 查找工作示例

• 在同一代码库中定位类似的正常工作代码
• 有什么相似且正常工作的代码？

操作： 使用 search_files 查找可比较的模式：

search_files("similar_pattern", path="src/", file_glob="*.py")

2. 与参考实现对比

• 如果正在实现某个模式，请完整阅读参考实现
• 不要略读——阅读每一行
• 在应用前充分理解该模式

3. 识别差异

• 正常工作的代码与出错的代码有什么不同？
• 列出每一个差异，无论多小
• 不要假设"那个不重要"

4. 理解依赖关系

• 这个功能还需要哪些其他组件？
• 需要什么设置、配置、环境？
• 它做了什么假设？

---

第三阶段：假设与测试

科学方法：

1. 形成单一假设

• 明确陈述："我认为 X 是根本原因，因为 Y"
• 写下来
• 要具体，不要模糊

2. 最小化测试

• 做出可能的最小改动来测试假设
• 每次只改一个变量
• 不要一次修复多个问题

3. 验证后再继续

• 有效吗？ → 第四阶段
• 无效？ → 形成新假设
• 不要在现有基础上添加更多修复

4. 当你不知道时

• 说"我不理解 X"
• 不要假装知道
• 向用户寻求帮助
• 进一步研究

---

第四阶段：实施

修复根本原因，而非症状：

1. 创建失败的测试用例

• 最简单的复现方式
• 如果可能，使用自动化测试
• 修复前必须有测试
• 使用 test-driven-development 技能

2. 实施单一修复

• 解决已识别的根本原因
• 每次只改一处
• 不要进行"既然改了，顺便也改一下"的改进
• 不要捆绑重构

3. 验证修复

# 运行特定的回归测试
pytest tests/test_module.py::test_regression -v

# 运行完整测试套件——确保无回归
pytest tests/ -q

4. 如果修复不起作用——三次法则

• 停止。
• 计数：你尝试了多少次修复？
• 如果 < 3：返回第一阶段，用新信息重新分析
• 如果 ≥ 3：停止并质疑架构（见下方步骤 5）
• 不要在没有架构讨论的情况下尝试第 4 次修复

5. 如果 3 次以上修复失败：质疑架构

表明存在架构问题的模式：

• 每次修复都在不同地方揭示了新的共享状态/耦合
• 修复需要"大规模重构"才能实现
• 每次修复都在其他地方制造了新症状

停止并质疑根本：

• 这个模式从根本上是健全的吗？
• 我们是否"纯粹出于惯性而坚持它"？
• 我们应该重构架构还是继续修复症状？

在尝试更多修复之前，与用户讨论。

这不是失败的假设——这是错误的架构。

---

危险信号——停止并遵循流程

如果你发现自己在想：

• "先快速修复，以后再调查"
• "就试试改 X 看看行不行"
• "多改几个地方，跑一下测试"
• "跳过测试，我会手动验证"
• "可能是 X，让我修一下"
• "我不完全明白，但这可能有效"
• "模式说的是 X，但我会用不同的方式适配"
• "主要问题是：[列出修复方案而没有调查]"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（当已经试过 2 次以上时）
• 每次修复都在不同地方揭示了一个新问题

所有这些都意味着：停止。返回第一阶段。

如果 3 次以上修复失败： 质疑架构（第四阶段步骤 5）。

常见借口

借口	现实
"问题简单，不需要流程"	简单问题也有根本原因。对于简单 bug，流程很快。
"紧急情况，没时间走流程"	系统化调试比猜测和检查的反复折腾更快。
"先试试这个，然后再调查"	第一次修复设定了模式。从一开始就做对。
"确认修复有效后再写测试"	未经测试的修复不会持久。先测试才能证明它有效。
"一次多修几个地方节省时间"	无法隔离哪个修复起作用。会导致新 bug。
"参考文档太长，我会适配那个模式"	部分理解保证了 bug。必须完整阅读它。
"我看到问题了，让我修复它"	看到症状 ≠ 理解根本原因。
"再试一次修复"（在 2 次以上失败后）	3 次以上失败 = 架构问题。质疑模式，不要再修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、复现、检查更改、收集证据、追踪数据流	理解是什么和为什么
2. 模式	查找工作示例、对比、识别差异	知道差异在哪里
3. 假设	形成理论、最小化测试、每次只改一个变量	假设被证实或形成新假设
4. 实施	创建回归测试、修复根本原因、验证	Bug 已解决，所有测试通过

Hermes 智能体集成

调查工具

在第一阶段使用这些 Hermes 工具：

• search_files — 查找错误字符串、追踪函数调用、定位模式
• read_file — 读取带行号的源代码，以便精确分析
• terminal — 运行测试、检查 git 历史、重现错误
• web_search/web_extract — 研究错误信息、查阅库文档

使用 delegate_task

对于复杂的多组件调试，可派遣调查子智能体：

delegate_task(
    goal="调查为什么 [具体的测试/行为] 失败",
    context="""
    遵循系统化调试技能：
    1. 仔细阅读错误信息
    2. 重现问题
    3. 追踪数据流以找到根本原因
    4. 报告发现 — 此时不要修复

    错误：[粘贴完整错误信息]
    文件：[失败代码的路径]
    测试命令：[确切的命令]
    """,
    toolsets=['terminal', 'file']
)

使用测试驱动开发

修复错误时：

1. 编写一个重现该错误的测试（RED - 红灯）
2. 系统化调试以找到根本原因
3. 修复根本原因（GREEN - 绿灯）
4. 该测试验证修复并防止回归

现实世界的影响

根据调试会议得出：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时的反复尝试
• 首次修复率：95% 对比 40%
• 引入的新错误：接近零对比常见

没有捷径。没有猜测。系统化方法总是赢家。