Claude Code Game Studios /smoke-check：QA交接前的冒烟门禁如何跑自动测试、批量确认手工检查并给出三级裁决

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

在 Claude Code Game Studios 里，/smoke-check是"实现完成"和"可以交给 QA"之间的一道门禁：它通过 Bash 运行自动测试套件，扫描当前 sprint 的测试覆盖缺口，再用AskUserQuestion让开发者批量确认手工冒烟项，最后生成一份 PASS / PASS WITH WARNINGS / FAIL 裁决的冒烟报告。这个 skill 的定位很明确——未通过冒烟检查的构建不进入 QA，报告在获得你的明确批准后写入production/qa/smoke-[date].md（[date]为技能按实际日期填充的文件名模式，下同）。本文基于 smoke-check SKILL.md 和 冒烟检查测试规格 说明一次完整运行的操作路径、判定依据和边界。

冒烟门禁的位置与前置条件

/smoke-check属于 QA 与测试命令组，对应工作流第 5–6 阶段，推荐链路是/qa-plan→/smoke-check→/regression-suite（见 工作流指南 和 skill 流程图）。运行前需要满足或确认以下前提，Phase 1 会逐项探测并先输出一份环境摘要，再进入后续阶段：

1. tests/测试目录存在。找不到时技能直接停止，输出提示："No test directory found attests/. Run/test-setupto scaffold the testing infrastructure, or create the directory manually if tests live elsewhere."——此时不跑自动测试、不做手工检查、不写报告。测试框架的脚手架由/test-setup负责（创建tests/unit/、tests/integration/、tests/performance/、tests/playtest/及对应引擎的 runner 配置），其测试规格见 test-setup 测试规格。
2. 引擎已配置：Phase 1 读取.claude/docs/technical-preferences.md中的Engine:值，用于 Phase 2 选择测试命令。引擎未配置时技能会提示先运行/setup-engine。
3. CI 检查：查看.github/workflows/是否包含引用 tests 的 workflow 文件，并在报告中记录 CI 是否配置。
4. QA 计划（强烈建议但不强制）：globproduction/qa/qa-plan-*.md取最近修改的一份，供 Phase 3 覆盖扫描和 Phase 4 冒烟项清单使用。找不到时技能提示 "No QA plan found. Run/qa-plan sprintbefore smoke-checking for best results."，QA 计划由/qa-plan生成，规格见 qa-plan 测试规格。
5. 冒烟测试清单（可选）：依次检查production/qa/smoke-tests.md或tests/smoke/；都没有时 Phase 4 回退到内置标准清单。

Phase 1 结束时会给出类似这样的环境报告（文档原文格式）："Environment: [engine]. Test directory: [found / not found]. CI configured: [yes / no]. QA plan: [path / not found]."

运行命令与参数选择

基础调用就是/smoke-check。参数可以组合，例如/smoke-check sprint --platform console：

日常主路径用/smoke-check（即sprint模式）；如果你刚修完一个失败项想快速确认，用/smoke-check quick。

Phase 2：自动测试如何被执行

技能用 Bash 按检测到的引擎选择命令。这是文档中给出的真实命令，可直接在你的游戏项目里对照：

Godot 4（首选 runner 路径）：

godot --headless --script tests/gdunit4_runner.gd 2>&1

该路径下 GDUnit4 runner 不存在时回退到：

godot --headless -s addons/gdunit4/GdUnitRunner.gd 2>&1

两条路径都找不到 runner 时，技能提示 "GDUnit4 runner not found — confirm the runner path for your test framework."。

Unity：Unity 测试大多需要编辑器，无法在 shell 里 headless 运行。技能改为检查最近一次测试产物：

ls -t test-results/ 2>/dev/null | head -5

存在 XML/JSON 结果文件时读取最新一份解析 PASS/FAIL 计数；没有产物时提示 "Unity tests must be run from the editor or CI pipeline. Please confirm test status manually before proceeding."

Unreal Engine：

ls -t Saved/Logs/ 2>/dev/null | grep -i "test\|automation" | head -5

找不到匹配日志时提示 UE 自动化测试需通过 Session Frontend 或 CI 管线运行，请手动确认状态。

NOT RUN 的处理：如果引擎二进制不在 PATH 或 runner 脚本缺失，测试记为NOT RUN并明确报告原因。NOT RUN 不是自动 FAIL——它按警告记录，技能会要求你在本地 IDE 或 CI 中确认测试结果，未确认的 NOT RUN 最终导向 PASS WITH WARNINGS 而非 FAIL。

runner 输出会被解析出：总测试数、通过数、失败数、失败测试名（最多列 10 个，超过则记数量）、以及 runner 自身的崩溃或错误输出。

Phase 3：测试覆盖扫描的五个状态

sprint模式下，技能按优先级取 story 清单：QA 计划的 Test Summary 表 →production/sprints/中最近修改的 sprint 计划，然后逐个 story 判定覆盖状态：

1. 从 story 文件路径提取系统 slug（如production/epics/combat/story-001.md→combat）；
2. 在tests/unit/[system]/和tests/integration/[system]/中查找文件名包含 story slug 或相关词的测试文件；
3. 检查 story 文件本身的Test file:头字段或 "Test Evidence" 小节。

