| name | bug-fixer |
| description | 系统化调试修复 Bug。五阶段：收集证据→重现用例→分析(含根因归因)→假设→修复→进化记录。支持触发 code-review 和 feedback-writer。 |
Bug Fixer — Bug 修复
职责
系统化地调试和修复 Bug。核心原则是 先调查根本原因，再尝试修复。禁止在看到报错后立即猜测性修改。
触发场景
- 用户报告 Bug 或异常行为
- 测试失败
- 构建失败
- 性能问题
铁律
不找出根本原因就不允许修复
如果还没完成阶段 1（证据收集），就不能进入阶段 4（修复）。
四阶段工作流程
阶段 1：收集证据
-
仔细阅读错误信息
- 不要跳过任何 error 或 warning
- 阅读完整的堆栈跟踪
- 记录行号、文件路径、错误码
-
稳定复现
- 能否稳定触发？
- 精确的复现步骤是什么？
- 每次都发生还是偶发？
-
检查最近的变更
git diff 和最近的 commits- 新依赖、配置变更
- 环境差异
-
收集完整上下文
阶段 1.5：编写重现用例
将证据转化为可重现的测试或复现脚本。
- 基于阶段 1 收集的复现步骤，编写最小重现用例
- 确认用例在当前代码上确实失败（证明 bug 存在）
- 这是后续"修复有效"的客观验证标准——用例通过 = bug 修好了
阶段 2：分析规律
- 找出错误模式
- 确定边界条件
- 识别技术原因类别（逻辑错误/边界条件/竞态/类型错误/配置问题等）
- 确定根因归因类型（必须四选一）：
| 根因类型 | 定义 | 举例 |
|---|
| 需求遗漏 | PRD/验收标准没写清楚，导致理解偏差 | "没说空状态要怎么展示" |
| 设计遗漏 | 设计规范/ADR 未覆盖该场景 | "设计稿没有错误态的样式" |
| 编码失误 | 需求设计都明确，实现写错了 | "循环里漏了 break" |
| 边界遗漏 | 正常路径对但极端输入/并发/超时未处理 | "文件超过 1GB 时 OOM" |
阶段 3：提出假设
- 基于证据提出修复假设
- 验证假设（通过日志、小测试等方式）
- 排除不正确的假设
- 确定最终的修复方案
阶段 4：实施修复
- 实施最小必要的修复
- 运行阶段 1.5 的重现用例，确认通过（Bug 不再复现）
- 确认没有引入回归问题（运行现有测试套件）
- 提交修复并附上说明
阶段 4.5：根因归因与进化记录
1. 写入文档错误记录表
将 Bug 追加到对应文档的「决策与错误记录 > 错误与修复」表：
| 错误 | 影响 | 根因类型 | 修复方式 | 日期 |
|------|------|---------|---------|------|
| <Bug 描述> | <影响范围> | 需求遗漏/设计遗漏/编码失误/边界遗漏 | <修复摘要> | YYYY-MM-DD |
- 根因类型为需求遗漏 → 写入
Product-Spec.md
- 根因类型为设计遗漏 → 写入
Design-Brief.md
- 根因类型为编码失误或边界遗漏 → 写入
Dev-Plan.md
2. 触发进化反馈
如果根因类型是编码失误或设计遗漏，调用 feedback-writer，记录结构化反馈：
feedback 内容：
- type: "correction"
- skill: 受影响的 skill（product-spec-builder / design-brief-builder / implementer 等）
- context: "Bug 修复中发现：<根因类型>"
- issue: "<具体问题描述>"
- resolution: "<修复方式>"
这样进化引擎才能在后续扫描到同一模式出现 ≥3 次时，触发对应 Skill 的优化提案。
3. 判断是否需要 code-review
修复完成后，判断以下条件：
- 修复涉及代码改动 > 20 行 → 触发 code-review
- 修复涉及接口/类型/数据模型变更 → 触发 code-review
- 否则 → 跳过 code-review，直接记录
阶段 5：更新进度
更新 .claude/progress.json：
milestones 追加「Bug 修复：<摘要>（根因：<类型>）」
输出
- Bug 分析报告（技术原因 + 根因归因 + 修复方案）
- 修复后的代码 + 验证结果
- 对应文档「决策与错误记录」表追加记录（含根因类型）
- 根因为编码失误/设计遗漏时，触发 feedback-writer
- 改动 >20 行或涉及接口变更时，触发 code-review
参考资源
