# Bug Fix Doc

> 当用户报告 bug、错误、问题或请求修复时自动生成中文 bug 修复文档。触发场景：用户说"有 bug"、"报错了"、"有问题"、"帮我修复"、"出错了"、"无法运行"等描述问题的情况。每次修复问题时必须创建结构化的 bug 修复记录文档，便于后续追踪和知识沉淀。

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

---


# Bug 修复文档生成技能

## 技能概述

本技能用于在 AI 帮助用户修复代码问题时，自动生成结构化的中文 bug 修复记录文档。这样可以：

- 📝 记录所有修复过的问题，避免遗忘
- 🔍 方便后续搜索和查阅
- 📚 形成团队知识库
- 🛡️ 预防同类问题再次发生

## 触发条件

当用户表达以下含义时，**必须触发此技能**：

- 报告 bug 或错误："有 bug"、"报错了"、"出错了"、"error"、"exception"
- 描述问题："有问题"、"不对劲"、"异常"、"无法运行"、"不工作"
- 请求修复："帮我修复"、"帮我解决"、"怎么处理"、"怎么修"
- 展示错误信息：粘贴了错误日志、堆栈跟踪、报错截图

**注意**：即使用户没有明确说"记录一下"，只要是在修复问题，就**必须**生成 bug 修复文档。

## 工作流程

### 1. 修复问题

首先帮助用户分析并修复问题，这是主要任务。

### 2. 生成记录

在修复完成后，**必须**执行以下步骤生成记录：

#### 2.1 确定记录文件信息

- **文件命名**: `docs/bugfixes/YYYYMMDD-{问题类型}-{简要描述}.md`
  - 例如：`docs/bugfixes/20260227-bug-用户登录失败.md`
  - 例如：`docs/bugfixes/20260227-performance-页面加载缓慢.md`

- **日期格式**: `YYYY-MM-DD HH:mm:ss`

#### 2.2 问题类型分类

根据问题性质选择合适的类型：

| 类型 | 说明 | 示例 |
|------|------|------|
| `bug` | 功能缺陷、逻辑错误 | 按钮点击无响应、数据计算错误 |
| `performance` | 性能问题 | 页面加载慢、接口响应超时 |
| `security` | 安全问题 | XSS 漏洞、SQL 注入风险 |
| `refactor` | 重构改进 | 代码结构优化、重复代码提取 |
| `compatibility` | 兼容性问题 | 浏览器兼容、版本兼容 |
| `ui-ux` | 界面体验问题 | 样式错乱、交互不友好 |
| `data` | 数据问题 | 数据丢失、数据格式错误 |
| `config` | 配置问题 | 环境变量、配置文件错误 |
| `dependency` | 依赖问题 | 包版本冲突、缺少依赖 |
| `other` | 其他类型 | 无法归类的问题 |

#### 2.3 涉及模块识别

- 提取修改的文件路径
- 识别涉及的组件/模块名称
- 记录关键函数/方法名

### 3. 创建文档

使用模板创建完整的 bug 修复文档（见下方模板）。

## Bug 修复记录模板

每次修复问题时，**必须使用以下模板**创建记录文档：

```markdown
# {问题简要描述}

## 基本信息

- **日期**: YYYY-MM-DD HH:mm:ss
- **问题类型**: {bug/performance/security/refactor/compatibility/ui-ux/data/config/dependency/other}
- **严重等级**: {P0-阻塞/P1-严重/P2-一般/P3-轻微}
- **涉及模块**: {文件/组件名称}
- **相关 Issue**: {如有关联的 issue 编号}

## 问题描述

### 现象

{详细描述问题的表现形式，用户看到了什么错误}

### 复现步骤

1. {步骤 1}
2. {步骤 2}
3. {步骤 3}

### 错误信息

```
{完整的错误日志、堆栈跟踪}
```

### 环境信息

- 操作系统：
- Node.js/Python/其他版本：
- 相关依赖版本：

## 根因分析

{深入分析问题产生的根本原因，而不是表面现象}

**关键代码位置**: `{文件路径}:{行号}`

```javascript
// {问题代码片段}
```

**原因**: {解释为什么这段代码会导致问题}

## 修复方案

### 方案描述

{说明修复思路和解决方案}

### 关键代码变更

**修改前**:
```javascript
// 原有代码
```

**修改后**:
```javascript
// 修复后的代码
```

### 文件变更清单

| 文件路径 | 变更类型 | 说明 |
|---------|---------|------|
| src/xxx.js | 修改 | 修复 xxx 逻辑 |
| src/yyy.js | 新增 | 添加 xxx 功能 |

## 验证方式

### 测试步骤

1. {如何验证修复是否生效}
2. {具体的测试操作}

### 预期结果

{修复后应该看到的结果}

### 实际结果

{修复后实际验证的结果}

## 预防措施

{为避免同类问题再次发生，采取的措施}

- [ ] 添加单元测试
- [ ] 添加类型检查
- [ ] 完善错误处理
- [ ] 更新文档
- [ ] 代码审查检查点

## 相关知识库

- {相关技术文档链接}
- {类似问题参考}

## 备注

{其他需要记录的信息}
```

## 输出位置

- **默认目录**: `docs/bugfixes/`
- 如果目录不存在，**必须创建**
- 文件名使用中文，便于阅读和搜索

## 重要提醒

1. **每次修复都必须记录** - 不要因为是"小问题"就跳过
2. **根因分析要深入** - 不要只记录表面现象
3. **代码变更要关键** - 只记录核心变更，不要全文件粘贴
4. **验证方式要具体** - 让其他人能按步骤验证
5. **预防措施要可执行** - 列出具体的待办事项

## 示例

当用户说："我的登录功能报错了，点击登录按钮没反应"

你应该：
1. 分析并修复登录功能的问题
2. 修复完成后，创建记录文档 `docs/bugfixes/20260227-bug-登录按钮无响应.md`
3. 使用上述模板填充完整内容

---

**记住**: 好的记录习惯能帮你节省未来排查问题的时间！