qa-plan

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,system_overrides

已在上方解析——按原样使用。没有配置块时 → 使用 .claude/docs/config-resolution.md 中的默认值。

QA 计划

此技能可为一个冲刺、功能或单个故事生成结构化 QA 计划。它会读取所有范围内的故事文件及其引用的 GDD，将每个故事按测试类型分类，并生成一份计划，明确告知开发者需要自动化哪些内容、需要手动验证哪些内容、冒烟测试的范围，以及何时需要引入游戏测试员。

请在冲刺开始前运行此技能，以便团队提前了解所需的测试工作。在实现完成后才编写的测试计划是事后总结，而非计划。

输出： production/qa/qa-plan-[sprint-slug]-[date].md

---

每次调用 AskUserQuestion 都遵循 .claude/docs/automation-modes.md（协作模式始终提问 · 引导模式仅针对重大事项提问 · 自主模式记录并继续；automation_always_ask 类别始终提示）。

工作流层级：读取每个 GDD 时，根据其所属系统进行解析（参见 .claude/docs/workflow-modes.md）：如果配置块中列出了 workflow_overrides.system_overrides.<system>，则使用该值，否则使用项目级值。此值决定从多少个 GDD 章节中提取测试计划内容——参见阶段 2。

qa.level：在 minimal 级别，仅生成最简冒烟测试计划——删除要求自动化测试的行和测试文件的 DoD；在 standard 级别，按故事类型生成完整计划；在 full 级别，还要添加每个系统的覆盖率目标。它与 workflow 是两个不同的维度（后者决定提取多少个 GDD 章节）。无论哪个级别，都不会删除视觉／手感和 UI 截图相关行——minimal 级别会豁免测试，但不会忽略外观（.claude/docs/coding-standards.md）。

第 1 阶段：解析范围

参数： $ARGUMENTS（空白 = 通过 AskUserQuestion 询问用户）

根据参数确定范围：

• sprint — 读取 production/sprints/ 中最新的文件，提取其中引用的 每个故事文件路径。如果 production/sprint-status.yaml 存在， 则将其作为主要故事列表，并从 sprint 计划中获取故事元数据。
• feature: [system-name] — 使用 glob 匹配 production/epics/*/story-*.md，筛选 文件路径或标题中包含系统名称的故事。同时检查该系统目录中的 epic 索引 文件（EPIC.md）。
• story: [path] — 验证路径存在，并加载该文件。
• 无参数 — 使用 AskUserQuestion：
  • “此 QA 计划的范围是什么？”
  • 选项：“当前 sprint”、“特定功能（输入系统名称）”、 “特定故事（输入路径）”、“完整 epic”

确定范围后，报告：“正在为 [N] 个故事构建 [scope] 的 QA 计划。”

如果引用的故事文件路径对应的文件不存在，将其标记为 MISSING，并继续处理其余故事。不要因单个文件缺失而导致整个计划失败。

如果解析后的范围包含零个故事，立即停止——不要构建计划。 报告 NOT ASSESSED — no stories in scope，指出搜索的范围 和为空的路径，并按以下方式处理：

• production/sprints/ 中没有文件 → “未找到 sprint 计划。运行 /sprint-plan new。” 在 workflow: minimal 中，按设计不会有 sprint——改为转至 /qa-plan feature: [epic-slug] 或 /qa-plan story: [path]。
• sprint 计划存在，但未引用任何故事 → “Sprint 计划 [path] 中没有列出 故事。运行 /create-stories [epic-slug]。”
• feature:/story: 范围没有匹配项 → 指出返回空结果的 glob。

必须执行 N=0 检查。 若不执行，空范围会报告“正在为 0 个故事构建 QA 计划”，并继续进入第 4 阶段，生成包含空表格的计划文档——而且零故事的 QA 计划看起来与已完成的 QA 计划完全一样。 此技能负责把关并移交给人工 QA，因此这里的误报通过会让构建仅凭一份没有测试任何内容的计划就进入 QA。

本段开头的规则仍然适用：多个文件中有一个缺失时，应标记为 MISSING 并继续。 这里说的是没有“多个”文件的另一种情况。

---

阶段 2：加载输入

先确定分母——对范围内的故事文件使用 glob 并计数为 N—— 然后使用有针对性的章节 grep，而不是完整读取每个故事，收集以下字段。QA 计划需要每个故事的类型和验收标准；不需要其实现说明、范围外边界或 ADR 理由。为了获取两个章节而完整读取 N 个故事，正是本阶段耗时所在：

Grep pattern="^## Acceptance Criteria" glob="production/epics/**/story-*.md" output_mode="content" -A 15
Grep pattern="^> \*\*(Type|Status|Estimate)\*\*" glob="production/epics/**/story-*.md" output_mode="content"
Grep pattern="^## (Context|Dependencies)" glob="production/epics/**/story-*.md" output_mode="content" -A 8

