day-one-patch

首日补丁

每款已发布的游戏都有首日补丁。提前规划，才能避免发布日陷入混乱。这项技能会将补丁范围限定在安全且必要的内容，并通过轻量级 QA 流程把关，确保在发布任何内容之前已有回滚计划。这是一次小型冲刺——不是热修复，也不是完整冲刺。

适用时机：

• 黄金母版构建已锁定后（认证已通过或已标记为发布候选版本）
• 已知存在一些 Bug，但在黄金母版中修复风险过高时
• 认证反馈要求在提交后进行小幅修复时
• 发布前试玩在通过发布关卡后发现必须修复的问题时

首日补丁范围规则：

• 仅包含可安全快速修复的 P1/P2 Bug
• 不添加新功能——只修复问题
• 不进行重构——改动保持在最低限度
• 任何预计需要超过 4 小时开发时间的修复都应归入补丁 1.1，而非首日补丁

输出： production/releases/day-one-patch-[version].md

---

阶段 1：加载发布上下文

读取：

• project.yaml 中的 project.stage（若不存在，则读取 production/stage.txt）——确认项目处于 Release 阶段
• production/gate-checks/ 中最新的文件——读取发布关卡的评估结果
• production/qa/bugs/*.md——加载状态为 Open 或 Fixed — Pending Verification 的所有 Bug
• production/sprints/ 中最新的文件——了解已发布的内容
• production/security/security-audit-*.md 中最新的文件——检查是否有未解决的安全问题

如果解析出的阶段（project.yaml → stage.txt）不是 Release 或 Polish：

"首日补丁准备适用于 Release 阶段的项目。当前阶段：[stage]。在项目接近发布之前，不适合使用此技能。"

核实前提，不要想当然。 这项技能完全依赖于已有一个通过发布关卡的黄金母版——这个前提正是采用轻量级 QA 流程而非完整流程的依据。因此应当核实，而不是根据阶段值推断：

• production/gate-checks/ 中没有文件，或没有文件记录发布关卡的评估结果：报告 Release gate: NOT ASSESSED — no gate-check record found。不要默默继续。明确说明，下方缩减后的 QA 范围所依据的关卡记录无人能找到，并询问是否先运行 /gate-check，或改为执行完整的 QA 流程。
• 最新记录的结果为 FAIL、CONCERNS 或 NOT ASSESSED：指出该记录并停止。基于从未通过关卡的构建制作首日补丁，这就不是首日补丁，而是迟来的发布关卡，且针对了错误范围的改动。
• 仅凭 project.stage: Release 不能证明这一点。阶段只表明项目所处的位置；关卡记录才是项目有资格处于该阶段的证据。

---

阶段 2：确定补丁范围

步骤 2a — 对未解决的 Bug 进行分类，确定是否纳入补丁

对每个未解决的 Bug，评估：

标准	是否纳入首日补丁？
S1 或 S2 严重性	是——若可安全修复，则必须纳入
P1 优先级	是
修复预计耗时 < 4 小时	是
修复需要更改架构	否——推迟到 1.1
修复会引入新的代码路径	否——风险过高
修复仅涉及数据/配置（不改代码）	是——风险极低
认证反馈要求	是——平台批准所必需
S3/S4 严重性	仅限琐碎的配置修复；否则推迟

步骤 2b — 向用户展示补丁范围

使用 AskUserQuestion：

• 提示词："根据未解决的 Bug 和认证反馈，以下是建议的首日补丁范围。你觉得合适吗？"
• 显示：纳入的 Bug 表格（ID、严重性、描述、预计工作量）
• 显示：推迟的 Bug 表格（ID、严重性、推迟原因）
• 选项：[A] 批准此范围 / [B] 调整 — 我想添加或移除项目 / [C] 不需要首日补丁

如果选择 [C]：输出 "无需首日补丁。继续执行 /launch-checklist。" 然后停止。

第 2c 步 — 检查总范围

汇总预估工作量。如果总计超过 1 天：

“⚠️ 补丁范围为 [N hours]——超出了安全的首日工作窗口。建议将优先级较低的项目推迟到补丁 1.1。首日补丁过于臃肿，带来的风险可能大于消除的风险。”

使用 AskUserQuestion 确认是否继续或缩减范围。

---

阶段 3：回滚计划

编写任何代码之前，先制定回滚流程。这一点不可妥协。

通过 Agent 启动 release-manager。请其制定回滚计划，涵盖：

• 如何在每个目标平台上恢复到黄金母版构建
• 平台特定的回滚限制（某些平台无法回滚认证构建）
• 谁负责触发回滚
• 发生回滚时需要向玩家传达哪些信息

展示回滚计划。询问：“我可以将此回滚计划写入 production/releases/rollback-plan-[version].md 吗？”

在回滚计划写入之前，不要进入阶段 4。

---

阶段 4：实施修复

对于已批准范围内的每项代码修复，启动一个专注的实施循环：

1. 通过 Agent 启动 lead-programmer，并提供：

   • Bug 报告（准确的复现步骤，以及已知的根本原因）
   • 约束：仅实施最小可行修复，不做清理
   • 受影响的文件（来自 Bug 报告的 Technical Context 部分）

   对于每个 Bug，它都会返回最小修复方案及将修改的文件—— 不写入任何内容。

2. 针对整组修复只询问一次：“我可以应用这些修复吗？[BUG-ID → 文件，每项占一行]”。获得批准前不得更改代码。

3. 同意后，将每项已批准的修复交回 lead-programmer（通过一次新的 Agent 调用，并附上其计划），让其实施修复并使用 project.yaml 中的 commands.test 运行针对性测试；如果测试运行器允许，则将测试范围缩小到受影响的测试套件——绝不凭记忆编写测试运行器命令。如果未设置 commands.test，则说明这一点，并为该 Bug 记录 Tests: NOT RUN — commands.test unset。

4. 通过 Agent 启动 qa-tester，验证修复后 Bug 是否仍可复现。

对于仅涉及配置/数据的修复：直接进行更改（无需程序员 Agent）。首先说明文件和更改，并询问：“我可以编辑 [config file]——[key]：[old value] → [new value] 吗？”确认值已更改，并重新运行任何相关的冒烟测试。

---

阶段 5：补丁 QA 门禁

这是一次轻量级 QA 检查，不是完整的 /team-qa。该补丁已通过发布门禁的 QA 审批；我们只需重新验证已更改的部分。

通过 Agent 启动 qa-lead，并提供：

• 所有已更改文件的列表
• 已修复 Bug 的列表（附上阶段 4 中的验证状态）
• 受影响系统的冒烟检查范围

请 qa-lead 判断：定向冒烟检查是否足够，还是有修复涉及需要进行更广泛回归测试的系统？

执行所需的 QA 范围：

• 定向冒烟检查——运行 /smoke-check（不接受系统参数）
• 更广泛的回归测试——使用 project.yaml 中的 commands.test，在引擎的测试根目录中运行受影响系统的测试（Godot 使用 tests/unit/ 和 tests/integration/，Unity 使用 Assets/Tests/，Unreal 使用 Source/<Module>/Private/Tests/——.claude/docs/directory-structure.md）；在测试运行器支持的情况下，将范围缩小到受影响的测试套件——绝不可凭记忆编写测试运行器命令。如果未设置 commands.test，则未评估更广泛的回归测试；请明确说明。

继续之前，QA 结论必须为 PASS 或 PASS WITH WARNINGS。如果为 FAIL：将失败修复排除在首日补丁之外，并推迟到 1.1。

如果 QA 结论为 NOT ASSESSED，则不算通过。 当测试套件从未运行时，/smoke-check 会返回此结论——可能是没有构建产物、没有测试运行器，或无人确认结果。不要据此继续，也不要将其重新解读为 PASS WITH WARNINGS：警告结论意味着有人检查过并发现了轻微问题，而这意味着无人检查。请获取结果（结论会说明如何才能运行测试），否则将修复推迟到 1.1。首日补丁会提供给所有首日购买游戏的玩家，而未经验证的改动最不应该面向这群玩家。

---

阶段 6：生成补丁记录

# Day-One Patch: [Game Name] v[version]

**Date prepared**: [date]
**Target release**: [launch date or "day of launch"]
**Base build**: [gold master tag or commit]
**Patch build**: [patch tag or commit]

---

## Patch Notes (Internal)

### Bugs Fixed
| BUG-ID | Severity | Description | Fix summary |
|--------|----------|-------------|-------------|
| BUG-NNNN | S[1-4] | [description] | [one-line fix] |

### Deferred to 1.1
| BUG-ID | Severity | Description | Reason deferred |
|--------|----------|-------------|-----------------|
| BUG-NNNN | S[1-4] | [description] | [reason] |

---

## QA Sign-Off

**QA scope**: [Targeted smoke / Broader regression]
**Verdict**: [PASS / PASS WITH WARNINGS / NOT ASSESSED]
**QA lead**: qa-lead agent
**Date**: [date]
**Warnings (if any)**: [list or "None"]
**Not assessed (if any)**: [what could not be checked, and why — or "None"]

---

## Rollback Plan

See: `production/releases/rollback-plan-[version].md`

**Trigger condition**: If [N] or more S1 bugs are reported within [X] hours of launch, execute rollback.
**Rollback owner**: [user / producer]

---

## Approvals Required Before Deploy

- [ ] lead-programmer: all fixes reviewed
- [ ] qa-lead: QA gate PASS confirmed
- [ ] producer: deployment timing approved
- [ ] release-manager: platform submission confirmed

---

## Player-Facing Patch Notes

[Draft for community-manager to review before publishing]

[list player-facing changes in plain language]

请询问：“我可以将此补丁记录写入 production/releases/day-one-patch-[version].md 吗？”

---

阶段 7：后续步骤

写入补丁记录后：

1. 运行 /patch-notes，生成面向玩家的补丁说明
2. 补丁上线后，对每个已修复的 Bug 运行 /bug-report verify [BUG-ID]
3. 对每个已验证的修复运行 /bug-report close [BUG-ID]
4. 上线 48–72 小时后，使用 /retrospective [milestone-name]，为 production/milestones/ 中的上线里程碑安排一次上线后回顾

如果补丁后仍有任何 S1 Bug 未关闭：

"⚠️ 仍有 S1 Bug 未关闭，且未包含在补丁中。这些是已接受的风险。请将其记录在回滚计划的触发条件中——如果这些问题大规模出现，回滚可能比后续补丁更合适。"

使用 AskUserQuestion：

• 提示词：“首日补丁已完成。接下来要做什么？”
• 选项：
  • [A] Run /patch-notes — generate player-facing patch notes
  • [B] Run /bug-report to log any issues found post-deploy
  • [C] Stop here

---

协作协议

• 范围控制至关重要——避免范围蔓延；每增加一项内容，风险都会上升
• 始终优先制定回滚计划——没有回滚计划的补丁是不负责任的
• 推迟不等于遗忘——每个推迟的 Bug 都必须列入记录中的“推迟到 1.1”表格；之后运行 /bug-triage，将它们安排到 1.1 冲刺中（如果项目没有冲刺计划，例如采用默认的最简工作流，则将其纳入简报的构建顺序）
• 与玩家沟通也是补丁的一部分——/patch-notes 是必需产出，不可省略