系统化调试

系统化调试

概述

随机修补浪费时间，还会制造新 Bug。快速打补丁只会掩盖潜在问题。

核心原则：在尝试任何修复之前，务必先找到根本原因。只治标不治本就是失败。

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

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

何时使用

适用于任何技术问题：

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

尤其在以下情况务必使用：

• 时间紧迫时（紧急情况容易让人想瞎猜）
• "就快速修一下"看似很明显
• 你已经尝试了多种修复
• 之前的修复没有奏效
• 你还没有完全理解问题

以下情况也不要跳过：

• 问题看似简单（简单的 Bug 也有根本原因）
• 你在赶时间（仓促行事必然返工）
• 有人要求立刻修好（系统化比胡乱折腾更快）

四个阶段

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

---

阶段 1：根本原因调查

在尝试任何修复之前：

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 差异、最近的提交
• 新依赖、配置变更

操作：

# 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 → 构建 → 部署）：

在提出修复方案之前，先添加诊断性埋点：

对每个组件边界：

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

运行一次，收集能显示问题出在哪里的证据。

然后分析证据，定位出故障组件。

然后再调查该特定组件。

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 完成清单

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

停：在理解问题为什么发生之前，不要进入阶段 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. 验证修复

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

# Run full suite — no regressions
pytest tests/ -q

4. 如果修复无效——三击法则

• 停。
• 数一数：你尝试了几次修复？
• 如果少于 3 次：回到阶段 1，用新信息重新分析
• 如果 ≥ 3 次：停止并质疑架构（见下方第 5 步）
• 未经架构讨论，不要尝试第 4 次修复

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

表明架构问题的模式：

• 每次修复都在不同位置暴露出新的共享状态/耦合
• 修复需要"大规模重构"才能实施
• 每次修复都在别处制造新症状

停下并质疑根本性问题：

• 这个模式从根本上是否合理？
• 我们是不是"仅凭惯性硬撑"？
• 是应该重构架构，还是继续修症状？

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

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

---

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

如果你发现自己这样想：

• "先快速修一下，以后再调查"
• "就试着改一下 X，看能不能行"
• "一次改多处，然后跑测试"
• "跳过测试，我手动验证"
• "大概是 X，我来修它"
• "我还没完全理解，但这样可能行"
• "模式说用 X，但我要换个方式套用"
• "主要问题如下：[列出修复方案却不做调查]"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（已尝试过 2 次以上时）
• 每次修复都在不同位置暴露出新问题

以上所有情况都意味着：停下来，回到阶段 1。

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

常见借口

| 借口 | 现实 |

|--------|---------|

| "问题很简单，不需要流程" | 简单的问题也有根本原因。流程对简单 Bug 也很快。 |

| "紧急情况，没时间走流程" | 系统化调试比瞎猜乱试更快。 |

| "先试一下这个，然后再调查" | 第一次修复就定下基调。一开始就要做对。 |

| "确认修复有效后再写测试" | 未经测试的修复不牢靠。先测试才能证明。 |

| "同时修多个问题省时间" | 无法判断哪个有效。还会引入新 Bug。 |

| "参考太长，我改造一下模式" | 一知半解必然出错。要完整阅读。 |

| "我看到问题了，让我来修" | 看到症状 ≠ 理解根本原因。 |

| "再试一次修复"（已失败 2 次以上） | 失败 3 次以上 = 架构问题。质疑模式，而不是再修一次。 |

速查参考

| 阶段 | 关键活动 | 成功标准 |

|-------|---------------|------------------|

| 1. 根本原因 | 阅读错误、复现、检查改动、收集证据、追踪数据流 | 理解发生了什么以及为什么 |

| 2. 模式 | 寻找可用示例、对比、识别差异 | 知道差异在哪里 |

| 3. 假设 | 形成理论、最小化验证、一次一个变量 | 假设得到确认或形成新假设 |

| 4. 实施 | 创建回归测试、修复根本原因、验证 | Bug 已解决，所有测试通过 |

与 Hermes Agent 集成

调查工具

在阶段 1 中使用这些 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% 对比 40%
• 引入的新 Bug：几乎为零 对比 经常发生

没有捷径。不要猜测。系统化永远胜出。