（在 sprint 模式下，将 glob 范围限定为 sprint 计划中的故事路径。）从中获取：

• 故事标题和故事 ID——从文件名和路径获取；无需读取文件
• Story Type 字段——从标头 grep 获取（例如，Type: Logic）
• 验收标准——从第一次 grep 获取完整的编号列表或项目符号列表
• GDD / ADR 引用和依赖项——从 ## Context grep 获取
• 预估工作量——如果存在，从标头 grep 获取
• 实现文件和引擎说明——仅当测试计划确实会用到这些信息时才需要；完整读取这些单独的故事

切勿将缺少章节视为缺少故事。 如果某个故事未匹配到 ## Acceptance Criteria，就完整读取该故事并注明这一点——没有可测试标准的故事本身就是一项 QA 发现，而不是可以跳过的故事。

读取故事后，加载一次辅助上下文（而不是每个故事都加载一次）：

• design/gdd/systems-index.md——了解系统优先级以及哪些 GDD 已获批准
• 对所有故事中引用的每个唯一 GDD：根据该系统的工作流级别（上文已确定）提取测试材料——full 级别提取全部 8 个章节；standard 级别提取必需章节中与测试相关的部分（始终包括验收标准和边界情况，并且任何定义数值规则的系统还需包括公式）；minimal 级别仅提取验收标准。不要加载完整的 GDD 文本。使用 Grep 工具查找章节标题（模式 ^#，内容模式），再使用带有 offset 和 limit 的 Read 工具读取相应范围。这些章节包含可测试的需求、需要验证的数学规则，以及测试必须覆盖的边界条件。如果没有边界情况章节（或 minimal 级别不需要该章节），请针对每个 GDD 记录：「未找到边界情况章节——边界情况覆盖将仅根据验收标准推断。」
• docs/architecture/control-manifest.md——检查应由自动化测试防范的禁止模式（如果文件存在）

如果故事未引用 GDD，请将其记为一项缺口，但不要因此阻止计划。 仅根据验收标准对该故事进行分类。

---

阶段 3：为每个故事分类

为每个故事指定一个故事类型：

• 如果故事的标题中已有 Type: 字段：照原样接受。不要根据以下标准重新分类或验证——该 Type 在创建故事时由主程序员设定，具有权威性。照原样记录。
• 如果缺少 Type: 字段：根据下表中的验收标准推断类型，并在报告中注明该类型是推断得出的（而非明确声明的）。将此标记为一个缺漏——在开始实施之前，应明确声明该故事的 Type。

故事类型	分类指标
Logic	验收标准涉及计算、公式、数值阈值、状态转换、AI 决策、数据验证、增益／减益叠加、经济交易，或任何可测试的计算
Integration	标准涉及两个或更多系统交互、信号或事件跨系统边界传递、存档／加载往返、网络同步或持久化
Visual/Feel	标准涉及动画行为、VFX、着色器输出、“响应灵敏的感觉”、感知到的时机、屏幕震动、粒子效果、音频同步或视觉反馈质量
UI	标准涉及菜单、HUD 元素、按钮、屏幕、对话框、库存面板、工具提示或任何面向玩家的界面元素
Config/Data	变更仅限于平衡调整值、数据文件或配置，不涉及新的代码逻辑

