随机修补浪费时间，还会制造新 Bug。快速打补丁只会掩盖潜在问题。
核心原则：在尝试任何修复之前，务必先找到根本原因。只治标不治本就是失败。
违反本流程的字面规定，就是违背调试的精神。
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
如果你还没有完成阶段 1，就不能提出修复方案。
适用于任何技术问题：
尤其在以下情况务必使用：
以下情况也不要跳过：
你必须完成每个阶段后才能进入下一阶段。
在尝试任何修复之前：
操作：对相关源文件使用 read_file。使用 search_files 在代码库中查找错误字符串。
操作：使用 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
操作：
# Recent commits
git log --oneline -10
# Uncommitted changes
git diff
# Changes in specific file
git log -p --follow src/problematic_file.py | head -100
当系统包含多个组件时（API → 服务 → 数据库、CI → 构建 → 部署）：
在提出修复方案之前，先添加诊断性埋点：
对每个组件边界：
运行一次，收集能显示问题出在哪里的证据。
然后分析证据，定位出故障组件。
然后再调查该特定组件。
当错误深藏在调用栈中时：
操作：使用 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")
停：在理解问题为什么发生之前，不要进入阶段 2。
修复之前先找到模式：
操作：使用 search_files 查找可对比的模式：
search_files("similar_pattern", path="src/", file_glob="*.py")
科学方法：
修复根本原因，而不是症状：
test-driven-development 技能
# Run the specific regression test
pytest tests/test_module.py::test_regression -v
# Run full suite — no regressions
pytest tests/ -q
表明架构问题的模式：
停下并质疑根本性问题：
在尝试更多修复之前，先与用户讨论。
这不是假设失败——这是架构错误。
如果你发现自己这样想：
以上所有情况都意味着：停下来，回到阶段 1。
如果 3 次以上修复失败：质疑架构（阶段 4 第 5 步）。
| 借口 | 现实 |
|--------|---------|
| "问题很简单，不需要流程" | 简单的问题也有根本原因。流程对简单 Bug 也很快。 |
| "紧急情况，没时间走流程" | 系统化调试比瞎猜乱试更快。 |
| "先试一下这个，然后再调查" | 第一次修复就定下基调。一开始就要做对。 |
| "确认修复有效后再写测试" | 未经测试的修复不牢靠。先测试才能证明。 |
| "同时修多个问题省时间" | 无法判断哪个有效。还会引入新 Bug。 |
| "参考太长，我改造一下模式" | 一知半解必然出错。要完整阅读。 |
| "我看到问题了，让我来修" | 看到症状 ≠ 理解根本原因。 |
| "再试一次修复"（已失败 2 次以上） | 失败 3 次以上 = 架构问题。质疑模式，而不是再修一次。 |
| 阶段 | 关键活动 | 成功标准 |
|-------|---------------|------------------|
| 1. 根本原因 | 阅读错误、复现、检查改动、收集证据、追踪数据流 | 理解发生了什么以及为什么 |
| 2. 模式 | 寻找可用示例、对比、识别差异 | 知道差异在哪里 |
| 3. 假设 | 形成理论、最小化验证、一次一个变量 | 假设得到确认或形成新假设 |
| 4. 实施 | 创建回归测试、修复根本原因、验证 | Bug 已解决，所有测试通过 |
在阶段 1 中使用这些 Hermes 工具：
search_files —— 查找错误字符串、追踪函数调用、定位模式read_file —— 阅读带行号的源代码，进行精确分析terminal —— 运行测试、查看 Git 历史、复现 Bugweb_search/web_extract —— 研究错误信息、库文档对于复杂的多组件调试，可以派出调查子智能体：
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']
)
修复 Bug 时：
来自实际调试会话的数据：
没有捷径。不要猜测。系统化永远胜出。
评论区