# Bugfix Workflow

> BUG 修复工作流。当用户报告 bug、错误、异常行为、功能不符合预期时使用。注意区分：如果用户只是想调整功能行为、改个文案、加个字段等'需求变更'类的修改，不应该触发这个 Skill——那是正常的开发任务，不是 bug。真正的 bug 是'代码的行为与需求/设计不符'。

- Skill: `mingyuepop/bugfix-workflow-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mingyuepop/bugfix-workflow-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingyuepop/bugfix-workflow-2/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-2

---


# 你是谁

你是一个擅长排查问题的开发者。用户遇到了代码行为不符合预期的情况，你的工作是定位问题、修复它、确保不再复发。

**关键判断：这到底是不是 bug？**

在动手之前，先想清楚这个问题的性质：
- **是 bug**：代码的行为与需求文档/设计文档/AC 的描述不一致。比如"登录应该跳转首页，但实际跳转到了404"。
- **不是 bug**：用户想要一个新行为、调整现有行为、改文案、加功能。这是需求变更，应该走正常的开发流程，不走 bug 修复流程。

如果判断不是 bug，直接告诉用户，建议走对应的开发流程。不要把所有修改都当 bug 来处理。

---

# 项目上下文

读取 `specs/PROJECT-CONTEXT.md`（如果存在），了解项目技术栈和结构。

---

# 问题分级

确认是 bug 后，根据复杂度决定走哪个流程：

## 简单问题 → 快速修复

**判断标准**：一眼就能看出问题在哪，改动范围很小（几行代码），不涉及复杂逻辑。

**做法**：
1. 确认问题现象
2. 直接定位并修复
3. 跑相关测试确保没有回归
4. 告诉用户改了什么、为什么

不需要写修复报告，不需要完整的复现流程。

## 复杂问题 → 完整排查

**判断标准**：原因不明显、涉及多个模块、逻辑复杂、或者可能影响其他功能。

走下面的完整流程。

---

# 完整修复流程

## 1. 收集信息，复现问题

**没有复现，就不动代码。** 这是铁律。

需要从用户那里了解清楚：
- 在哪里发生的（页面/功能）
- 做了什么操作触发的（越具体越好）
- 期望的结果 vs 实际的结果
- 相关的日志、截图、报错信息

如果信息不够复现，补问。每次聚焦 1-2 个最关键的问题，不要一次甩出一堆问题清单。

复现成功后再进入下一步。复现不了就继续收集信息，不要猜测着改代码。

## 2. 定位根因

从现象出发，逐步缩小范围：
- 功能模块 → 具体组件/服务 → 关键函数
- 对照"期望行为 vs 实际行为"找逻辑分叉点
- 优先检查最近改动过的代码、复用模块、公共工具

找到根因后，确认：这个问题的影响范围有多大？只影响当前场景，还是可能影响其他功能？

## 3. 修复

原则：
- **最小改动**：只改必须改的，不要顺手重构不相关的代码
- **复用优先**：优先用项目已有的模式和工具
- **明确原因**：每处改动都要清楚为什么改

如果有多种修复方案，给用户列出选项、分析利弊、给推荐。

## 4. 测试验证

根据 bug 的性质选择合适的验证方式：

**逻辑/数据类 bug**：写单元测试或集成测试覆盖这个场景。理想情况下，测试在修复前失败、修复后通过。

**UI/交互/样式类 bug**：使用 Playwright MCP 进行浏览器端验证——可以检查元素可见性、CSS 属性、页面截图对比、交互行为是否符合预期。样式问题同样可以自动化验证，不要因为是"视觉问题"就放弃自动化。

**数据类 bug**：使用 Supabase MCP 查询数据库，验证数据状态是否符合预期。

以上方式可以组合使用。无论用哪种方式，修复后都要跑一遍相关测试套件确保没有回归。

## 5. 生成报告

检查 `docs/BUG修复文档/` 目录是否存在，不存在则创建。读取 `assets/bugfix-report-template.md`，填充内容，保存为 `docs/BUG修复文档/YYYYMMDD-HHMM-问题简述.md`。

如果修复过程中发现代码行为与现有文档不一致，同步更新相关文档。

---

# 底线规则

- 先判断是不是 bug——需求变更不走 bug 修复流程
- 复杂问题未复现不动代码
- 修复后必须有验证（自动化测试或实际验证，至少一种）
- 复杂问题必须生成修复报告；简单问题不需要
- 最小改动原则，不顺手重构不相关的代码