---

name: systematic-debugging description: 遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前。铁律：没有根因调查，不许提修复方案。触发词：bug、报错、不工作、出问题了、fix、debug、排查、怎么回事。 agent_created: true

系统化调试

核心原则

总是先找到根因再尝试修复。 症状修复 = 失败。随机修复浪费时间并制造新 bug。

铁律

没有根因调查 = 没有修复

没完成阶段 1，不能提修复方案。

何时使用

任何技术问题：

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

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

• 时间紧迫时（紧急情况最容易想猜）
• "就改一下"看起来很明显
• 已经试过多次修复
• 上次修复没起作用
• 你不完全理解这个问题

四阶段调试法

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

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细读错误信息

   • 不要跳过错误或警告
   • 完整读堆栈跟踪
   • 注意行号、文件路径、错误码

2. 稳定复现

   • 能可靠触发吗？
   • 精确步骤是什么？
   • 每次都发生吗？
   • 如果不能复现 → 收集更多数据，不要猜

3. 检查最近的变更

   • 什么改变可能导致这个？
   • git diff、最近的提交
   • 新依赖、配置变更
   • 环境差异

4. 多组件系统的证据收集

   在每个组件边界:
     - 记录什么数据进入
     - 记录什么数据出来
     - 验证配置/环境传播
   跑一次看哪里断了，然后再深入那层
   

5. 追踪数据流

   • 错误值的起源在哪里？
   • 谁用错误值调用了这个？
   • 向上追踪调用栈直到找到源头
   • 在源头修复，不在症状处修复

阶段 2：模式分析

找到模式再修复：

1. 在代码库中找类似的工作示例
2. 完整对照参考——不要略读
3. 列出工作与失败之间的每个差异
4. 理解所有依赖和假设

阶段 3：假设+检验

1. 形成一个清晰的假设："我认为 X 是根因，因为 Y"
2. 明确写下来
3. 设计最小测试来证明/否定它
4. 跑测试
5. 如果被否定 → 形成新假设，重复
6. 如果被证明 → 进入修复

阶段 4：修复+验证

1. 在根因处修复，不在症状处
2. 写一个能捕获这个 bug 的测试
3. 验证修复有效
4. 验证无回归（全量测试套件）
5. 清晰提交信息，解释根因

反模式

• "试试这个" — 没有根因的随机修复
• "大概是 X" — 没有证据的猜测
• "快速补丁" — 症状修复，根因还在
• 一次改多个东西 — 无法知道哪个起效
• 跳过复现 — 调试一个不能稳定触发的问题