Claude Code Game Studios/smoke-check技能深度解析：实现到 QA 交接前的自动化冒烟测试关口
【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios
/smoke-check是 CCGS（Claude Code Game Studios）技能体系中负责"实现 → QA 交接"的关键路径关口技能：它自动检测测试环境、经 Bash 运行引擎自动化测试套件、对照 sprint stories 扫描测试覆盖率，并用AskUserQuestion分批与开发者确认人工冒烟项，最终在用户批准后把报告写入production/qa/smoke-[date].md。读完本文，你将掌握该技能的完整执行协议、PASS / PASS WITH WARNINGS / FAIL 三种判决的判定边界、五类测试场景的预期行为与断言，以及在 Godot / Unity / Unreal 引擎项目中落地这一冒烟关口的实战方法。
一、技能定位：生产阶段 QA 周期中的硬性关口
在 CCGS 的七阶段流水线中，/smoke-check属于Phase 5 Production 阶段的每个 sprint QA 周期。根据 skill-flow-diagrams.md 中的 QA Pipeline 图示，其位置是：
/qa-plan ─────► production/qa/qa-plan-sprint-NN.md │ ▼ /smoke-check │ ├── PASS → QA hand-off cleared └── FAIL → block sprint close → fix critical paths first │ ▼ /regression-suite → /test-evidence-review → /test-flakinessWORKFLOW-GUIDE.md 将其定位为 "Critical path smoke test gate before QA hand-off"，预估消耗 5-6 步。它承接/qa-plan产出的测试计划，把"代码实现完成"这一状态正式推向 QA 验收；只有它返回 PASS，sprint 才能继续走向/story-done关闭故事，否则会阻塞 sprint close。
与/team-qa的联动关系也值得注意：/team-qa的 Phase 4（smoke check）是一个硬门，FAIL 会直接停止整个 QA 循环，且其失败处置会明确建议 "re-run/smoke-check"（见 team-qa.md）。也就是说，/smoke-check既服务于单 sprint 的日常交接，也是团队级全量 QA 流程的前置闸门。
二、核心工作流：五步完成冒烟检查
/smoke-check的执行流程可归纳为五个阶段：
| 阶段 | 动作 | 关键工具/输入 |
|---|---|---|
| Phase 1 | 检测测试环境：查找tests/目录、从technical-preferences.md识别引擎、确认 QA 计划是否存在 | technical-preferences.md、production/qa/qa-plan-sprint-*.md |
| Phase 2 | 经 Bash 运行自动化测试套件并解析输出 | 引擎无头运行命令（如godot --headless --script tests/gdunit4_runner.gd） |
| Phase 3 | 扫描测试覆盖率：核对每个 sprint story 是否有对应测试文件 | sprint 故事文件与tests/下测试文件 |
| Phase 4 | 用AskUserQuestion分批次确认人工冒烟项（Batch 1 核心稳定性、Batch 2 sprint 机制、Batch 3 附加项） | AskUserQuestion |
| Phase 5 | 组装报告 → 询问 "May I write…" → 批准后写入production/qa/smoke-[date].md→ 给出判决 | 写文件权限 |
关键约束：必须先经 Bash 运行自动化测试，再向开发者提出任何人工冒烟问题，保证自动化证据先于主观确认。
三、判决体系：PASS / PASS WITH WARNINGS / FAIL
三种判决的触发条件定义严格，是协议合规检查（Protocol Compliance）的核心：
| 判决 | 触发条件 | 对流程的影响 |
|---|---|---|
| PASS | 自动化测试全部通过 + 所有人冒烟项通过 + 无 MISSING 覆盖率 | 允许 QA hand-off，可继续/story-done |
| PASS WITH WARNINGS | 自动化测试通过或NOT RUN+ 所有关键检查通过，但存在建议性缺口（如部分故事缺少测试覆盖、引擎二进制不可用） | 构建可交接 QA，但缺口需在/story-done关闭受影响故事前解决 |
| FAIL | 任一自动化测试失败，或 Batch 1 / Batch 2 冒烟项返回 FAIL | 阻塞 QA 交接，提示修复后重跑/smoke-check |
两个重要的边界规则：
- NOT RUN 不等于 FAIL：当引擎二进制不在 PATH 上导致自动化测试无法执行时，记为警告（warning）并按 PASS WITH WARNINGS 处理，而不是直接 FAIL；
- 只有 FAIL 才触发强制阻断：MISSING 覆盖率只构成警告；Batch 3 的失败响应不会单独触发 FAIL（FAIL 仅由自动化测试失败或 Batch 1/Batch 2 的 FAIL 响应触发）。
FAIL 判决附带的标准提示语为："The smoke check failed. Do not hand off to QA until these failures are resolved."，并列出失败测试名、给出修复后重跑/smoke-check的建议。
四、静态断言：可自动验证的结构性要求
/skill-test static可在无需 fixture 的情况下自动验证以下结构要求（这五个检查项与 skill-test-spec.md 模板中的 Static Assertions 一脉相承）：
- 具备全部必需 frontmatter 字段：
name、description、argument-hint、user-invocable、allowed-tools； - 至少 2 个阶段标题（phase headings）；
- 包含判决关键词：PASS、PASS WITH WARNINGS、FAIL；
- 在写报告前包含 "May I write" 协作协议用语；
- 末尾提供下一步交接指引（FAIL 时指向
/bug-report，PASS 时给出 QA 交接指引）。
五、五类测试场景详解（Test Cases）
/smoke-check的规格文档针对五种典型场景给出了完整的 fixture、预期行为与断言，这是验证技能实现是否合格的可执行契约。
Case 1：Happy Path —— 全绿放行（PASS）
Fixture 状态：tests/目录存在且含 GDUnit4 运行脚本；technical-preferences.md标记引擎为 Godot；production/qa/qa-plan-sprint-005.md已存在；自动化运行器报告 12 个测试全部通过（12 passing, 0 failing）；开发者确认 Batch 1 与 Batch 2 全部 PASS；所有 sprint stories 都有匹配测试文件。
预期行为链：
- 检测测试目录与引擎，确认 QA 计划存在；
- 经 Bash 运行
godot --headless --script tests/gdunit4_runner.gd； - 解析输出：12/12 通过；
- 扫描覆盖率——所有 stories 为 COVERED 或 EXPECTED；
- 用
AskUserQuestion询问 Batch 1（核心稳定性）与 Batch 2（sprint 机制）； - 开发者全部选择 PASS；
- 组装报告：自动化测试 PASS、冒烟项全 PASS、无 MISSING 覆盖率；
- 询问"May I write this smoke check report to
production/qa/smoke-[date].md?"； - 批准后写报告；
- 给出判决 PASS。
断言：自动化运行器必须经 Bash 调用；人工冒烟必须走AskUserQuestion；写文件前必须问 "May I write"；报告写入production/qa/smoke-[date].md；判决为 PASS。
Case 2：失败路径 —— 自动化测试失败即 FAIL
Fixture 状态：tests/存在、引擎为 Godot；运行器报告 10 个测试中 8 通过、2 失败（test_health_clamp_at_zero、test_damage_calculation_negative）；QA 计划存在。
预期行为链：运行自动化测试 → 解析出 2 个失败 →记录失败测试名→ 仍走完人工冒烟批次 → 报告将自动化测试标记为 FAIL 并列出失败测试名 → 询问并写报告 → 给出 FAIL 判决及阻断提示，建议修复后重跑/smoke-check。
断言：失败测试名必须出现在报告中；判决为 FAIL；判决后消息必须指引先修复再交接 QA；必须建议重跑/smoke-check。
Case 3：人工确认 + 覆盖缺口 —— PASS WITH WARNINGS
Fixture 状态：tests/存在、引擎为 Godot；自动化测试 8/8 全过；但某个 Logic story 没有匹配测试文件（MISSING coverage）；开发者确认 Batch 1、Batch 2 全 PASS。
预期行为链：自动化测试 PASS → 覆盖率扫描发现 1 个 MISSING（Logic story）→AskUserQuestion确认冒烟项全 PASS → 报告显示：自动化测试 PASS、人工检查全 PASS、1 个 MISSING 覆盖率条目 → 判决为PASS WITH WARNINGS（而非 PASS 或 FAIL），并附建议说明：构建可交 QA，但该 MISSING 条目必须在/story-done关闭受影响故事前解决。
断言：人工冒烟必须用AskUserQuestion（而非内联文本提示）；MISSING 条目必须出现在报告中；判决必须是 PASS WITH WARNINGS；建议性说明必须提到/story-done前置条件。
Case 4：无测试目录 —— 停止并给出补救指引
Fixture 状态：tests/目录不存在，引擎配置为 Godot。
预期行为：Phase 1 检测不到tests/→ 输出"No test directory found attests/. Run/test-setupto scaffold the testing infrastructure, or create the directory manually if tests live elsewhere."→技能立即停止：不运行自动化测试、不做人工冒烟、不写报告。
断言：错误消息指明缺失的tests/目录；建议/test-setup作为补救步骤；技能在消息后停止（不再执行后续阶段）；不写任何报告文件。
Case 5：导演关卡检查 —— 无门通过
Fixture 状态：测试环境合法、自动化测试通过、人工冒烟确认完成。
预期行为：技能跑完所有阶段并产出 PASS 或 PASS WITH WARNINGS；全程不唤起任何 director agent；输出中不出现任何 gate ID（CD-*、TD-*、AD-*、PR-*）；不调用/gate-check。
断言：未调用任何导演关卡；无 gate skip 消息；判决只在 PASS / PASS WITH WARNINGS / FAIL 三选一，与门控判决体系完全无关。
六、协议合规要求：协作协议是硬性约束
规格文档将以下行为列为必须遵守的协议（Protocol Compliance），也是自动化断言的基础：
- 所有人工冒烟批次（Batch 1、Batch 2、Batch 3）一律使用
AskUserQuestion，禁止用内联文本提问； - 先经 Bash 运行自动化测试，再询问任何人工问题；
- 写报告文件前必须问 "May I write"，未经批准绝不写入；
- 判决词汇严格限定为 PASS / PASS WITH WARNINGS / FAIL，无其他判决；
- FAIL 仅由自动化测试失败或 Batch 1/Batch 2 的 FAIL 响应触发；
- PASS WITH WARNINGS 仅在存在 MISSING 测试覆盖但无关键失败时触发；
- NOT RUN（引擎二进制不可用）记为警告而非 FAIL；
- 全程不调用导演关卡。
这套协议与 skill-test-spec.md 模板中的通用 Protocol Compliance（写前询问、先展示再请求批准、以推荐下一步收尾、未经批准不自动创建文件）完全一致，体现了 CCGS 对"Agent 写文件必须经过用户授权"这一协作原则的强制落地。
七、变体与边界：quick、--platform 与 NOT RUN
规格文档的 Coverage Notes 明确声明了三类未单独 fixture 测试的变体，其行为模式如下：
quick参数：跳过 Phase 3 覆盖率扫描与 Batch 3，其余流程与 Case 1 相同，输出中会附带 coverage-skip 说明；--platform参数：追加平台专属的AskUserQuestion批次，并生成按平台分列的判决表；- NOT RUN 场景：引擎二进制不在 PATH 时按 PASS WITH WARNINGS 模式处理，由上述协议合规断言覆盖。
八、引擎无关性：三种引擎下的运行命令
虽然规格文档的用例以 Godot 为主 fixture，但/smoke-check的引擎检测逻辑使其天然跨引擎工作。引擎选择在 Phase 4（Pre-Production）由/test-setup依据technical-preferences.md完成脚手架搭建（见 test-setup.md）：
| 引擎 | 测试框架 | 冒烟阶段运行命令 |
|---|---|---|
| Godot 4 + GDScript | GdUnit4 | godot --headless --script tests/gdunit4_runner.gd |
| Unity + C# | Unity Test Runner（Tests/+ asmdef，EditMode/PlayMode） | Unity 无头批处理运行器 |
| Unreal Engine | Unreal headless runner | 无头运行器（-nullrhi参数） |
/smoke-check只需读取检测到的引擎配置即可拼装对应的自动化测试命令；若tests/缺失，则回退到 Case 4 的停止-指引行为。这也解释了为什么 Case 1 的 fixture 中technical-preferences.md是关键输入——它是引擎检测的唯一权威来源。
九、与周边技能的完整协同
/smoke-check不是孤岛，它处在一条完整的 QA 工具链中（全部在 catalog.yaml 中注册为 utility 类别）：
- 上游：
/qa-plan依据coding-standards.md的测试证据表为每个 story 分配测试类型（Logic → 单元测试 BLOCKING、Config/Data → smoke check ADVISORY），产出production/qa/qa-plan-sprint-NN.md供冒烟阶段核对；/test-setup保证tests/基础设施就绪； - 下游：PASS 后进入
/regression-suite（覆盖缺口 + 回归测试清单）、/test-evidence-review（证据质量而非仅存在性）、/test-flakiness（flaky 测试报告），最终由/story-done关闭故事； - FAIL 分支：转
/bug-report登记缺陷，修复后重跑/smoke-check； - 团队级：
/team-qa的 Phase 4 将 smoke check 作为硬门，FAIL 时整个 QA 循环停止。
十、如何验证与扩展这套规格
/skill-test系列命令提供了验证入口：/skill-test static在无 fixture 条件下验证静态断言（frontmatter、阶段标题、判决关键词、协作协议、交接指引）；/skill-test spec则按本文第五节的测试用例逐一验证行为。若需新增变体场景（如新的引擎、新的平台批次），可参照本文结构在规格文档中追加 fixture + 预期行为 + 断言三元组，并同步更新 catalog.yaml 中对应条目。
小结
/smoke-check用一套可自动断言的规格，把"实现是否达到 QA 交接标准"这一模糊判断变成了可重复、可验证、有人工兜底的工程协议：自动化证据先行、人工冒烟分批确认、覆盖率缺口显式暴露、写文件全程征求授权、判决词汇严格三选一。无论你的 CCGS 项目运行在 Godot、Unity 还是 Unreal 上，这套关口都能以同一套心智模型守住实现与 QA 之间的最后一道防线。
【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