混合型故事（例如，同时添加公式和 UI 显示的故事）： 根据哪些验收标准带来的实施风险最高，指定主要类型，并注明次要类型。Logic+Integration 或 Visual+UI 是最常见的混合组合。

为所有故事完成分类后，请在继续阶段 4 之前，在对话中生成分类摘要表。这样用户可以了解测试将如何分配。

---

阶段 4：生成测试计划

汇总完整的 QA 计划文档。使用以下结构：

# QA Plan: [Sprint/Feature Name]
**Date**: [date]
**Generated by**: /qa-plan
**Scope**: [N stories across [N systems]]
**Engine**: [engine name — `engine.name` from project.yaml if present and non-empty, else the Engine field from .claude/docs/technical-preferences.md, else "Not configured"]
**Sprint File**: [path to sprint plan if applicable]

---

## Test Summary

| Story | Type | Automated Test Required | Manual Verification Required |
|-------|------|------------------------|------------------------------|
| [story title] | Logic | Unit test — `tests/unit/[system]/` | None |
| [story title] | Integration | Integration test — `tests/integration/[system]/` | Smoke check |
| [story title] | Visual/Feel | None (not automatable) | Screenshot + lead sign-off |
| [story title] | UI | None (verified by its screenshots) | Retained screenshot of each screen touched |
| [story title] | Config/Data | Data validation test | Spot-check in-game values |

---

## Automated Tests Required

*(At `qa.level: minimal`, omit this entire section and blank the Test Summary's
"Automated Test Required" column — automated tests are not required there; list
manual/smoke verification only.)*

### [Story Title] — [Type]
**Test file path**: `tests/[unit|integration]/[system]/[story-slug]_test.[ext]`
**What to test**:
- [Specific formula or rule from the GDD Formulas section]
- [Each named state transition or decision branch]
- [Each side effect that should or should not occur]

**Edge cases to cover**:
- Zero/minimum input values (e.g., 0 damage, empty inventory)
- Maximum/boundary input values (e.g., max level, stat cap)
- Invalid or null input (e.g., missing target, dead entity)
- [Any edge case explicitly called out in the GDD Edge Cases section]

**Estimated test count**: ~[N] unit tests

[If no GDD formula reference was found for this story, note:]
*No formula found in referenced GDD — test cases must be derived from acceptance
criteria directly. Review the GDD Formulas section before writing tests.*

---

## Manual QA Checklist

### [Story Title] — [Type]
**Verification method**: [Screenshot + designer sign-off | Playtest session |
Manual step-through | Comparison against reference footage]
**Who must sign off**: [designer / lead-programmer / qa-lead / art-director]
**Evidence to capture**: [screenshot of X | video clip of Y | written playtest
notes | side-by-side comparison]

Checklist:
- [ ] [Specific observable condition — concrete and falsifiable]
- [ ] [Another condition]
- [ ] [Every acceptance criterion translated into a manual check item]

*If any criterion uses subjective language ("feels", "looks", "seems"), it must
be supplemented with a specific benchmark or a playtest protocol note.*

---

## Smoke Test Scope

Critical paths to verify before any QA hand-off for this sprint:

