CCGS /create-control-manifest 深入解析：将 Accepted ADR 固化为架构控制清单，让 Story 创作继承全部架构约束

CCGS /create-control-manifest 深入解析：将 Accepted ADR 固化为架构控制清单，让 Story 创作继承全部架构约束

【免费下载链接】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）仓库中CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md这一技能测试规格文档，结合仓库内catalog.yaml、quality-rubric.md、上游/architecture-decision与下游/create-stories、/create-epics等技能规格以及docs/architecture/、docs/registry/下的实际注册表文件，系统讲解控制清单（Control Manifest）技能的输入输出契约、五种核心行为场景、无门禁设计原理、静态断言与测试验证方法。读完本文，你将掌握该技能在 CCGS 架构治理流水线中的位置、其生成docs/architecture/control-manifest.md的完整行为规格，以及如何用/skill-test对这类 pipeline 技能做逐场景验证。

一、为什么需要控制清单：ADR 碎片化与架构约束传递难题

在 CCGS 的架构治理体系中，架构决策记录（ADR，Architecture Decision Record）是架构事实的源头。由/architecture-decision技能引导用户逐节撰写，ADR 被写入docs/architecture/adr-NNN-[name].md，其必需章节包括Status、Context、Decision、Consequences、Alternatives、Related ADRs六大部分。

随着项目推进，docs/architecture/下的 ADR 会越来越多，每个 ADR 都承载着不同类型的架构信息：

• Required Patterns——必须遵循的实现模式；
• Forbidden Patterns——被明确禁止的反模式；
• 关键约束（constraints）——状态所有权、接口契约、性能预算等硬性规定。

问题是：当 Story 作者要写一个用户故事时，他不可能逐份通读全部 ADR 才能动笔。/create-control-manifest技能正是为了解决这一信息传递瓶颈而设计：

它读取docs/architecture/下所有Accepted（已接受）的 ADR，将其中全部的架构约束、必需模式与禁止模式汇总到一份单点参考文档docs/architecture/control-manifest.md中。Story 作者（以及/create-stories技能）只需查阅这一份清单，即可继承正确的架构规则，无需逐个翻阅 ADR 原文。

这正是该技能规格文档开篇 "Skill Summary" 所定义的核心宗旨：把分散的 ADR 收敛为一份"控制清单"（control manifest），成为 story 创作时的架构规则参考文档。

二、技能定位：pipeline 类技能与上下游链路

在技能测试框架的注册表catalog.yaml中，create-control-manifest被登记为：

• priority: high——流水线关键技能；
• category: pipeline——产出工件、且工件被其他技能消费的流水线类技能。

而quality-rubric.md的pipeline类别将这类技能界定为："Pipeline skills produce artifacts that other skills consume"，并要求它们满足 P1–P5 五项指标（详见后文第八节）。

上游：谁产生 ADR

/architecture-decision技能负责 ADR 的撰写。关键行为包括：

• 逐节引导撰写六大必需章节，并在每节写入前询问"May I write"；
• 从docs/engine-reference/将引擎版本参考戳进 ADR，保证可追溯性；
• 在full审查模式下，草稿完成后并行拉起TD-ADR（技术总监）与LP-FEASIBILITY（主程）两个门禁 Agent，两者均 APPROVED 时 ADR 状态置为Accepted；任一返回 CONCERNS/FAIL 则保持Proposed；
• 在lean/solo模式下两个门禁被跳过，ADR 一律以Status: Proposed写入；
• 输出文件路径为docs/architecture/adr-NNN-[name].md。

这意味着：ADR 的状态（Accepted / Proposed）是上游技能通过门禁机制严谨产出的，/create-control-manifest完全可以信任该字段作为过滤依据，无需重复审查。

下游：谁消费控制清单

控制清单最主要的消费者是/create-stories。该技能将一个 EPIC 拆解为开发者就绪的 story 文件时，会同时读取 EPIC.md、对应 GDD、治理 ADR、控制清单（control manifest）以及 TR 注册表，并把控制清单中的规则逐条引用进每个 story（"Control manifest rules quoted per-story from the manifest, not invented"——规则必须引自清单原文，不得自行发挥）。

