# Bug Fixer

> 系统化调试修复 Bug。五阶段：收集证据→重现用例→分析(含根因归因)→假设→修复→进化记录。支持触发 code-review 和 feedback-writer。

- Skill: `herxinsasa/bug-fixer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add herxinsasa/bug-fixer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/bug-fixer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: herxinsasa (https://skillmd.com/u/herxinsasa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/herxinsasa/bug-fixer

---


# Bug Fixer — Bug 修复

## 职责

系统化地调试和修复 Bug。核心原则是 **先调查根本原因，再尝试修复**。禁止在看到报错后立即猜测性修改。

## 触发场景

- 用户报告 Bug 或异常行为
- 测试失败
- 构建失败
- 性能问题

## 铁律

```
不找出根本原因就不允许修复
```

如果还没完成阶段 1（证据收集），就不能进入阶段 4（修复）。

## 四阶段工作流程

### 阶段 1：收集证据

1. **仔细阅读错误信息**
   - 不要跳过任何 error 或 warning
   - 阅读完整的堆栈跟踪
   - 记录行号、文件路径、错误码

2. **稳定复现**
   - 能否稳定触发？
   - 精确的复现步骤是什么？
   - 每次都发生还是偶发？

3. **检查最近的变更**
   - `git diff` 和最近的 commits
   - 新依赖、配置变更
   - 环境差异

4. **收集完整上下文**
   - 输入输出数据
   - 环境信息（OS、版本等）
   - 日志文件

### 阶段 1.5：编写重现用例

**将证据转化为可重现的测试或复现脚本。**

1. 基于阶段 1 收集的复现步骤，编写最小重现用例
2. **确认用例在当前代码上确实失败**（证明 bug 存在）
3. 这是后续"修复有效"的客观验证标准——**用例通过 = bug 修好了**

### 阶段 2：分析规律

- 找出错误模式
- 确定边界条件
- 识别技术原因类别（逻辑错误/边界条件/竞态/类型错误/配置问题等）
- **确定根因归因类型**（必须四选一）：

| 根因类型 | 定义 | 举例 |
|---------|------|------|
| **需求遗漏** | PRD/验收标准没写清楚，导致理解偏差 | "没说空状态要怎么展示" |
| **设计遗漏** | 设计规范/ADR 未覆盖该场景 | "设计稿没有错误态的样式" |
| **编码失误** | 需求设计都明确，实现写错了 | "循环里漏了 break" |
| **边界遗漏** | 正常路径对但极端输入/并发/超时未处理 | "文件超过 1GB 时 OOM" |

### 阶段 3：提出假设

- 基于证据提出修复假设
- 验证假设（通过日志、小测试等方式）
- 排除不正确的假设
- 确定最终的修复方案

### 阶段 4：实施修复

- 实施最小必要的修复
- 运行阶段 1.5 的重现用例，确认通过（Bug 不再复现）
- 确认没有引入回归问题（运行现有测试套件）
- 提交修复并附上说明

### 阶段 4.5：根因归因与进化记录

**1. 写入文档错误记录表**

将 Bug 追加到对应文档的「决策与错误记录 > 错误与修复」表：

```markdown
| 错误 | 影响 | 根因类型 | 修复方式 | 日期 |
|------|------|---------|---------|------|
| <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

## 参考资源
- [systematic-debugging](../../references/superpowers/systematic-debugging.md) — 系统化调试方法论（本技能基于此）