4阶段根因调试：先理解 Bug 再动手修复
随意修复浪费时间并引入新 Bug。快速补丁只会掩盖底层问题。
核心原则：在尝试修复之前，必须找到根因（Root Cause）。只修复症状等于失败。
违反此流程的字面意思，就是违反调试的精神。
没有根因调查，就不能修复
如果你还没有完成第一阶段，就不能提出修复方案。
适用于任何技术问题：
以下情况尤其适用：
不要跳过的情况：
你必须完成每个阶段后再进入下一个。
在尝试任何修复之前：
操作：使用 read_file 读取相关源文件。使用 search_files 在代码库中查找错误字符串。
操作：使用 terminal 工具运行失败的测试或触发 Bug：
# 运行特定失败的测试
pytest tests/test_module.py::test_name -v
# 详细输出运行
pytest tests/test_module.py -v --tb=long
操作：
# 最近的提交
git log --oneline -10
# 未提交的变更
git diff
# 特定文件的变更
git log -p --follow src/problematic_file.py | head -100
当系统有多个组件时（API → 服务 → 数据库，CI → 构建 → 部署）：
在提出修复之前，先添加诊断工具：
对每个组件边界：
运行一次以收集显示哪里出错的证据。
然后分析证据以识别出故障的组件。
然后调查该特定组件。
当错误在调用栈深处时：
操作：使用 search_files 追踪引用：
# 查找函数被调用的位置
search_files("function_name(", path="src/", file_glob="*.py")
# 查找变量被赋值的位置
search_files("variable_name\\s*=", path="src/", file_glob="*.py")
停止：在理解"为什么"发生之前，不要进入第二阶段。
在修复之前先找模式：
操作：使用 search_files 查找可比较的模式：
search_files("similar_pattern", path="src/", file_glob="*.py")
科学方法：
修复根因，而不是症状：
test-driven-development 技能
# 运行特定的回归测试
pytest tests/test_module.py::test_regression -v
# 运行完整测试套件——无回归
pytest tests/ -q
表明架构问题的模式：
停下来质疑基本面：
在尝试更多修复之前与用户讨论。
这不是假设失败——这是架构错误。
如果你发现自己在想：
所有这些都意味着：停下来。回到第一阶段。
如果3次以上修复失败：质疑架构（第四阶段第5步）。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根因。流程处理简单 Bug 很快。 |
| "紧急情况，没时间走流程" | 系统化调试比瞎猜瞎试更快。 |
| "先试试这个，之后再调查" | 第一次修复定基调。从一开始就做对。 |
| "确认修复有效后再写测试" | 未经测试的修复不可靠。先写测试才能证明。 |
| "同时修多个问题省时间" | 无法隔离哪个有效。还会引入新 Bug。 |
| "参考太长了，我按模式改编" | 一知半解注定出 Bug。完整阅读。 |
| "我看到问题了，修吧" | 看到症状 ≠ 理解根因。 |
| "再试一次修复"（已失败2次以上） | 3次以上失败 = 架构问题。质疑模式，不要再修。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根因调查 | 读错误、复现、检查变更、收集证据、追踪数据流 | 理解"什么"和"为什么" |
| 2. 模式分析 | 找正常示例、对比、识别差异 | 知道有什么不同 |
| 3. 假设验证 | 形成理论、最小测试、一次一变量 | 确认假设或形成新假设 |
| 4. 实施 | 创建回归测试、修复根因、验证 | Bug 解决，所有测试通过 |
在第一阶段使用以下 Hermes 工具：
search_files — 查找错误字符串、追踪函数调用、定位模式read_file — 带行号读取源代码进行精确分析terminal — 运行测试、查看 Git 历史、复现 Bugweb_search/web_extract — 研究错误信息、库文档对于复杂的多组件调试，派遣调查子代理：
delegate_task(
goal="调查 [特定测试/行为] 为什么失败",
context="""
遵循系统化调试技能：
1. 仔细阅读错误信息
2. 复现问题
3. 追踪数据流找到根因
4. 报告发现——不要修复
错误: [粘贴完整错误]
文件: [失败代码路径]
测试命令: [确切命令]
""",
toolsets=['terminal', 'file']
)
修复 Bug 时：
来自调试实战数据：
不走捷径。不猜。系统化永远获胜。
评论区