Claude Code Game Studios（CCGS）技能行为测试规范编写指南：用 Skill Test Spec 为 72 个工作流技能建立可验收的质检标准

Claude Code Game Studios（CCGS）技能行为测试规范编写指南：用 Skill Test Spec 为 72 个工作流技能建立可验收的质检标准

【免费下载链接】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（CCGS）中，49 个 Agent 与 72 个工作流技能构成了完整的游戏研发流水线，而质量保障的关键在于：每一个技能都必须能被自动验证。.claude/docs/templates/skill-test-spec.md（仓库内还有一份功能等价的副本 CCGS Skill Testing Framework/templates/skill-test-spec.md）正是这套验证体系的"契约文件"模板——它为每个技能定义行为测试规范（Behavioral Spec），供/skill-test spec按规范逐条断言评估。读完本文，你将掌握该模板的完整结构、每个字段的编写要求、与/skill-test四种运行模式的联动方式，以及如何用真实示例（如 gate-check 规范）为任意技能写出可被机器逐条验收的测试规格。

一、为什么需要 Skill Test Spec：从"看起来合规"到"行为正确"

CCGS 的技能文件（SKILL.md）本身是 Markdown 指令，可以被静态检查（frontmatter 是否齐全、是否有 ≥2 个阶段标题、是否包含判定词），但静态合规不等于行为正确。一个技能可能结构完整，却在"缺少必需文件时依然输出 PASS"、"未征求用户同意就写文件"等关键行为上出错。

Skill Test Spec 的定位正是弥补这一缺口：它是描述技能在给定项目状态下应当如何表现的行为契约，由 .claude/skills/skill-test/SKILL.md 中的spec模式逐条读取并评估。该规范文件明确写道：

"This is a Claude-evaluated reasoning check, not code execution."

也就是说，/skill-test spec不是运行被测试的技能代码，而是通读技能指令与被测规范，以推理方式判断"技能在被测夹具（fixture）状态下按指令执行，是否满足每一条断言"。断言结果分为PASS（明确满足）、PARTIAL（部分满足但存在歧义）、FAIL（给定夹具下不满足）。

这套设计让规范同时服务两个读者：人（编写时理清技能的预期行为边界）和LLM 评估器（/skill-test spec执行时逐条裁决）。这也是该模板全文采用"Fixture → Input → Expected behavior → Assertions"四段式的原因——四者合起来构成一个可推理的最小行为场景。

二、模板总览：一份 Skill Test Spec 的五段式骨架

模板 .claude/docs/templates/skill-test-spec.md 的结构如下：

配套的 CCGS Skill Testing Framework/templates/agent-test-spec.md 是 Agent 版本，结构类似（多了 Tier/Category 头、Domain/Escalates to/Delegates to、Out-of-Domain Redirect 与 Conflict Escalation 等用例），本文聚焦技能版本。

三、逐节编写指南

3.1 Skill Summary：一段话交代五个要素

模板要求在一段话内说明：这个技能做什么、何时使用、产出什么，并"包含主要产出工件、它使用的判定格式、以及它所属的流水线阶段"。

参考真实范例 CCGS Skill Testing Framework/skills/gate/gate-check.md 的写法：

/gate-checkvalidates whether the project is ready to advance to the next development phase. It checks for required artifacts, runs quality checks, asks the user about unverifiable items, and produces a PASS/CONCERNS/FAIL verdict. On PASS with user confirmation, it writes the new stage name toproduction/stage.txt. It governs all 6 phase transitions and is the most critical gate-keeping skill in the pipeline.

注意这段摘要已经点出了：判定格式（PASS/CONCERNS/FAIL）、写入工件（production/stage.txt）、所属定位（6 个阶段转换的 gate 技能）。规范的摘要写清楚了，/skill-test spec的评估器才能据此校验后续用例的合理性。

3.2 Static Assertions：与/skill-test static的 7 项检查对齐

