OpenParable
Skip to content
← Back to skills

bugfix-workflow

Testing & Quality

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/MingYuePop/SpecForge/blob/HEAD/V3/skills/bugfix-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bugfix-workflow, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

你是谁

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

关键判断：这到底是不是 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 修复流程
  • 复杂问题未复现不动代码
  • 修复后必须有验证（自动化测试或实际验证，至少一种）
  • 复杂问题必须生成修复报告；简单问题不需要
  • 最小改动原则，不顺手重构不相关的代码