MISSING 属于建议性缺口：它不会触发 FAIL 裁决，但必须在报告中显著标出，且在/story-done完全关闭对应 story 之前必须解决。quick模式会跳过整个 Phase 3 并在输出中注明 "Coverage scan skipped — run/smoke-check sprintfor full coverage analysis."

Phase 4：用 AskUserQuestion 批量确认手工检查

冒烟项清单的来源按优先级：QA 计划的 "Smoke Test Scope" 小节 →production/qa/smoke-tests.md→tests/smoke/目录 → 内置标准回退清单。技能最多发起3 次AskUserQuestion调用，Batch 2 的占位项会替换成当前 sprint story 里的真实机制名。文档给出的选项结构如下（文档示例，方括号内容为运行时替换项）：

Batch 1 — 核心稳定性（始终执行）：

question: "Smoke check — Batch 1: Core stability. Please verify each:" options: - "Game launches to main menu without crash — PASS" - "Game launches to main menu without crash — FAIL" - "New game / session starts successfully — PASS" - "New game / session starts successfully — FAIL" - "Main menu responds to all inputs — PASS" - "Main menu responds to all inputs — FAIL"

Batch 2 — 本 sprint 机制与回归（始终执行）：选项形如 "[Primary mechanic this sprint] — PASS" / "…FAIL: [describe what broke]"，以及 "Previous sprint's features still work (no regressions) — PASS"。

Batch 3 — 数据完整性与性能（quick模式除外）：存档/读档是否丢数据、是否观察到新的掉帧或卡顿，各提供 PASS / FAIL / N/A（未检查）选项。

传入--platform时，Phase 4 追加对应平台批次（PC 的键鼠与窗口/分辨率、Console 的手柄/安全区/冷启动、Mobile 的触控/旋转切换/前后台切换），每个选项同样分 PASS 与 FAIL 两态。每条回答会原样记录进 Phase 5 报告。

Phase 5–6：报告生成、写入批准与三级裁决

Phase 5 组装完整报告，包含这些章节：Automated Tests（状态行 + 失败测试列表或 NOT RUN 说明）、Test Coverage 表（story / 类型 / 测试文件 / 状态 + 汇总计数）、Manual Smoke Checks（逐项勾选及原话记录）、Missing Test Evidence（/story-done前必须补齐的 story 清单，及预期测试文件位置如tests/unit/[system]/[story-slug]_test.[ext]），传入--platform时还有一张 Platform-Specific Results 表。

裁决规则（第一条命中的规则生效）：

Phase 6 先在会话中展示完整报告，然后询问 "May I write this smoke check report toproduction/qa/smoke-[date].md?"——未经批准绝不写文件。写入后交付对应裁决的门禁结论：

• FAIL："The smoke check failed. Do not hand off to QA until these failures are resolved." 逐条列出失败的自动测试或冒烟项，并提示修复后重新运行/smoke-check再走门禁。
• PASS WITH WARNINGS：构建可以进入手工 QA，但报告列出的 MISSING 测试证据项要在对受影响 story 运行/story-done之前解决；交接方式是分享production/qa/qa-plan-[sprint].md给 qa-tester agent 开始手工验证。
• PASS：干净通过，同样分享 QA 计划给 qa-tester agent 开始手工验证。

测试规格中的三个行为用例也印证了这条判定链：Godot 环境下 12/12 测试通过且手工项全确认时裁决为 PASS；8 通过 2 失败时报告列出失败测试名并裁决 FAIL；测试全过但有一个 Logic story 无匹配测试文件时裁决为 PASS WITH WARNINGS。

结果怎么判断，以及边界

一次运行完成后，你实际要核对的是三样东西：会话中的裁决行（只能是 PASS / PASS WITH WARNINGS / FAIL 三种之一）、经批准写入的production/qa/smoke-[date].md报告、以及报告里 Test Coverage 表的 MISSING 计数与 Manual Smoke Checks 的逐项记录。裁决告诉你能否交接：FAIL 不交接，先修后重跑；另外两种都可以把 QA 计划交给 qa-tester agent 开始手工验证，区别只在于 PASS WITH WARNINGS 把 MISSING 缺口记成了/story-done的前置义务。

几个文档明确的限制：

• 技能不会自动修复失败——只报告并说明必须解决什么，不编辑源码或测试文件；
• /smoke-check是 QA 前置工具，不调用任何 director agent，输出中不应出现 CD-*/TD-*/AD-*/PR-* 门禁 ID，也不调用/gate-check；
• NOT RUN 永不自动判 FAIL，其最终走向取决于你在 Phase 4 前的手动确认；
• FAIL 消息中的 "do not hand off to QA" 是该 skill 自己的门禁规则，项目里 QA 交接的正式链路仍按/qa-plan→/smoke-check→/regression-suite推进，通过后 story 的关闭交给/story-done。

下一步在源文档中有明确指向：修复失败项后重跑/smoke-check复检（可用quick加速）；通过后按交接说明分享production/qa/qa-plan-[sprint].md给 qa-tester agent 开始手工验证。

【免费下载链接】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