# Bug Fix

> 修复 bug。用户指定工单或直接描述缺陷时按它修，没指定时到 docs/bugs/ 里挑一个；先复现再定位根因，根因没定位到不许动手。bug 是代码与产品文档不符，只改代码不改产品文档；确实要改产品设计的必须先问用户。修完验证通过就删掉工单。用于「修这个 bug」「找个 bug 修」等场景。

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

---


# 修复 bug

**bug 的定义是代码行为与产品文档（或用户确认的口径）不符。** 所以修复只改代码，
**不改产品文档**——文档是判定谁对谁错的基准，改了基准就等于把 bug 认定成了正确行为。

## 选定要修的 bug

| 用户给了什么 | 怎么做 |
|---|---|
| 指名了工单 | 按它修 |
| 只口头描述了缺陷 | 直接修，不必先建工单 |
| 什么都没给 | 到工单目录（默认 `docs/bugs/`，项目有自己的约定时按项目的）里挑一个 |

自己挑时按以下判据，**选定后先告诉用户修的是哪个再开工**：

- 严重程度高的优先
- 同级别里取复现步骤清楚、影响范围明确的
- 目录是空的，或候选之间取舍不清（严重程度相当、互相牵连），列出候选让用户拍板，不要自己硬挑

## 动手之前

- 先建立项目上下文：项目有自己的文档规范时按它的，否则从文档索引（默认 `docs/README.md`）入手
  定位涉及的模块
- **必须先复现**。复现不了就停下汇报——写明试了什么、缺什么条件，不许凭工单描述猜着改
- 复现后定位根因，**根因没定位到不许改代码**；查不出来就汇报卡在哪，不要试探性地改着看
- 对照产品文档、或工单里写明的依据确认预期行为。**两者都没有，或文档写的就是当前这个行为**，
  说明这不是实现偏差——停下来问用户要的是哪种行为，问清之前不要改

## 产品设计要改时

根因出在产品设计本身、只改代码修不掉的，**停下来问用户**：说明现状、为什么按现在的设计修不掉、
有哪些改法。**用户拍板要改设计之后**，才动产品文档与对应的代码；用户不改设计就按文档的口径修代码。

- 改产品文档时，项目有自己的文档规范的按它的规定做；没有的落笔前必须先完整读一遍要改的那几份
- 设计变更超出本 bug 的范围时，那是需求变更，按项目的需求讨论与开发流程另行排期，
  本次只修与 bug 直接相关的部分

## 怎么修

- 改在根因上，不在表象上堵。确实只能临时绕过时，代码里标 `TODO` 写明绕过了什么、什么条件下能真正修掉
- 只改与本 bug 相关的部分；顺带发现的其它问题记下来，修完一并汇报，不要顺手改
- 能加回归测试的加一条，覆盖这次的复现路径
- **不要回头改工单**：不勾进度、不写修复记录、不改状态。工单只负责把问题交接过来

## 验证与收尾

1. **验证**：按工单的验收判据逐条验；没有工单的按复现步骤确认现象消失。**验证不过不算修完**，
   验不了的部分如实说明是哪部分、为什么
2. **删工单**：验证通过就把工单删掉，工单目录空了就把目录一起删。
   验证没通过、或修复没做完的不许删