CCGS 技能测试规范全解：/story-readiness 四维就绪度检查与 READY / NEEDS WORK / BLOCKED 判定机制

CCGS 技能测试规范全解/story-readiness 四维就绪度检查与 READY / NEEDS WORK / BLOCKED 判定机制【免费下载链接】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导读/story-readiness是 Claude Code Game StudiosCCGS框架中负责开工前把关的就绪度校验技能在开发者认领任何一个 story 之前它以只读方式从 Design内嵌 GDD 需求、ArchitectureADR 引用与状态、Scope边界与依赖、Definition of Done可测标准四个维度对 story 文件做体检并输出 READY / NEEDS WORK / BLOCKED 三档结论。本文以 CCGS Skill Testing Framework 中该技能的官方行为测试规范 story-readiness.md 为主体骨架结合技能真实实现 SKILL.md、质量准则 quality-rubric.md 与 TR 注册表 tr-registry.yaml 做源码级展开。读完本文你将掌握该技能的完整检查维度、三档判定边界、五种测试场景的预期行为与断言方式以及如何使用/skill-test驱动这套规范对技能本身进行回归验证。1. 技能定位开工前的只读体检规范文档在 Skill Summary 中给出了该技能的精确职责/story-readinessvalidates that a story file is ready for a developer to pick up and implement. It checks four dimensions: Design (embedded GDD requirements), Architecture (ADR references and status), Scope (clear boundaries and DoD), and Definition of Done (testable criteria). It produces a READY / NEEDS WORK / BLOCKED verdict. It is a read-only skill and runs before any developer picks up a story.翻译过来即校验 story 文件是否已具备开发者可直接开工实现的一切要素——不要求开发者在冲刺中途回头补设计、不靠猜、不接受模糊的验收标准。它必须在 story 被分配之前运行。实际技能实现.claude/skills/story-readiness/SKILL.md的 frontmatter 佐证了这一设计意图name: story-readiness description: Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps. Use when user says is this story ready, can I start on this story, is story X ready to implement. argument-hint: [story-file-path or all or sprint] user-invocable: true allowed-tools: Read, Glob, Grep, AskUserQuestion, Task model: haiku值得注意的细节有两点只读约束allowed-tools中只有Read, Glob, Grep, AskUserQuestion, Task没有 Write 和 Edit。这是只读技能最硬的结构性证据——它只会报告问题、在对话里起草补缺内容绝不直接修改 story 文件。轻量模型该技能分配了model: haiku说明这是一个高频、确定性强的校验型技能不需要重型推理。在技能质量准则 quality-rubric.md 的readiness分类中story-readiness与/story-done被归为一组对应五条 PASS/FAIL 度量RD1–RD5度量PASS 判定标准RD1 — 多维检查技能至少检查 ≥3 个相互独立的维度如 Design、Architecture、Scope、DoD并分别报告RD2 — 三档判定层级判定层级清晰READY/COMPLETE NEEDS WORK/COMPLETE WITH NOTES BLOCKEDRD3 — BLOCKED 需外部动作BLOCKED 仅保留给 story 作者自己无法修复的问题如 ADR 处于 Proposed、依赖无法解决RD4 — 正确模式的导演门QL-STORY-READY 门在full模式下触发在lean/solo下跳过并输出跳过说明RD5 — 下一 story 交接完成后技能从当前冲刺中浮现下一条 READY 状态的 story这五条度量正是本文后面五组测试用例的验收总纲RD1 对应四维检查、RD3 对应 Case 2 的 BLOCKED 语义、RD4 对应 Case 5 的导演门模式逻辑。2. 静态断言无需夹具的结构合规检查规范文档第一节Static Assertions (Structural)列出五条纯结构断言它们由/skill-test static自动校验不需要任何测试夹具fixture具备必需 frontmatter 字段name、description、argument-hint、user-invocable、allowed-tools包含 ≥2 个阶段标题或编号检查小节包含判定关键词READY、NEEDS WORK、BLOCKED不要求 May I write 语言只读技能无需写权限协议具备下一步交接verdict 之后做什么把这五条断言放回框架语境里理解会更有价值。通用规范模板 skill-test-spec.md 中的静态断言要求是≥2 阶段标题、至少一个判定关键词、若含 Write/Edit 则需 May I write、结尾有下一步交接。story-readiness规范在其基础上反向加了第四条——显式断言不得包含 May I write 语言。这是因为该技能是只读的若实现中出现写文件请求反而是协议违规。对照真实技能实现.claude/skills/story-readiness/SKILL.md逐条验证frontmatter 五字段齐全见上文 YAML全文含Phase 0、Phase 8、## 1. Parse Arguments## 7. Next-Story Handoff共 10 个阶段标题远超 ≥2 的门槛判定关键词 READY / NEEDS WORK / BLOCKED 在## 4. Verdict Assignment有专门章节定义## 6. Collaborative Protocol明确写道 This skill is read-only. It never proposes edits or asks to write files. Do not use Write or Edit tools无任何 May I write 语言## 7. Next-Story Handoff与## Recommended Next Steps提供了完整交接路径。如何执行这组静态检查根据 README.md 的说明/skill-test static story-readiness # 检查单个技能7 项检查 /skill-test static all # 检查全部 72 个技能catalog.yaml查看中登记了本规范的权威路径- name: story-readiness spec: CCGS Skill Testing Framework/skills/readiness/story-readiness.md框架约定spec:字段是技能规范文件的权威定位方式运行测试前应先读它而不是靠猜路径。3. 四维检查从规范摘要到实现的六组清单规范说技能检查Design / Architecture / Scope / DoD四个维度。规范文档本身的测试用例已经暗示了每个维度的具体判据TR-ID、ADR 状态、Acceptance Criteria、Manifest 版本、Dependency 状态等而真正完整的判据清单在技能实现 SKILL.md 的## 3. Story Readiness Checklist中实际细分为六组检查项Design Completeness、Architecture Completeness、Scope Clarity、Open Questions、Asset References Check、Definition of Done。为了让规范的 Case 断言有落点这里把实现清单按四维重新组织作为后续测试用例的判据字典。3.1 Design Completeness设计完整性GDD 需求被引用story 必须包含design/gdd/路径并引用或引用具体某条需求/验收标准/规则而不是只贴一个 GDD 文件名。只链到文档但未追踪到具体需求 → 不通过。需求自包含验收标准在不开 GDD 的前提下即可读懂。开发者不应为了搞懂 DONE 的含义而再读一份独立文档。验收标准可测每条标准必须是具体、可观察的条件。规范原文给出的反例与正例极具指导性反例Implement the jump mechanic.实现跳跃机制正例Jump reaches max height of 5 units within 0.3 seconds when jump is held.按住跳跃时 0.3 秒内达到 5 单位最大高度无判断型验收项feels responsive手感响应好、looks good看起来不错这类无基准标准的措辞必须替换为可观察条件或 playtest 协议。3.2 Architecture Completeness架构完整性ADR 引用或显式 N/A至少引用一个 ADR或显式声明 No ADR applies 并附简短理由。两者皆无 → 失败。ADR 状态为 Accepted不得是 Proposed这是规范 Case 2 的核心判据。实现进一步细分Status: Accepted→ 通过Status: Proposed→BLOCKEDADR 可能在被接受前变更story 的实现指导可能出错修复提示BLOCKED: ADR-NNNN is Proposed — wait for acceptance before implementing.ADR 文件不存在 →BLOCKED引用的 ADR 缺失有 No ADR applies N/A 注记 → 自动通过TR-ID 有效且 active若 story 含TR-[system]-NNN引用则在 TR 注册表中查证。TR 注册表的权威文件是 docs/architecture/tr-registry.yaml其文件头注释明确写明了读写方WRITTEN BY: /architecture-review (appends new entries, never overwrites) READ BY: /create-stories (embed IDs in stories) / story-done (look up current requirement text at review time) / story-readiness (validate TR-ID exists and is active)ID 格式规则为TR-[system-slug]-[NNN]状态值为active | deprecated | superseded-by: TR-[system]-NNN。注册表中的示例条目如TR-combat-001、TR-combat-002展示了完整字段id、system、gdd、requirement、created、revised、status。判定逻辑ID 存在且status: active→ 通过ID 存在但status: deprecated或superseded-by→ NEEDS WORK需求被移除或替换修复更新为当前需求 ID 或删除ID 不存在 → NEEDS WORKstory 可能早于注册表或注册表需要跑一次/architecture-reviewstory 无 TR-ID 引用或注册表不存在 → 自动通过Manifest 版本为当前版本若 story 头含Manifest Version:日期且控制清单存在则比对版本落后 → NEEDS WORK可能有新规则生效修复后需把 story 的Manifest Version:更新为当前值。这对应规范 Case 4 的 ADVISORY 语义。引擎说明就位对 story 可能触及的 cutoff 之后的新引擎 API需包含实现说明或验证要求纯数据/配置类改动写 N/A — no engine API involved 即可。控制清单规则被标注相关的层规则需被引用或声明 N/A — manifest not yet created若docs/architecture/control-manifest.md尚不存在则自动通过不惩罚清单创建前写的 story。3.3 Scope Clarity范围清晰度估算存在含小时数、点数或 T 恤尺码之一。无估算的 story 无法排期。范围内/范围外边界明确通过显式 Out of Scope 小节或语义明确的语言说明不包括什么。缺失即暗示实现期存在 scope creep 风险。依赖被列出若依赖其他 story 先完成须列出其 story ID无依赖时须显式写 None而不是省略。3.4 Open Questions开放问题与 Definition of Done完成定义开放问题维度包括两条硬性判据无未解决设计问题story 中不得在任何验收标准、实现说明或规则语句中出现 UNRESOLVED、TBD、TODO、? 等标记。依赖 story 不得处于 DRAFT对每个依赖 story 检查文件存在且非 DRAFT 状态。依赖 DRAFT 或缺失的 story →BLOCKED而非 NEEDS WORK。DoD 维度包括至少 3 条可测验收标准少于 3 条说明 story 要么小到不该成为 story要么规格不足。性能预算如适用若触及 gameplay loop、渲染或物理须有性能预算或 no performance impact expected — [reason] 注记。Story Type 已声明头部Type:字段必须是Logic / Integration / Visual/Feel / UI / Config/Data之一否则 story 关闭时无法强制执行测试证据要求。修复提示Fix: Add Type: [Logic|Integration|Visual/Feel|UI|Config/Data] to the story header.测试证据要求明确设置 Type 后须有## Test Evidence小节说明证据存放位置Logic/Integration 类放测试文件路径Visual/Feel/UI 类放证据文档路径。此外实现中还有一条常被忽略的Asset References Check扫描 story 文本中的资源路径模式含assets/的路径或.png、.jpg、.svg、.wav、.ogg、.mp3、.glb、.gltf、.tres、.tscn、.res扩展名用 Glob 逐条验证存在性缺失 → NEEDS WORK需移除引用、创建占位资源或将之标注为对资源创建 story 的显式依赖。该检查只验存在性不校验格式与内容。4. 五组测试用例详解判定逻辑的行为验证规范的主体是五组测试用例每组由 Fixture预置项目状态、Expected behavior期望行为序列、Assertions断言清单三部分构成。它们分别压测 READY、BLOCKED、NEEDS WORK 三条判定路径与导演门模式逻辑。4.1 Case 1Happy Path —— 全就绪 story 输出 READYFixture 预置条件对应规范的完整清单story 文件存在于production/epics/core/story-light-pickup.md含TR-ID: TR-light-001GDD 需求引用含ADR: docs/architecture/adr-003-inventory.md被引用的 ADR 存在且状态为Accepted被引用的 TR-ID 存在于docs/architecture/tr-registry.yaml含## Acceptance Criteria且可测条目 ≥3含## Definition of Done小节含Status: Ready for Devstory 头部的 Manifest 版本与当前docs/architecture/control-manifest.md一致输入/story-readiness production/epics/core/story-light-pickup.md期望行为序列六步读取 story 文件读取被引用的 ADR —— 验证状态为Accepted读取docs/architecture/tr-registry.yaml—— 验证 TR-ID 存在读取docs/architecture/control-manifest.md—— 验证 Manifest 版本匹配评估全部 4 个维度Design、Architecture、Scope、DoD输出 READY 判定所有检查通过断言要点技能必须真的去读被引用的 ADR 文件而非只信 story 里的引用文字、验证 ADR 状态是Accepted而非Proposed、真实读取tr-registry.yaml验证 TR-ID、输出覆盖 4 个维度的检查结果、全部通过时判定为 READY、且不写任何文件。实现侧的行为佐证## 2. Load Supporting Context要求先一次性加载参考文档design/gdd/systems-index.md、control-manifest.md、tr-registry.yaml、所有被引用 ADR 的 Status 字段缓存、当前 sprint 文件按需缓存避免逐 story 重复读同一 ADR。这正是 Case 1 断言读取注册表与 ADR 文件的底层实现。4.2 Case 2Blocked Path —— 引用的 ADR 仍为 ProposedFixturestory 含ADR: docs/architecture/adr-005-light-system.md该 ADR 文件存在但Status: Proposed其余内容全部完整。输入/story-readiness production/epics/core/story-light-system.md期望行为读取 story读取adr-005-light-system.md—— 发现Status: Proposed将其标记为BLOCKING 问题不能对着未接受的 ADR 实现输出 BLOCKED 判定建议先接受或拒绝该 ADR再认领 story断言要点判定必须是BLOCKED绝不能是 NEEDS WORK 或 READY输出必须显式点名作为阻塞源的 Proposed ADR输出必须建议先解决 ADR 状态再继续无论其他检查是否通过都不允许输出 READY。这条用例正是质量准则 RD3 的落地验证——BLOCKED 保留给 story 作者无法独立修复的问题。Proposed ADR 的接受/拒绝属于架构决策超出 story 作者权限因此是真正的阻塞而非需要打磨。实现中## 4. Verdict Assignment的 BLOCKED 定义与其一致依赖 story 缺失/DRAFT或关键设计问题UNRESOLVED无 owner。规范同时给出一个补充说明BLOCKED 的 story 可能同时存在 NEEDS WORK 项两者都要列出。4.3 Case 3Needs Work —— 缺失 Acceptance CriteriaFixturestory 无## Acceptance Criteria小节ADR 引用存在且AcceptedTR-ID 存在于注册表Manifest 版本匹配。输入/story-readiness production/epics/core/story-oxygen-drain.md期望行为读取 story发现无 Acceptance Criteria 小节标记为 NEEDS WORKstory 不完整但不阻塞输出 NEEDS WORK 判定点名缺失的小节并建议补充可度量标准断言要点判定必须是NEEDS WORK不能是 BLOCKED 或 READY输出必须具体点名缺失的 Acceptance Criteria 小节输出必须建议添加可测/可度量标准技能必须能区分 NEEDS WORK无需外部依赖即可修复与 BLOCKED需外部动作——这是整个判定体系里最关键的语义边界对应质量准则 RD3 的直接验证。4.4 Case 4Edge Case —— 过期的 Manifest 版本Fixturestory 头部写Manifest Version: 2026-01-15docs/architecture/control-manifest.md的版本是2026-03-10两版本不匹配story 在清单更新前创建。输入/story-readiness production/epics/core/story-mirror-rotation.md期望行为读取 story 并提取 Manifest 版本2026-01-15读取控制清单头部并提取当前版本2026-03-10检测到版本不匹配标记为ADVISORY 问题不阻塞但值得提示判定为 NEEDS WORK 并附注清单过期断言要点技能读取docs/architecture/control-manifest.md获取当前版本将 story 内嵌版本与当前版本比对过期 Manifest 版本导致 NEEDS WORK不是 BLOCKED也不是 READY输出解释 story 内嵌的指导信息可能已过时。这条用例揭示了判定体系的一个精细层级Manifest 版本陈旧 ≠ 无法开工规则可能没变化因此不阻塞但它 ≠ 无风险新规则可能已生效因此不给 READY。实现中对应的判据正是 3.2 节提到的story 版本落后于当前 manifest → NEEDS WORK检查变更的 manifest 规则、按需更新 story、再同步Manifest Version:。同时实现也定义了自动通过的两类豁免story 没有Manifest Version:字段或 manifest 文件不存在。4.5 Case 5Director Gate —— QL-STORY-READY 在不同评审模式下的行为Fixturestory 处于全就绪状态4 维全部通过、ADR Accepted、验收标准齐备production/session-state/review-mode.txt存在。Case 5a —— full 模式review-mode.txt内容为full。期望行为读取评审模式 —— 判定为full完成自身的四维检查后调用QL-STORY-READY门QA lead 对 story 做就绪度评审若 QA lead 判定INADEQUATE→ 无论四维结果如何最终判定为BLOCKED若 QA lead 判定ADEQUATE→ 正常继续输出判定断言要点技能在决定是否调用 QL-STORY-READY 前先读取评审模式full 模式下在四维检查完成后调用该门QA lead 的 INADEQUATE覆盖四维 READY 结果 → 最终 BLOCKED输出中必须记录门调用Gate: QL-STORY-READY — [result]。Case 5b —— lean 或 solo 模式review-mode.txt内容为lean或solo。期望行为读取评审模式 —— 判定为lean或solo跳过QL-STORY-READY 门输出记录跳过[QL-STORY-READY] skipped — Lean/Solo mode判定仅基于四维检查断言要点lean/solo 模式下不触发QL-STORY-READY 门跳过被显式记录在输出中判定仅由四维检查决定。这条用例直接验证质量准则 RD4。值得注意的是实现SKILL.md中该技能 Phase 0 的三级解析顺序是--review [full|lean|solo]命令行参数 production/review-mode.txt文件 默认lean。也就是说默认模式是 lean只有显式声明 full 才会触发 QA lead 门。而 full 模式下 spawnqa-lead其行为规范见 agents/leads/qa-lead.md时需传入四段上下文story 标题、完整验收标准列表、依赖状态exist / DRAFT / missing、四维判定的总体结论门结果按三档处理——ADEQUATE 放行、GAPS 弹出AskUserQuestion三选项Update story with suggested gaps/Accept and proceed anyway/Discuss further、INADEQUATE 则向用户呈现具体缺口后再决定。5. 协议合规只读技能的验收红线规范的 Protocol Compliance 一节是运行测试时的最终验收清单对应 templates/skill-test-spec.md 中协议合规段的特化不使用 Write 或 Edit 工具只读技能在给出判定前先呈现完整的检查结果不请求批准无文件写入故无 May I write 环节以推荐下一步收尾修复问题或进入实现清晰区分三档判定READY vs NEEDS WORK vs BLOCKED前两条与实现中## 5. Output Format的输出模板一一对应单 story 输出需包含## Story Readiness: [story title]、File: [path]、Verdict: [...]、### Passing Checks (N/[total])、### Gaps每条含Fix:具体补缺文本、以及 BLOCKED 时的### Blockers小节——先列通过项、再列缺口、最后才给判定确保结论可追溯。多 story 聚合输出all/sprint范围使用汇总格式## Story Readiness Summary — [scope] — [date] Ready: [N] stories Needs Work: [N] stories Blocked: [N] stories并在尾部附每条非 READY story 的单文件详细报告。若范围为sprint且存在 NEEDS WORK / BLOCKED 的 Must Have story输出顶部会出现显著的冲刺预警WARNING: [N] Must Have stories are not implementation-ready. [List them with their primary gap or blocker.] Resolve these before the sprint begins or replan with /sprint-plan update.第三条不请求批准的实现对应## 6. Collaborative Protocol技能报告完发现后只提供一句协作式提议——Would you like help filling in the gaps for any of these stories? I can draft the missing sections for your approval.即使用户同意也只在对话中起草缺失小节写入动作交给用户或/create-stories。协议还定义了三条重定向规则story 文件完全不存在 → 指引先跑/create-epics [layer]再跑/create-stories [epic-slug]无 GDD 引用且改动很小约 4 小时→ 指引跑/quick-design [description]生成 Quick Design Spec 并回填引用story 范围已膨胀超过原估算 → 建议拆分或升级给 producer 处理6. 覆盖率说明与已知边界规范的 Coverage Notes 诚实地划定了测试未覆盖的边界这些是写规范、改技能时最值得关注的扩展点TR-ID 完全缺失于注册表未单列用例但明确说明它遵循与 Case 3 相同的NEEDS WORK模式对应实现中ID 不存在于注册表 → NEEDS WORK的分支。无参数路径技能自动探测当前 story未测试因为依赖production/session-state/active.md的内容难以稳定构造夹具。规范原文The no argument path (skill auto-detecting the current story) is not tested because it depends on production/session-state/active.md content, which is hard to fixture reliably.注意实现SKILL.md的无参行为是弹AskUserQuestion让用户选范围单个 story / 当前冲刺全部 / epics 全部 / 指定 epic与/story-done无参时直接读active.md自动探测不同。多 ADR 引用未测试假设行为是累加式的——只有所有被引用 ADR 均为 Accepted 才给 READY。这三条边界同时呼应了 CLAUDE.md 中的框架规范Specs describe current behavior, not ideal behavior. When a skill misbehaves in practice, correct the skill first, then update the spec to match the fixed behavior.规范描述的是当前行为而非理想行为技能实践出错时先修技能再同步规范。7. 如何在框架中驱动这套测试整套规范的执行由框架内置的两个技能驱动用法详见 README.md/skill-test static story-readiness # 7 项静态结构检查 /skill-test spec story-readiness # 对照本规范逐用例评估5 组用例 协议合规 /skill-test category story-readiness # 对照 readiness 分类度量 RD1–RD5 评估 /skill-test audit # 查看全部技能/代理的 has-spec、last tested、result /skill-improve story-readiness # 测试 → 诊断 → 提出修复 → 重测的闭环工作流来自 CLAUDE.md先读catalog.yaml拿到spec:路径与category:再读catalog.yaml指向的规范文件按用例逐条评估断言最后将结果写入results/并更新catalog.yaml的last_spec/last_spec_result追踪字段。测试产物目录results/被 gitignore不会污染仓库。结语/story-readiness是 CCGS 流水线中开工前最后一道闸门它以只读方式把story 是否真的能开工分解为设计、架构、范围、完成定义四个维度的可判定问题用 READY / NEEDS WORK / BLOCKED 三档结论把可以开工需要打磨与存在外部阻塞精确区分开再通过 QL-STORY-READY 导演门在 full 模式下引入 QA lead 的人工复核。本文以官方行为规范 story-readiness.md 为骨架逐条展开了静态断言、五组行为测试用例与协议合规清单并用技能实现 SKILL.md 的六组检查清单与 TR 注册表 tr-registry.yaml 补齐了判据细节——这套规范 实现 注册表三位一体的证据链既可用于对技能本身的回归验证也可作为设计同类开工门槛校验技能时的直接参考模板。【免费下载链接】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），仅供参考