메뉴
系统性 Bug 修复流水线（P0-P8）：一次修一个，强制根因分析、独立 worktree、TDD、双层验收报告、forge-qa 回归；多会话经 .forge/active.md 防撞车。 铁律：不做根因分析不写代码；新发现禁止顺手修；没有用户最终结论不合并。 触发方式：用户说"bugfix"、"反馈个问题"、"修这个 bug"、"这里有问题"、"为什么不对"、"排查一下"、"investigate"、"forge-bugfix"，或报告错误、异常行为、功能失效时。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Forge 工作流总入口。只读检测项目状态，推荐下一步该用哪个 skill，自己不干活。触发方式：用户说"forge"、"下一步"、"接下来做什么"。
复盘 v3（Workbench 门禁型）：启动本地 Workbench，用户在独立会话页确认想学的知识点和深度，按选择调研产出复盘文档； 同时落 2-3 条账本条目（记录/复盘/learnings.jsonl）供 bugfix/eng 开工回放与复发检测。 触发方式：用户说"总结知识"、"学习总结"、"复盘"、"可视化复盘"、"/forge-fupan"。
通用头脑风暴：4 种模式（产品/内容/构建/探索）× 6 阶段，强制前提挑战和 2-3 方案，产出可跨会话续聊的思考文档；支持 Mermaid/图辅助判断。 触发方式：用户说"头脑风暴"、"brainstorm"、"讨论一下"、"我有个想法"、"帮我想想"、"画图梳理想法"。
设计实现：把 DESIGN.md 转成代码，只改样式不改逻辑；CSS 优先、Token 驱动、反 AI 模板、原子提交，以真实截图和 CSS 断言验证。 触发方式：用户说"实现设计"、"forge-design-impl"、设计文档确认后需要写代码时。
全栈设计规划：分级门控管理 DESIGN.md 与 DESIGN-CHANGELOG，内置可检索设计规则库（UX 规则/配色/字体），三层 Token、Image 2 视觉稿门禁、反 AI 模板检测。 触发方式：用户说"设计"、"forge-design"、"先看效果图"，或 forge-dev 调度、需要创建/更新设计文档时。
文档落地治理规范。统一管理 docs/ 目录下文档的写时约束、读时索引、生命周期标记。提供当前真相源白名单（doc-paths.md）+ frontmatter schema + 新项目一键脚手架（init-project.sh，已就绪）。所有 forge-* skill 的文档落地路径以本 skill 的 doc-paths.md 为准。触发方式：用户说"文档治理"、"文档放哪"、"docs 目录乱了"、"forge-doc-policy"、AI 准备创建任意 .md 或新目录前的自查。
| name | forge-bugfix |
| description | 系统性 Bug 修复流水线（P0-P8）：一次修一个，强制根因分析、独立 worktree、TDD、双层验收报告、forge-qa 回归；多会话经 .forge/active.md 防撞车。 铁律：不做根因分析不写代码；新发现禁止顺手修；没有用户最终结论不合并。 触发方式：用户说"bugfix"、"反馈个问题"、"修这个 bug"、"这里有问题"、"为什么不对"、"排查一下"、"investigate"、"forge-bugfix"，或报告错误、异常行为、功能失效时。 |
| allowed-tools | ["Bash","Read","Write","Edit","Glob","Grep","TodoWrite","AskUserQuestion","WebSearch","Skill"] |
文档落地路径：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
~/.claude/skills/forge-doc-policy/doc-paths.md。 当前文档加载顺序：先读项目CLAUDE.md、docs/README.md、docs/INDEX.md、docs/QA.md/docs/ENGINEERING.md相关当前真相源，再读活跃 BF 报告和 backlog。 历史 BF 报告在docs/archive/raw/bugfix-reviews/，只作追溯证据。 详细规则见~/.claude/skills/_shared/current-doc-loading.md。
短会话、单 bug 隔离、结构化证据、可追溯、可丢弃。
核心机制：
docs/bugfix/reviews/BF-XX.md（status: draft）
docs/archive/raw/bugfix-reviews/（status: archive），backlog 保留链接qa-pass-pending-final-review，最后由批次汇总统一交给用户验收docs/bugfix/backlog.md 的待修区，分配 BF-XX 编号docs/bugfix/backlog.md 的新需求区，建议 /forge-prd 立项docs/bugfix/backlog.md 的待澄清区docs/bugfix/backlog.md / 报告中演进历史和设计决策背景见
forge-cookbook/docs/forge-bugfix-changelog.md。
docs/bugfix/backlog.md。docs/bugfix/reviews/BF-XX.md，经 forge-qa 和用户/批次两层验收后才进 P7；P8 结案时归档到 docs/archive/raw/bugfix-reviews/。docs/bugfix/backlog.md，绝不在当前修复内夹带。.forge/active.md 追加一行会话登记；P2 推荐前必须读 .forge/active.md 做功能域判重；P7 合并前必须跑 git merge --no-commit --no-ff 预演。清理 active 的责任在 forge-fupan 或 /forge-status，不在 forge-bugfix 自己。blocked-human 并让用户判断，禁止无限循环。.claude/settings.local.json 预置 allow 规则（AI 代改会被反自授权拦截）；禁止逐次撞权限门后原样重试。═══════════ 会话级（每会话一次，多次修复复用）═══════════
P0 环境探测（前置脚本，自动执行）
P1 问题理解 + 强制读 PRD/ENGINEERING/Bugfix 历史/Memory
═══════════ 每次修复（一次一 bug，可循环）═══════════
P2 范围推荐
├─ AI 从 docs/bugfix/backlog.md 捞候选 + 列出本会话新报告的 bug
├─ AI 接收 forge-qa 发现的结构化 bug（若来自 QA 自动闭环）
├─ 推荐"本次修 X"（1 个 / 或 1-2 共因），其余 → backlog
└─ 用户确认范围
P2.5 创建/更新 Bug 修复验收报告 docs/bugfix/reviews/BF-XX.md
├─ 写入来源、现象、初始证据、Feature Spec 场景、功能域、当前状态
└─ 同步 backlog.md 的报告链接
P3 创建 worktree（端口预检）+ 复现
P4 根因追踪 + 假设验证 + 5 Whys + 修复方案确认
P5 worktree 内独立 TDD 驱动修复 + 原子提交
P5.3 ⭐ 更新 Bug 修复验收报告为待 QA 状态
├─ 写入 TDD 红绿证据、根因、修复摘要、commit、涉及文件
└─ 写入人工验收指南草案，QA 区域留给 forge-qa
P6 ⭐ 调用 forge-qa 自动验收
├─ forge-qa 针对每个验证项跑自动化测试
├─ 强校验 Frontend/Backend 地址、PID、cwd、commit 一致性
├─ 把每个前端交互关键步骤截图嵌入报告
├─ QA 全过 → 单 bug 模式进 P6.5；批量模式标记 qa-pass-pending-final-review
└─ QA 有挂 → 有界回 P5；达到上限或有疑问则 blocked-human
P6.5 ⭐ 用户人工验收 / 批次最终验收
├─ AI 输出"请人工验收 @ docs/bugfix/reviews/BF-XX.md"
├─ 用户打开文档填"你的验收"列 + 最终结论（Pass / Fail / Pass + 新发现）
└─ 用户说"验收了" → AI 读报告 → 判定
P7 ⭐ 按最终结论分流
├─ Pass → worktree 合并决策（合并 / 暂存 / 推迟）
├─ Fail → 回 P5（只修原 bug，不接新问题）
└─ Pass + 新发现 → 先完成当前修复的合并/暂存决策 → 进 P7.4
P7.4 ⭐ Pass 边界确认 + 文档更新询问
├─ 告知用户：本次 bug 已完成，当前修复到此关闭
├─ 列出新问题来源：用户反馈 / QA 发现 / AI 发现的衍生问题
├─ 询问是否写入 docs/bugfix/backlog.md / 报告索引
├─ 用户确认 → 进 P7.5 分流，并输出简短接力 prompt
└─ 用户不确认 → 不写 backlog，不继续修新问题，结束本次 bugfix
P7.5 ⭐ 新发现分流到 backlog
├─ 逐条分析，AI 做分类判断（同根 / 独立 bug / 新需求 / 模糊反馈）
├─ 同根（声称时必须举证）→ 新 bug 建议在新会话修
├─ 独立 bug → backlog.md 的 🐛 待修区，分配 BF-XX
├─ 新需求 → backlog.md 的 💡 新需求区，建议 /forge-prd 立项
└─ 模糊反馈 → backlog.md 的 🌀 待澄清区
P8 沉淀：归档 backlog 对应条目 + BF 报告移动到 archive/raw
═══════════ 出口 ═══════════
- 用户想继续修下一个 bug → 默认建议新会话或 /clear、/compact
（除非明确共因才本会话继续，由用户主动选择）
- 全部完成 → 建议 /forge-review、/forge-ship 或 /forge-fupan
红线：
本文件只保留哲学、铁律、流程总览和 P8 收尾。执行各阶段前必须先读对应手册：
| 阶段 | 必读文件 | 内容 |
|---|---|---|
| P0-P1（会话级准备） | references/p0-p1-session-setup.md | 环境探测脚本、active.md 判重、PRD/ENG/历史阅读 |
| P2/P2.5（定范围建报告） | references/p2-scoping.md | backlog 捞候选、范围确认、BF 报告创建 |
| P3-P5.3（修复循环） | references/p3-p5-fix-loop.md | worktree/复现、根因/5 Whys、TDD 修复、报告更新 |
| P6-P7.5（验收与分流） | references/p6-p7-acceptance.md | forge-qa 调用、人工验收、分流、边界确认 |
规矩：骨架没写的操作细节一律以对应手册为准；手册与骨架冲突时，以骨架的铁律和红线为准。
Mode B 调用 forge-qa 的参数契约以 ~/.claude/skills/forge-qa/SKILL.md「调用模式」节为唯一出处，本 skill 不再复制该表。
docs/bugfix/reviews/{BUG_ID}.md 是处理中的案卷；结案后进入 archive/raw，成为历史证据。P8 只做这些硬动作：
docs/archive/raw/bugfix-reviews/{BUG_ID}.md；已处理区永久保留。docs/bugfix/reviews/{BUG_ID}.md 移动到 docs/archive/raw/bugfix-reviews/{BUG_ID}.md，frontmatter status 改为 archive，并确认截图链接仍可打开。docs/bugfix/batches/BATCH-YYYY-MM-DD.md，用于最终人工验收汇总；每个 bug 的技术证据仍回到各自 BF 报告。/forge-review。/clear、/compact 后继续下一个 bug；全部完成则建议 /forge-review、/forge-ship、/forge-fupan 或 /forge-status。docs/bugfix/backlog.md，不进 TODO；顺手重构想法只写代码注释。