系统性调试

四阶段根因调试：在修复前理解 bug。

技能元数据

来源	内置（默认安装）
路径	skills/software-development/systematic-debugging
版本	1.1.0
作者	Hermes 智能体（改编自 obra/superpowers）
许可证	MIT
平台	linux, macos, windows
标签	调试, 故障排除, 问题解决, 根因, 调查
相关技能	测试驱动开发， 编写计划， 子智能体驱动开发

信息

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

系统化调试

概述

随机的修复会浪费时间并引入新错误。快速补丁掩盖了根本问题。

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

违反此流程的文字，就是违反调试的精神。

铁律

没有根本原因调查，就没有修复

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

何时使用

适用于任何技术问题：

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

尤其在以下情况使用此技能：

• 时间紧迫时（紧急情况会诱使你猜测）
• "就改一小下"似乎显而易见时
• 你已经尝试了多次修复
• 上一次修复没有生效
• 你并不完全理解这个问题

不要跳过，即使：

• 问题看起来很简单（简单缺陷也有根本原因）
• 你赶时间（匆忙保证返工）
• 有人要求立刻修复（系统化比胡乱尝试更快）

四个阶段

你必须完成每个阶段，然后才能进入下一阶段。

---

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

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

2. 稳定地重现问题

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

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

# 运行特定的失败测试
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 完成清单

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

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

---

阶段 2：模式分析

在修复前找到模式：

1. 找到正常工作的示例

• 在相同代码库中定位类似的正常工作的代码
• 与损坏的部分相比，什么是正常工作的？

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

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

2. 与参考实现对比

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

3. 识别差异

• 正常工作的和损坏的之间有什么不同？
• 列出每一个差异，无论多小
• 不要假设“这个没关系”

4. 理解依赖项

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

---

阶段 3：假设与测试

科学方法：

1. 提出一个单一假设

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

2. 最小化测试

• 为测试假设做出尽可能小的更改
• 一次只改变一个变量
• 不要一次修复多个东西

3. 验证后再继续

• 有效吗？ → 阶段 4
• 无效？ → 提出新的假设
• 不要继续叠加更多修复

4. 当你不知道时

• 说“我不理解 X”
• 不要假装知道
• 向用户寻求帮助
• 研究更多

---

阶段 4：实施

修复根本原因，而不是症状：

1. 创建失败的测试用例

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

2. 实施单一修复

• 解决已识别的根本原因
• 一次一个更改
• 不要“顺便”做改进
• 不要捆绑重构

3. 验证修复

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

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

4. 如果修复无效——三次原则

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

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

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

• 每次修复都在不同位置揭示新的共享状态/耦合
• 修复需要“大规模重构”才能实施
• 每次修复都在其他地方产生新症状

停下来质疑根本问题：

• 这个模式从根本上正确吗？
• 我们是否“仅凭惯性坚持使用它”？
• 我们是应该重构架构，还是继续修复症状？

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

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

---

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

如果你发现自己在想：

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

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

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

常见借口

借口	现实
“问题简单，不需要流程”	简单问题也有根本原因。流程对简单缺陷很快。
“紧急，没时间走流程”	系统化调试比猜测-检查的胡乱尝试更快。
“先试试这个，再调查”	第一次修复设定了模式。从一开始就做对。
“我确认修复有效后再写测试”	未经测试的修复不会持久。先测试证明它有效。
“一次修复多个能节省时间”	无法隔离哪个有效。会导致新缺陷。
“参考太长，我会调整模式”	部分理解保证出错。完全阅读它。
“我看到问题了，让我修一下”	看到症状 ≠ 理解根本原因。
“再试一次修复”（2 次失败后）	3 次以上失败 = 架构问题。质疑模式，不再修复。

快速参考

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

赫尔墨斯智能体集成

调查工具

在第一阶段使用这些赫尔墨斯工具：

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

使用 delegate_task

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

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

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

使用测试驱动开发

修复错误时：

1. 编写一个重现错误的测试（红色）
2. 系统性调试以找到根本原因
3. 修复根本原因（绿色）
4. 测试证明修复有效并防止回归

实际影响

来自调试会话的总结：

• 系统性方法：15-30分钟修复
• 随机修复方法：2-3小时的反复尝试
• 首次修复率：95% 对 40%
• 引入的新错误：几乎为零 对 常见情况

无捷径，无猜测。系统性方法始终获胜。