同样在/create-epics中，每个 EPIC.md 需要包含 "governing ADRs"（治理该系统的 ADR 列表），控制清单为此提供了快速索引。

并行的注册表体系

控制清单之外，docs/下还有两份与之互补的机器可读注册表：

• docs/architecture/tr-registry.yaml：技术需求 ID 注册表，为每个 GDD 技术需求分配永久稳定的TR-[system-slug]-[NNN]ID，由/architecture-review写入、/create-stories、/story-done、/story-readiness读取；
• docs/registry/architecture.yaml：架构立场注册表，登记状态所有权（state_ownership）、接口契约（interfaces）、性能预算（performance_budgets）、API 决策（api_decisions）与禁止模式（forbidden_patterns）五类跨系统立场，用于在撰写新 ADR 前检测冲突。

控制清单与这两份 YAML 注册表的分工在于：YAML 注册表面向机器校验与搜索（Grep），控制清单面向 story 作者的快速阅读——它把注册表中的规则语义以文档形态统一呈现。

三、输入与输出契约

该技能规格文档明确了严格的输入输出边界：

规格文档明确强调："The skill only includes Accepted ADRs; Proposed ADRs are excluded and noted"——被排除的 Proposed ADR 绝不能静默省略，必须让用户看到排除清单，这是防止架构约束悄悄流失的关键设计。

四、核心行为流程：提取 → 起草 → 确认 → 写入

综合规格文档的 Skill Summary 与 Case 1 的 Expected behavior，正常路径下的行为流程如下：

