缺陷定位与修复

---
name: bug-localization-and-fix
description: 从现象出发，用可复现路径定位根因，给出最小修复与防回归措施。用于 bug 处理全流程。产出 `事件与问题/缺陷队列.md` + `BUG-NNN` 记录。
---

# 缺陷定位与修复

## 何时使用

- 用户 / 测试 / 监控报告了一个 bug。
- 测试用例失败需要定位。
- 线上事件需要查明直接原因（深层复盘交给 `线上事件诊断与复盘`）。

## 前置

- 必读 `.agents/context/常见故障与排查.md`、`.agents/memory/常见排查路径.md`。
- 必读 `.agents/rules/代码规范.md`（修复也要守规范）。

## 输入

- 缺陷现象 / 报错 / 日志 / trace
- 复现环境与步骤
- 相关模块代码

## 步骤

1. **建档**：在 `事件与问题/缺陷队列.md` 登记一条 `BUG-NNN`，字段见模板。
   - 严重级别：`P0 崩溃/数据损坏` / `P1 主流程不可用` / `P2 功能受损有绕过` / `P3 轻微`
2. **稳定复现**：写出最小复现步骤。**不能复现的缺陷也要记录**，并标注"待复现"。
3. **缩小范围**：
   - 二分法定位（提交 / 模块 / 配置）；
   - 日志与 trace 追踪；
   - 构造最小失败用例（能稳定红）。
4. **定位根因**：区分**根本原因**与**触发条件**，写清"为什么会发生"。
   - 若根因是设计问题 → 建议写 ADR 或记技术债。
5. **最小修复**：优先改**根因**，不做顺手重构（避免夹带风险）。若必须临时绕过 → 明确标注 TODO + 跟踪项。
6. **防回归**：补一条**会失败的测试**，修复后转绿；必要时加入 `测试与验证/回归测试.md`。
7. **验证**：跑相关测试 + 手工验证原复现路径；确认**没有引入新缺陷**。
8. **收尾**：更新缺陷状态，若涉及线上则记录影响与持续时间。

## 输出

- `事件与问题/缺陷队列.md`（登记 + 状态流转）
- `事件与问题/进行中缺陷/BUG-NNN-<slug>.md`（详情，模板：`.agents/templates/缺陷/缺陷报告.md`）
- 修复记录：`.agents/templates/缺陷/修复验证.md`
- 修复完成后移入 `事件与问题/已修复缺陷/`
- 可复现模式的根因 → 追加到 `.agents/memory/经验与陷阱.md`

## 检查清单

- [ ] 有最小复现步骤（或明确标注无法复现）。
- [ ] 写清了根因，而非只写"改了某行"。
- [ ] 修复针对根因，未顺带做无关重构。
- [ ] 补了防回归测试，且该测试在修复前是失败的。
- [ ] 验证了原路径 + 相邻路径。
- [ ] 缺陷队列状态已更新。

## 边界与禁止

- **禁止**在未定位根因时"试错式改代码"。
- **禁止**修复夹带大规模重构（拆成独立变更）。
- **禁止**用"加个 try/catch 吞掉异常"作为最终修复（除非有明确理由与记录）。
- 涉及数据损坏的缺陷：**立即**升级并提示用户，评估是否需要数据修复（见 `数据修复规范.md`）。