systematic-debugging

---
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"** — 没有证据的猜测
- **"快速补丁"** — 症状修复，根因还在
- **一次改多个东西** — 无法知道哪个起效
- **跳过复现** — 调试一个不能稳定触发的问题