---
name: diagnosing-bugs
description: 难查 bug 的诊断纪律：先造出一条「现在就为这个 bug 变红」的紧反馈循环，再二分定位、最小验证、补回归测试。当 bug 难复现、间歇失败、或第一次看没头绪时使用。
metadata:
  invocation: model-invoked
  owner: qiudl
---

# 难查 bug 诊断

## 0. 一句话

**没有红循环就不推理**：先有一条几秒内能跑、且现在就为这个 bug 变红的命令，再开始猜。

## 1. 何时用

- 间歇性失败、偶发问题
- 第一次看没头绪、日志线索不足
- 已知两个好版本之间引入的回归
- 别人修过几次没修好的 bug

何时不用：一眼可见的拼写/配置错误、明确报错指向单行 → 直接修。

## 2. 铁律

1. **先复现**：能手动复现最好；不能就缩小到最小输入/最小步骤。
2. **建红循环**：一条命令（测试/脚本/curl），现在跑必须是红的，且失败原因就是这个 bug。
3. **一次只验一个假设**：改一个变量，跑一次，记录结果。
4. **修完补回归测试**：确认测试在修复前是红的（临时回退验证一次）。

## 3. 步骤

1. 收集信息：报错、日志、复现步骤、最近改动（`git log`/`git bisect`）。
2. 写最小复现：能稳定触发的最小输入或最小步骤。
3. 建立反馈循环：命令固定、几秒内出结果、失败信息可读。
4. 二分定位：git bisect / 输入二分 / 代码路径二分，把范围砍半。
5. 假设 → 最小改动 → 跑循环验证；不做"顺手重构"。
6. 回归测试：补一条覆盖该 bug 的测试，并证明它曾经红过。
7. 记录根因与预防（进复盘或 memory）。

## 4. 反模式

- 没复现就开始改代码
- 同时改多个地方，不知道哪个生效
- 靠"看了日志觉得是缓存问题"直接改
- 修完不补回归测试
- 间歇失败归因于"环境问题"就收工

## 5. 验证清单

- [ ] 有一个现在为红的命令（不是偶发）
- [ ] 每次改动只变一个变量，并有结果记录
- [ ] 修复后同一命令变绿
- [ ] 回归测试存在，且回退修复后它会红
- [ ] 根因已写清（不是"不知道，反正好了"）

## 6. 与其他技能

- 需要写测试规范 → `dev-test`
- 需要判断是不是设计缺陷 → `defect-analysis`
- 修复后要评审 → `dev-review`
- 任务状态与证据 → `ai-proj`（REQ 未 released 不算完成）