1. 读取：读取docs/architecture/下全部 ADR 文件；
2. 过滤：按Status: Accepted过滤出有效 ADR；
3. 提取：从每个 Accepted ADR 中提取Required Patterns（必需模式）、Forbidden Patterns（禁止模式）以及关键约束；
4. 起草：按正确的章节结构起草清单（要求包含 Required Patterns 与 Forbidden Patterns 的独立分区，且每条约束都标注来源 ADR 编号，便于回溯）；
5. 展示：将清单草稿完整展示给用户；
6. 确认：询问"May I write \docs/architecture/control-manifest.md`?"`；
7. 写入：获批准后写入文件，输出 verdictCREATED；
8. 移交：以下一步交接指令收尾——/create-epics或/create-stories（让流水线自然延续）。

其中"每条约束必须携带来源 ADR 编号"是 Case 1 断言之一："Manifest includes the source ADR number for each constraint"。这一设计保证了清单与 ADR 原文之间的双向可追溯：读者在清单中看到某条约束，即可顺着编号回到原始 ADR 查阅完整上下文。

写入阶段还严格遵守协作协议："Skill does NOT write without approval"——没有用户批准，技能绝不落盘。

五、五种场景行为：测试用例驱动的完整行为规格

该技能规格文档以5 个测试用例定义了技能在正常、异常、边界、门禁各维度下的完整行为。下表先给出全景，随后逐例展开。

Case 1：Happy Path——4 个 Accepted ADR 生成正确清单

前置状态（Fixture）：docs/architecture/含 4 份 ADR 文件，全部Status: Accepted；每份都有 "Required Patterns" 和/或 "Forbidden Patterns" 章节；docs/architecture/control-manifest.md尚不存在。

断言要点：

• 4 个 Accepted ADR全部呈现在清单中；
• 清单包含Required Patterns 与 Forbidden Patterns 两个独立分区；
• 每条约束携带源 ADR 编号；
• 写入前必问 "May I write"；未获批准绝不写入；
• 写入完成后 verdict 为CREATED。

Case 2：Failure Path——目录中无任何 ADR

前置状态：docs/architecture/目录存在但无任何 ADR 文件。

预期行为：技能输出精确的错误提示并干净退出：

"No ADRs found. Run/architecture-decisionto create ADRs before generating the control manifest."

随后不创建任何文件，verdict 为BLOCKED——注意规格特别强调 BLOCKED 是"受控终止"而非崩溃（"not an error crash"），并且必须给出下一步动作指引（推荐/architecture-decision）。

Case 3：混合状态——只有 Accepted ADR 被纳入

前置状态：docs/architecture/含 3 个 Accepted ADR 与 2 个 Proposed ADR。

预期行为：

1. 读取全部 ADR 并按Status: Accepted过滤；
2. 仅基于 3 个 Accepted ADR 起草清单；
3. 输出中显式注明排除项，例如：

"2 Proposed ADRs were excluded: [adr-NNN-name, adr-NNN-name]"

4. 用户在批准写入前能看到被排除的 ADR 清单；
5. 然后照常询问 "May I write"。

这条行为的核心断言是："Skill does NOT silently omit Proposed ADRs without noting them"——禁止静默省略。因为一旦静默排除，团队可能误以为某些约束不存在，后续 story 就会在不知情的前提下违背尚未定案的架构方向。

Case 4：Edge Case——控制清单已存在

前置状态：docs/architecture/control-manifest.md已存在（版本 v1，上周生成）；docs/architecture/中又有新增的 Accepted ADR。

预期行为：

1. 技能检测到已有清单，读取并报告其版本号/日期；
2. 提供重新生成选项（而非直接覆盖）：

"control-manifest.md already exists (v1, [date]). Regenerate with current ADRs?"

3. 用户确认后：基于当前 ADR 起草更新版清单，版本号递增（v1 → v2）；
4. 覆盖写入前依然询问 "May I writedocs/architecture/control-manifest.md?"（overwrite）；
5. 获批准后写入更新版。

此用例验证了两个保护机制：绝不自动覆盖（User is offered a regenerate/skip choice）与版本可追踪（incremented version number）。

Case 5：Director Gate——无门禁被拉起，不读取 review-mode.txt

前置状态：4 个 Accepted ADR 存在；production/session-state/review-mode.txt存在且内容为full。

预期行为：

1. 技能读取 ADR 并起草清单；
2. 不读取production/session-state/review-mode.txt；
3. 全程不派发任何门禁 Agent；
4. 起草完成后直接进入 "May I write" 征询；
5. review 模式设置对该技能行为零影响。

断言要点：

• 无任何带 CD-、TD-、PR-、AD- 前缀的门禁出现；
• 输出中不含 "Gate: [GATE-ID]" 或 gate-skipped 条目；
• 清单仅由 ADR 机械生成，无外部门禁审查介入。

六、设计原理：为什么控制清单不需要导演门禁

该技能在 Director Gate Checks 一节给出的理由非常明确：

"No director gates — this skill spawns no director gate agents. The control manifest is a mechanical extraction from Accepted ADRs; no creative or technical review gate is needed."

即：控制清单生成是纯粹的机械提取。ADR 的"好坏"在上游/architecture-decision阶段已经由 TD-ADR 与 LP-FEASIBILITY 两个门禁把关过了；/create-control-manifest只是把已定案的 Accepted 结果汇总成文档，既不涉及创意判断，也不涉及技术可行性评估，因此任何导演级审查都是多余开销。

这也解释了为什么该技能连review-mode.txt都不读取（Case 5 专门验证了这一点）——门禁模式（full/lean/solo）只对"是否派发门禁 Agent"有意义，而该技能根本不存在门禁这一环节，读取 review-mode 纯属浪费。

从质量准则视角看，这与quality-rubric.md中 pipeline 类指标的P4（Director gate at correct tier）完全一致：门禁应运行在与其风险级别匹配的技能上，而不是机械类技能上。

七、静态断言与协议合规：技能的可自动验证骨架

规格文档定义了一组无需夹具即可自动验证的结构性断言（由/skill-test static执行）。这些断言共同构成了该技能的最低合规骨架：

• Frontmatter 必备字段：name、description、argument-hint、user-invocable、allowed-tools；
• 阶段标题：至少 2 个阶段（phase）标题；
• 结论词汇：包含CREATED与BLOCKED；
• 协作协议：包含面向control-manifest.md的 "May I write" 协作协议语言；
• 下一步交接：结尾包含交接指令（/create-epics或/create-stories）；
• 过滤规则文档化：明确记录"仅包含 Accepted ADR，不含 Proposed"。

这与测试规格模板templates/skill-test-spec.md中定义的 5 项静态检查保持一致（frontmatter 五字段、2+ 阶段标题、verdict 关键词、May I write 语言、结尾交接节），说明该技能完全遵循框架的规格编写规范。

协议合规清单（Protocol Compliance）则进一步收紧了运行时行为：

• 起草清单前读取全部 ADR 文件；
• 仅包含 Accepted ADR，Proposed 显式标注排除；
• 在 "May I write" 征询前，先将清单草稿完整展示给用户；
• 写入docs/architecture/control-manifest.md前询问 "May I write"；
• 无导演门禁，不读取review-mode.txt；
• 以/create-epics或/create-stories交接收尾。

八、如何验证与测试该技能

根据CCGS Skill Testing Framework/CLAUDE.md中定义的技能测试工作流，验证该技能的标准步骤是：

1. 读取catalog.yaml获取该技能的spec:路径与category:（create-control-manifest的 spec 即本文对应的规格文件，category 为pipeline）；
2. 读取技能本体（.claude/skills/[name]/SKILL.md）；
3. 读取规格文件（spec:路径）；
4. 逐用例评估断言（即第五节中的 5 个 Case）；
5. 提供将结果写入results/并更新catalog.yaml中last_spec_result等跟踪字段的选项。

在此基础上，/skill-test category [name|all]会进一步对照quality-rubric.md中pipeline类别的 P1–P5 指标做 PASS/FAIL/WARN 判定：

九、边界与已知限制（Coverage Notes）

规格文档在 Coverage Notes 中如实声明了三处测试覆盖边界，理解它们有助于正确解读测试结果：

1. 清单的确切章节结构不做断言锁定：约束表格、模式列表等章节细节由技能本体定义，测试断言只验证 Required/Forbidden 分区与源 ADR 编号的存在，不逐格验证版式；
2. 版本号递增逻辑经 Case 4 测试，但格式不锁定：v1 → v2 的递增行为被验证，但具体版本号书写格式（如是否带日期）不由夹具固定；
3. ADR 解析依赖一致的 ADR 结构：从 ADR 中提取 Required/Forbidden Patterns 的前提是 ADR 具备稳定章节结构（由上游/architecture-decision保证），这一依赖通过 Case 1 的夹具隐式验证。

此外，CLAUDE.md中有一句重要提醒：规格文件描述的是技能的"当前行为"而非"理想行为"（"Specs in this folder describe current behavior, not ideal behavior"），它们可能编码了 bug。因此当技能实际行为与规格不符时，应优先修正技能本体，再让规格与修正后的行为对齐，而不是把规格失败直接等同于"技能有罪"。

十、仓库内相关证据阅读指引

如果你希望深入验证本文所述内容，可以直接查阅以下仓库文件：

• 本文主体规格：CCGS Skill Testing Framework/skills/pipeline/create-control-manifest.md；
• 技能注册信息（priority/category/spec 路径）：catalog.yaml；
• pipeline 类质量指标 P1–P5：quality-rubric.md；
• 上游 ADR 撰写技能（状态来源与门禁机制）：architecture-decision.md；
• 下游消费者技能（读取清单、引用规则）：create-stories.md、create-epics.md；
• 机器可读注册表（TR-ID 与架构立场）：tr-registry.yaml、architecture.yaml；
• 技能测试工作流与规格编写模板：CLAUDE.md、skill-test-spec.md。

需要说明的是，仓库当前状态中docs/architecture/仅含tr-registry.yaml，control-manifest.md属于该技能运行时的产物——当你在一个已积累多份 Accepted ADR 的项目中调用/create-control-manifest时，该文件才会被生成。这也正是阅读本规格文档的意义所在：你可以在技能运行之前，就完整预期它的五种行为路径与产出形态。

小结：/create-control-manifest是 CCGS 架构治理流水线中承上启下的一环——它把上游/architecture-decision通过门禁机制定案的 Accepted ADR，机械且无遗漏地汇总为一份 story 作者可直接引用的控制清单，同时以 "May I write" 协作协议、源 ADR 编号标注、Proposed 显式排除、版本递增等机制保证清单的准确性、可追溯性与可维护性。理解它的行为规格，就等于理解了 CCGS 如何让"架构约束"从散落的决策文档，变为每个故事创作时都无法绕过的单点事实源。

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