1. Game launches to main menu without crash
2. New game / new session can be started
3. [Primary mechanic introduced or changed this sprint]
4. [Any system with a regression risk from this sprint's changes]
5. Save / load cycle completes without data loss (if save system exists)
6. Performance is within budget on target hardware (no new frame spikes)

*Smoke tests are verified by the developer via `/smoke-check`. Reference this
list when running that skill.*

---

## Playtest Requirements

| Story | Playtest Goal | Min Sessions | Target Player Type |
|-------|--------------|--------------|-------------------|
| [story] | [What question must the session answer?] | [N] | [new player / experienced] |

**Sign-off requirement**: Playtest notes must be written with `/playtest-report` to
`production/qa/playtests/` (naming the story) and reviewed by
the [designer / qa-lead] before the story can be marked COMPLETE.

If no stories require playtest validation: *No playtest sessions required for
this sprint.*

---

## Definition of Done — This Sprint

A story is DONE when ALL of the following are true (at `qa.level: minimal`, drop
the test-file and smoke rows below — tests are waived there; the screenshot and
sign-off rows stay at every level, because the look is not):

- [ ] All acceptance criteria verified — via automated test result OR documented
      manual evidence (screenshot, video, or playtest notes with sign-off)
- [ ] Test file exists at the specified path for all Logic and Integration stories *(qa.level standard/full)*
- [ ] Retained screenshot of each screen touched, in `production/qa/evidence/`, for all Visual/Feel and UI stories *(every qa.level)*
- [ ] Signed-off evidence doc at `production/qa/evidence/[story-slug]-evidence.md` for all Visual/Feel stories *(every qa.level)*
- [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off) *(qa.level standard/full)*
- [ ] No regressions introduced
- [ ] Code reviewed (via `/code-review` or documented peer review)
- [ ] Story file updated to `Status: Complete` (via `/story-done`)

生成内容时，请使用阶段 2 中提取的实际故事标题、GDD 公式文本和验收标准。不要使用占位文本——每个测试条目都应反映这些特定故事的实际要求。

---

阶段 5：写入输出

在对话中展示完整计划（如果计划很长，则展示摘要），然后使用 AskUserQuestion 同时提出两个问题：

question: "Ready to write the QA plan. Choose output options:"
multiSelect: true
options:
  - "Write QA plan to production/qa/qa-plan-[sprint-slug]-[date].md"
  - "Also back-fill test case specs into each story file's ## QA Test Cases section (Recommended — enables /dev-story and /code-review traceability)"

如果选择“Write QA plan”：按生成内容原样写入计划文件，不要截断。

如果选择“Also back-fill story files”：对于范围内的每个 Logic 和 Integration 故事，编辑其路径下的故事文件。找到 ## QA Test Cases 部分，并将其内容替换为阶段 4 中为该故事生成的测试用例规范。如果故事没有 ## QA Test Cases 部分，则将其追加到 ## Test Evidence 之前。对于 Visual/Feel 和 UI 故事，写入手动验证步骤，而不是测试规范。

写入后：

"QA 计划已写入 production/qa/qa-plan-[sprint-slug]-[date].md。

后续步骤：

• 在 Sprint 实施开始前，将此计划分享给团队
• 所有 Sprint 故事实施完成后，运行 /smoke-check sprint，以此作为 QA 交接的关卡——现在不要运行，只有在实施完成后才运行
• 对于 Logic/Integration 故事，在将故事标记为完成之前，请在列出的路径创建测试文件——/story-done 会检查这些文件"

静默追加到 production/session-state/active.md（如果文件不存在，则创建该文件）：

最后给出结论：COMPLETE — QA 计划已写入（或如果未获准写入，则为 COMPLETE — QA 计划已展示，未写入）。唯一其他结果是阶段 1 中的 NOT ASSESSED — no stories in scope 路径。

---

协作协议

适用于 collaborative 模式（默认模式）。 关于 guided 和 autonomous 模式，请参阅 .claude/docs/automation-modes.md——以下规则 说明的是协作模式的要求，并非通用行为。

• 未经询问，绝不编写计划——第 5 阶段必须获得明确批准。
• 谨慎分类：当某个故事在 Logic 和 Integration 之间存在歧义时，将其归为 Integration——它需要同时进行单元测试和 集成测试。
• 不要编造测试用例，超出验收标准和 GDD 公式所支持的范围。如果 GDD 中缺少 某个公式，请将其标出，不要猜测。
• 试玩要求仅供参考：对于处于 Visual/Feel 边界的故事，由用户决定是否需要试玩。请标出 相关情况；不要强制要求。
• 未提供参数时，使用 AskUserQuestion 选择范围。 其他所有阶段均不得进行交互——先呈现结果，再询问一次是否批准写入。