| name | systematic-debugging |
| description | 遇到任何 bug、测试失败或意外行为时使用,在提出修复方案之前。铁律:没有根因调查,不许提修复方案。触发词:bug、报错、不工作、出问题了、fix、debug、排查、怎么回事。 |
| agent_created | true |
系统化调试
核心原则
总是先找到根因再尝试修复。 症状修复 = 失败。随机修复浪费时间并制造新 bug。
铁律
没有根因调查 = 没有修复
没完成阶段 1,不能提修复方案。
何时使用
任何技术问题:
- 测试失败
- 生产 Bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
尤其在以下情况必须使用:
- 时间紧迫时(紧急情况最容易想猜)
- "就改一下"看起来很明显
- 已经试过多次修复
- 上次修复没起作用
- 你不完全理解这个问题
四阶段调试法
必须完成每个阶段再进入下个阶段。
阶段 1:根因调查
在尝试任何修复之前:
-
仔细读错误信息
- 不要跳过错误或警告
- 完整读堆栈跟踪
- 注意行号、文件路径、错误码
-
稳定复现
- 能可靠触发吗?
- 精确步骤是什么?
- 每次都发生吗?
- 如果不能复现 → 收集更多数据,不要猜
-
检查最近的变更
- 什么改变可能导致这个?
git diff、最近的提交
- 新依赖、配置变更
- 环境差异
-
多组件系统的证据收集
在每个组件边界:
- 记录什么数据进入
- 记录什么数据出来
- 验证配置/环境传播
跑一次看哪里断了,然后再深入那层
-
追踪数据流
- 错误值的起源在哪里?
- 谁用错误值调用了这个?
- 向上追踪调用栈直到找到源头
- 在源头修复,不在症状处修复
阶段 2:模式分析
找到模式再修复:
- 在代码库中找类似的工作示例
- 完整对照参考——不要略读
- 列出工作与失败之间的每个差异
- 理解所有依赖和假设
阶段 3:假设+检验
- 形成一个清晰的假设:"我认为 X 是根因,因为 Y"
- 明确写下来
- 设计最小测试来证明/否定它
- 跑测试
- 如果被否定 → 形成新假设,重复
- 如果被证明 → 进入修复
阶段 4:修复+验证
- 在根因处修复,不在症状处
- 写一个能捕获这个 bug 的测试
- 验证修复有效
- 验证无回归(全量测试套件)
- 清晰提交信息,解释根因
反模式
- "试试这个" — 没有根因的随机修复
- "大概是 X" — 没有证据的猜测
- "快速补丁" — 症状修复,根因还在
- 一次改多个东西 — 无法知道哪个起效
- 跳过复现 — 调试一个不能稳定触发的问题