系统化调试

在遇到任何 bug、测试失败或意外行为时使用。分为四个阶段的根本原因调查——在未理解问题之前，严禁进行修复。

技能元数据

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

参考：完整 SKILL.md

信息

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

系统化调试

概述

随意修复会浪费时间并引入新的 bug。快速补丁会掩盖潜在问题。

核心原则： 在尝试修复之前，务必找到根本原因。仅修复症状即为失败。

违反此流程的字面要求，即违背了调试的精神实质。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果未完成第一阶段，不得提出修复方案。

何时使用

适用于任何技术问题：

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

尤其在以下情况下使用：

• 时间紧迫（紧急情况容易让人倾向于猜测）
• “只需快速修复一下”看起来显而易见
• 已经尝试过多次修复
• 之前的修复未生效
• 尚未完全理解问题

以下情况不要跳过：

• 问题看似简单（简单的 bug 也有根本原因）
• 赶时间（匆忙必然导致返工）
• 有人要求立即修复（系统化方法比盲目尝试更快）

四个阶段

在进入下一阶段之前，必须完成当前阶段。

---

第一阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

操作： 对相关源文件使用 read_file。使用 search_files 在代码库中搜索错误字符串。

2. 稳定复现

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

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

# Run specific failing test
pytest tests/test_module.py::test_name -v

# Run with verbose output
pytest tests/test_module.py -v --tb=long

3. 检查近期变更

• 哪些变更可能导致此问题？
• Git diff、最近的提交
• 新依赖项、配置变更

操作：

# Recent commits
git log --oneline -10

# Uncommitted changes
git diff

# Changes in specific file
git log -p --follow src/problematic_file.py | head -100

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

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

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

对于每个组件边界：

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

运行一次以收集证据，显示问题出现在何处。 然后分析证据以识别失败的组件。 接着调查该特定组件。

5. 追踪数据流

当错误位于调用栈深处时：

• 不良值源自何处？
• 是谁用不良值调用了此函数？
• 持续向上游追踪，直到找到源头
• 在源头修复，而非在症状处修复

操作： 使用 search_files 追踪引用：

# Find where the function is called
search_files("function_name(", path="src/", file_glob="*.py")

# Find where the variable is set
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. 验证修复

# Run the specific regression test
pytest tests/test_module.py::test_regression -v

# Run full suite — no regressions
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 Agent 集成

调查工具

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

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

配合 delegate_task

对于复杂的多组件调试，分派调查子代理：

delegate_task(
    goal="Investigate why [specific test/behavior] fails",
    context="""
    Follow systematic-debugging skill:
    1. Read the error message carefully
    2. Reproduce the issue
    3. Trace the data flow to find root cause
    4. Report findings — do NOT fix yet

    Error: [paste full error]
    File: [path to failing code]
    Test command: [exact command]
    """,
    toolsets=['terminal', 'file']
)

配合 test-driven-development

修复 bug 时：

1. 编写复现 bug 的测试（RED）
2. 系统化调试以找到根本原因
3. 修复根本原因（GREEN）
4. 测试证明修复有效并防止回归

实际影响

来自调试会话的数据：

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

没有捷径。没有猜测。系统化方法永远胜出。