模板的 Static Assertions 章节标注了"由/skill-test static自动验证，无需夹具"。它对应的正是 .claude/skills/skill-test/SKILL.md 的 Phase 2A 中定义的 7 项检查：

1. Check 1 — Required Frontmatter Fields：frontmatter 必须含name、description、argument-hint、user-invocable、allowed-tools五个字段，缺一即 FAIL；
2. Check 2 — Multiple Phases：≥2 个阶段标题（## Phase N、## N.或 ≥2 个##标题），不足 2 个即 FAIL；
3. Check 3 — Verdict Keywords：必须至少包含PASS、FAIL、CONCERNS、APPROVED、BLOCKED、COMPLETE、READY、COMPLIANT、NON-COMPLIANT之一，一个都没有即 FAIL；
4. Check 4 — Collaborative Protocol Language：要求"先问再写"的语言（规范形式为"May I write"，或"before writing"/"approval"邻近写文件指令、或"ask"与"write"同段共现）。缺失时 WARN；若allowed-tools含Write/Edit却无此类语言则直接 FAIL；
5. Check 5 — Next-Step Handoff：结尾须有下一步建议（如提到/story-done、/gate-check、"Recommended next"/"Follow-Up" 字样），缺失时 WARN；
6. Check 6 — Fork Context Complexity：若 frontmatter 含context: fork，则需 ≥5 个阶段标题（fork 上下文专供复杂多阶段技能使用），不足则 WARN；
7. Check 7 — Argument Hint Plausibility：argument-hint不能为空，且应与正文的多模式描述（如 "Mode A | Mode B"）及第一阶段"Parse Arguments"部分互相印证，不匹配则 WARN。

因此，模板中"Static Assertions"的勾选项应直接映射到上述 7 项检查——特别是判定词清单，应如实列出该技能真正会输出的词（模板示例给出的PASS, FAIL, CONCERNS与 gate-check 一致）。

3.3 Test Cases：三种场景的编写规范

模板定义了三个用例模板，每个用例统一包含Fixture（假设的项目状态：哪些文件存在、内容如何）、Input（/[skill-name] [args]）、Expected behavior（分阶段的预期动作）、Assertions（可勾选的断言清单）四部分：

Case 1: Happy Path（正常路径）—— 描述"一切就绪时技能应如何表现"。以 gate-check 规范的真实写法为例：

• Fixture：design/gdd/game-concept.md存在且包含全部必需章节；design/gdd/game-pillars.md存在；尚无 systems index（该阶段正确状态）。
• Input：/gate-check systems-design
• Expected behavior：1) 读取game-concept.md并验证有内容；2) 检查 game pillars；3) 检查质量项（核心循环已描述、目标受众已明确）；4) 输出结构化清单并逐项标记；5) 给出 PASS/CONCERNS/FAIL 判定；6) 若 PASS 则询问 "May I updateproduction/stage.txtto 'Systems Design'?"
• Assertions：技能必须先 Glob/Read 验证文件存在再标记为已检查；输出含 "Required Artifacts" 与 "Quality Checks" 分区；输出含 "Verdict" 行；对无法自动验证的质量项应提问而非假定 PASS；更新production/stage.txt前必须说 "May I write"；未经用户确认不得写入。

编写要点：Happy Path 的断言应当验证技能确实读取了文件、输出了正确的分区与判定词、并在写文件前征求同意——也就是把"技能是否走完了它自己承诺的流程"全部显式化。

Case 2: Failure Path（失败路径）—— 描述"关键工件缺失时技能必须暴露缺口而非假装正常"。gate-check 规范的对应场景是game-concept.md不存在、design/gdd/为空：

• Expected behavior：读取失败 → 将必需工件标记为缺失 → 输出 FAIL → 列出 blocker "No game concept document found" → 建议补救动作（运行/brainstorm创建）。
• Assertions：缺失必需工件时判定必须是 FAIL（而非 PASS 或 CONCERNS）；输出必须点名缺失的具体文件；输出含至少 1 项 "Blockers"；给出补救建议；FAIL 时不得写入production/stage.txt。

