系统化调试

4阶段根因调试：先理解 Bug 再动手修复

概述

随意修复浪费时间并引入新 Bug。快速补丁只会掩盖底层问题。

核心原则：在尝试修复之前，必须找到根因（Root Cause）。只修复症状等于失败。

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

铁律

没有根因调查，就不能修复

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

使用场景

适用于任何技术问题：

• 测试失败
• 生产环境 Bug
• 异常行为
• 性能问题
• 构建失败
• 集成问题

以下情况尤其适用：

• 时间紧迫时（紧急情况让人容易猜测）
• "只需一个小修复"看起来很明显
• 你已经尝试了多种修复
• 上一次修复没有生效
• 你没有完全理解问题

不要跳过的情况：

• 问题看起来简单（简单 Bug 也有根因）
• 你很赶时间（匆忙只会保证返工）
• 有人要求立刻修复（系统化比瞎试更快）

四个阶段

你必须完成每个阶段后再进入下一个。

---

第一阶段：根因调查（Root Cause Investigation）

在尝试任何修复之前：

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")

第一阶段完成检查清单

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

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

---

第二阶段：模式分析（Pattern Analysis）

在修复之前先找模式：

1. 找到正常工作的示例

• 在同一个代码库中定位类似的正常工作的代码
• 有什么和出问题的代码类似但正常工作的？

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

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

2. 与参考实现对比

• 如果实现某种模式，请完整阅读参考实现
• 不要粗略浏览——逐行阅读
• 在应用之前充分理解模式

3. 识别差异

• 正常和出问题的代码之间有什么不同？
• 列出每个差异，无论多小
• 不要假设"那不可能有影响"

4. 理解依赖关系

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

---

第三阶段：假设与测试（Hypothesis and Testing）

科学方法：

1. 形成单一假设

• 清楚陈述："我认为 X 是根因，因为 Y"
• 写下来
• 要具体，不要模糊

2. 最小化测试

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

3. 在继续之前验证

• 有效？→ 进入第四阶段
• 无效？→ 形成新的假设
• 不要在失败的修复上叠加更多修复

4. 不知道时

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

---

第四阶段：实施（Implementation）

修复根因，而不是症状：

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 Agent 集成

调查工具

在第一阶段使用以下 Hermes 工具：

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

配合 delegate_task

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

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

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

配合测试驱动开发

修复 Bug 时：

• 编写一个复现 Bug 的测试（红色）
• 系统化调试找到根因
• 修复根因（绿色）
• 测试证明修复有效并防止回归

实际效果

来自调试实战数据：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时瞎试
• 首次修复成功率：95% vs 40%
• 引入新 Bug：几乎为零 vs 常见

不走捷径。不猜。系统化永远获胜。