---
name: systematic-debug
description: 系统化调试 — 禁止猜测，要求复现→假设→验证的科学流程
origin: AI-Engineering
---

# 系统化调试

## When to Activate

- 遇到 Bug、测试失败或异常行为
- 修复 Bug 前（先复现再修复）

## 核心原则

**禁止猜测。** 每一步都要有证据支持。

## 流程

### 第 1 步：复现 Bug

1. 获取确切的复现步骤（不是 "大概是这样"）
2. 写一个能稳定复现的最小测试用例
3. 如果无法复现 → 先收集更多信息，不要开始改代码

**复现检查**：
- [ ] 有明确的复现步骤
- [ ] 有期望行为 vs 实际行为的对比
- [ ] 有错误日志或堆栈信息

### 第 2 步：缩小范围

1. 用二分法定位问题区域（注释掉一半代码，看问题是否消失）
2. 检查最近的变更：`git log --oneline -10`、`git diff HEAD~1`
3. 添加诊断日志，不要用 print 然后 guess

**范围检查**：
- [ ] 确认了问题在哪个文件/函数
- [ ] 确认了是哪个 commit 引入的（如果是回归）
- [ ] 排除了环境问题（版本、配置、数据）

### 第 3 步：提出假设

1. 基于证据提出 1-3 个可能的原因
2. 按可能性排序
3. 为每个假设设计验证方法

**假设格式**：
```
假设 1: [原因] — 因为 [证据]
验证方法: [如何确认/排除]
```

### 第 4 步：验证假设

1. 从最可能的假设开始
2. 一次只验证一个假设
3. 记录验证结果（确认/排除）

### 第 5 步：最小化修复

1. 只改导致 bug 的那行代码
2. 不要 "顺手" 重构或优化
3. 修复后运行所有测试
4. 确认复现用例现在通过

### 第 6 步：防止复发

1. 将复现用例保留为回归测试
2. 记录根因到 `docs/ai-engineering/LEARNINGS.md`
3. 如果是编码标准问题，考虑更新 `CODE_STANDARDS.md`

## 常见反模式（禁止）

| 反模式 | 为什么不行 |
|---|---|
| "试试加个 sleep" | 掩盖竞态条件，不是修复 |
| "先加个 try-catch" | 吞掉异常，隐藏真正的问题 |
| "改了很多地方试试" | 无法确定哪个改动解决了问题 |
| "网上说这样能解决" | 不理解根因就照搬方案 |
| "重启试试" | 如果重启能解决，说明有状态泄漏，要找到源头 |

## 诊断工具参考

| 问题类型 | 推荐工具 |
|---|---|
| 性能 | profiler、火焰图、日志时间戳 |
| 内存泄漏 | heap dump、内存分析器 |
| 竞态条件 | 并发测试、日志追踪 |
| 依赖问题 | 依赖树分析、版本锁定检查 |
| 网络问题 | 抓包、日志、超时设置检查 |