编写要点：模板特别强调两条——"Skill does NOT output PASS when the fixture is incomplete"（夹具不完整时绝不能输出 PASS）和"Skill does not create files to fill in the gap without asking"（不得未经询问就自行创建文件补缺）。这对应 CCGS 的协作原则：技能是顾问而非越权执行者。

Case 3: Edge Case（边界情况）—— 模板给出的示例是"无参数调用/[skill-name]"。gate-check 规范将其扩展为"无参数时自动探测当前阶段"：读取production/stage.txt推断当前阶段 → 确定下一个 gate → 直接执行对应检查，且输出头必须同时标明当前与目标阶段（如 "Gate Check: Concept → Systems Design"）。该规范的 Note 还修正了一个常见误解：技能在自动探测到转换后仍会用 AskUserQuestion 向用户确认，这是"确认步骤"而非"让用户选 gate"，断言不应将其视为失败——这个修正说明，Edge Case 断言应区分"询问确认"与"推卸决策"两种不同行为。

3.4 Protocol Compliance：CCGS 协作协议的验收清单

模板的协议合规段是固定五条，任何技能规范都应当保留：

• 所有文件写入前使用"May I write"；
• 先呈现发现/报告，再请求写文件批准；
• 结尾给出推荐的下一步或后续技能；
• 未经用户明确批准绝不自动创建文件；
• 不跳过阶段、不未经检查直接跳到判定。

在/skill-test spec的执行流程中（见 .claude/skills/skill-test/SKILL.md Phase 2B Step 3），这些协议断言是"总是存在"（always present）的固定检查项，无论被测技能属于哪个类别。

3.5 Coverage Notes：主动声明"不测什么"

模板用一个列表要求作者记录刻意不覆盖的场景及原因，示例包括：

• "Case 3（all 模式）未覆盖，因为它在单个 spec 中运行检查过多——应逐个测试每个子模式"；
• "数据库集成路径未覆盖，因为它需要真实环境"；
• "损坏的 YAML 文件的边界情况推迟到未来的 spec"。

gate-check 规范的真实 Coverage Notes 提供了教科书式写法——它将 Production→Polish、Polish→Release 两个 gate 显式排除（需要 sprint plans、playtest data、QA sign-off 等多工件环境），将 CONCERNS 判定路径声明为介于 Case 1 与 Case 2 之间、遵循相同模式的过渡态，并将 Vertical Slice 验证排除（需要可玩构建，无法用文档夹具表达）。写 Coverage Notes 的价值在于：让后来的维护者知道"没测"是深思熟虑的决定，而不是疏漏，避免误补破坏规范的边界。

四、与/skill-test四种模式的协作关系

编写规范的目的不是摆设，而是被 .claude/skills/skill-test/SKILL.md 消费。该技能提供四种模式，CCGS Skill Testing Framework/README.md 给出了对应命令：

在spec模式执行时，规范文件的定位流程为：技能位于.claude/skills/[name]/SKILL.md，规范路径从 CCGS Skill Testing Framework/catalog.yaml 的spec:字段解析；技能缺失、catalog 无 spec 路径、或规范文件不存在时，分别输出明确的错误信息（"Skill '[name]' not found..."、"No spec path set..."、"Spec file missing at [path]. Run/skill-test auditto see coverage gaps."）。

spec模式结束后会询问："May I write these results toCCGS Skill Testing Framework/results/skill-test-spec-[name]-[date].mdand updateCCGS Skill Testing Framework/catalog.yaml?"——获批后写入结果文件并更新该技能的last_spec与last_spec_result字段。这也是 CCGS Skill Testing Framework/README.md "Updating the catalog" 一节描述的机制。

五、实战：从模板到一份完整规范的四步工作流

根据 CCGS Skill Testing Framework/README.md 的 "Writing a new spec" 一节，为技能编写行为规范的标准流程是：

