# Bugfix Workflow

> 通用 BUG 修复流程与报告生成。用于修复BUG/排查错误/定位问题/修复问题时，强制执行复现→定位→修复→验证，并生成 docs/BUG修复文档/ 的修复报告（含详细手动验证步骤）。

- Skill: `mingyuepop/bugfix-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mingyuepop/bugfix-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingyuepop/bugfix-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: mingyuepop (https://skillmd.com/u/mingyuepop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingyuepop/bugfix-workflow

---


# BUG 修复工作流

## 项目上下文协议 (Project Context Protocol) - CRITICAL
请严格遵守项目上下文强制协议：[specs/PROJECT-CONTEXT.md](specs/PROJECT-CONTEXT.md)
**在执行本 Skill 之前，必须先建立项目认知。**

目标：通用适配所有类型 BUG，且强制"先复现再修复"。

## 快速开始
1. 收集信息：问题描述、出现位置、期望结果、实际结果、环境/版本、日志/截图。
2. 复现：严格按照用户步骤复现；若失败，立即补问，不进入修复。
3. 定位：缩小范围，找到根因或最小可疑范围。
4. 修复：最小改动；优先复用现有模块/代码。
5. 单元测试：编写针对此 BUG 的自动化测试脚本，验证修复有效性并防止回归。
6. 验证：必须包含"详细的手动操作步骤"，逐步说明。
7. 生成报告：复制模板到 `docs/BUG修复文档/`，补全内容。

## 必做约束
- 未复现 → 不得修改代码。
- 复现不成功 → 给出"还需要的复现信息清单"，等待用户补充。
- 修复完成 → 必须给出手动验证步骤（逐步、细到点击/输入）。
- 影响文档 → 更新相关文档，避免与代码不一致。
- 任一硬性条件不满足 → 必须停止并说明原因，不得继续下一步。
 - 复现门槛：未提供"清晰可执行的复现步骤 + 期望/实际" → 必须停止。
 - 验证门槛：未输出逐步手动验证步骤 → 不得结束。
 - 测试门槛：必须编写/更新单元测试脚本以覆盖此 BUG；若无法编写（如纯 UI 样式问题或缺乏环境），必须在报告中详细说明原因。
 - 报告门槛：未生成修复报告 → 不算完成。

## 复现信息清单（不足时先补问）
- 发生页面/功能位置
- 期望结果 vs 实际结果
- 可复现步骤（尽量到按钮/输入项）
- 尽量提供最小可复现步骤
- 设备/系统/版本/配置
- 日志/截图/报错信息

## 引导式补问（当描述不完整时使用）
按"少量多次"的方式补问，先问最关键的三点：
1) 发生在哪里（页面/功能）？
2) 你做了哪些操作（尽量细化到每一步）？
3) 期望结果 vs 实际结果？

如果还无法复现，再继续追问：
- 触发频率（必现/偶现）与首次出现时间
- 账号/角色/权限是否有关
- 设备/系统/版本/配置细节
- 是否有截图/日志/报错信息

## 定位建议（按需使用）
- 缩小范围：功能模块 → 组件/服务 → 关键函数
- 对照"期望 vs 实际"找逻辑分叉点
- 优先检查复用模块与公共工具

## 修复建议（通用）
- 最小改动、明确原因、避免副作用
- 遵守现有代码规范与结构
 - 对严重级别有清晰依据（影响范围/是否阻断/是否可绕过）
 - 修复方案包含风险点与回滚思路

## 验证输出要求
1. **自动化测试**：
   - 编写一个新的测试文件或在现有测试中新增用例。
   - 确保测试用例能复现 BUG（修复前失败）并验证修复（修复后通过）。
   - 在对话中展示测试运行结果（PASS/FAIL）。

2. **手动验证**：
   必须输出"手动验证步骤"，格式为逐条步骤（示例）：
1) 打开应用并进入 XXX 页面
2) 点击 XXX 按钮
3) 在 XXX 输入框输入 XXX
4) 观察 XXX 是否达到预期

## 报告模板
1. 检查 `docs/BUG修复文档/` 目录是否存在，若不存在请自动创建。
2. 复制 `assets/bugfix-report-template.md` 到该目录，命名建议：
`YYYYMMDD-HHMM-问题简述.md`

填好后在回复中说明报告路径。