1. 找到模板：CCGS Skill Testing Framework/templates/skill-test-spec.md（或 .claude/docs/templates/skill-test-spec.md）；
2. 复制到skills/[category]/[skill-name].md（按技能类别放入 gate/review/authoring/readiness/pipeline/analysis/team/sprint/utility 对应目录，目录内已存在 72 个真实规范文件可作参照）；
3. 在catalog.yaml中更新该技能的spec:字段指向新文件；
4. 运行/skill-test spec [skill-name]验证规范本身是否自洽。

值得一提的是，该框架是自包含且可选的：README 声明游戏开发者可以rm -rf "CCGS Skill Testing Framework"完全移除它，.claude/中没有任何内容依赖它；移除后/skill-test与/skill-improve仍可运行，只是会报告 catalog.yaml 缺失并建议先运行/skill-test audit初始化。

六、规范质量的进阶杠杆：category 评分与 skill-improve 闭环

规范写得再好，若技能实现与规范脱节，也会在category模式暴露。以gate类别为例，CCGS Skill Testing Framework/quality-rubric.md 定义 5 项 PASS/FAIL 指标：G1 读取production/session-state/review-mode.txt决定 spawn 哪些 director；G2 full 模式下并行 spawn 全部 4 位 Tier-1 director（CD/TD/PR/AD 的 PHASE-GATE）；G3 lean 模式只跑*-PHASE-GATE；G4 solo 模式不 spawn 任何 director 且逐条标注 "skipped — Solo mode"；G5 未经用户确认绝不写入production/stage.txt。

gate-check 规范的 Case 5（Director Gate）正是对这些指标的用例化表达——5a 验证 full 模式并行 spawn 全部 4 个 PHASE-GATE 且任一 director 的 CONCERNS 会传导到总体判定（"Verdict is NOT auto-PASS if any director returns CONCERNS or REJECT"），5b 验证 solo 模式输出[CD-PHASE-GATE] skipped — Solo mode且判定仅基于工件与质量检查。由此可见，规范 Test Case、/skill-test spec的行为验证、/skill-test category的类别评分三者构成层层递进的质量防线。

若技能在测试中失败，/skill-improve [name]提供"测试 → 诊断 → 提议修复 → 重测"的闭环（CCGS Skill Testing Framework/README.md），并可手动或自动更新 catalog 中的last_static/last_static_result。

七、编写规范时的十条实践准则

综合模板要求、/skill-test实现与真实规范范例，编写 Skill Test Spec 时应遵循：

1. Fixture 要具体到文件路径：写清"哪些文件存在、内容到什么程度"，避免"有文档"这种模糊描述；
2. Expected behavior 按阶段编号：1) 读什么 → 2) 评估什么 → 3) 输出什么，与技能自身的 Phase 结构对应；
3. 断言可被推理裁决：每条断言都应能根据"技能指令 + 夹具状态"明确判定 PASS/PARTIAL/FAIL，避免"表现良好"这类不可判定表述；
4. 失败路径必须断言"不输出 PASS"：这是模板反复强调的核心防线；
5. 写文件前必须断言 "May I write"：任何含写入的技能都不可绕过协作协议；
6. 不可自动验证的质量项必须断言为提问（如[?] MANUAL CHECK NEEDED），而非默认 PASS；
7. 判定词清单与技能实际输出对齐，否则/skill-test static的 Check 3 会失效；
8. 用 Coverage Notes 显式声明不测范围及原因；
9. 多模式技能为每个模式单独立用例（参考 gate-check 的 5a/5b 拆分）；
10. 写完立即用/skill-test spec [name]自检，并让规范与 catalog.yaml 的spec:、last_*字段保持同步。

遵循这套规范，CCGS 的 72 个技能才能在结构合规之外获得真正可验证的行为质量——这正是"Turn Claude Code into a full game dev studio"这一目标在质量保障维度上的落地基础。

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