create-control-manifest

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation

以上配置已解析，请直接使用；本次运行中，--review 会覆盖 review_mode。没有阻止项 → 使用 .claude/docs/config-resolution.md 中的默认值。

使用提问工具进行询问。如果没有提问工具，请将选项编号列出，并结束本轮以等待回复。跳过或关闭的问题不算回答：请改用纯文本再次提问。

创建控制清单

控制清单是一份面向程序员的扁平规则表，按架构层列出要做什么、绝不能做什么，内容取自已接受的 ADR、项目的技术偏好和引擎参考文档。ADR 说明为什么；清单说明做什么。

写入： 用户同意后写入 docs/architecture/control-manifest.md。 时机： /architecture-review 通过且 ADR 已接受后。每当有 ADR 被接受或修订时，都要重新运行。

提问遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式在重大选择时提问，自主模式记录后继续；automation_always_ask 类别始终提问）。

阶段 1：加载输入

ADR

bash .claude/scripts/adr-status.sh 一次读取所有 docs/architecture/adr-*.md：首先输出计数（依次为 adrs、accepted、proposed、deprecated、superseded、unfilled、other、no_status），然后为每个 ADR 输出一行，列出其状态和层。先确定分母：阅读任何 ADR 之前，根据计数作出判断：

计数	含义	操作
adrs 0	没有 ADR。	“未找到 ADR——请先运行 /architecture-decision，再创建控制清单。”停止。
accepted ≥ 1	正常。	已接受的条目组成集合 A。在阶段 4 的预览中列出所有其他 ADR 及其状态：用户应在了解清单未涵盖的内容后再批准清单。
accepted 0，但有些 ADR 有状态	没有已接受的 ADR。	“找到 [N] 个 ADR，但没有已接受的 ADR。根据提议中的 ADR 构建清单，会将仍可能改变的决策固化下来。”询问是继续使用提议中的 ADR，还是停止。绝不能默默写入空清单。
所有 ADR 均为 no_status	ADR 格式错误，并非已接受 ADR 集合为空。	“找到 [N] 个 ADR，但都没有 ## Status 部分，因此无法判断是否已接受。请对每个文件运行 /architecture-decision retrofit [file]。”停止。绝不能将它们视为已接受。

以上每种停止情况都要以 Verdict: BLOCKED — [原因] 结尾。记录每条规则所依据的 ADR 编号和标题。

项目配置

• 从 project.yaml 获取 naming.* 和 performance.*；任何缺失或为空的键，均从 .claude/docs/technical-preferences.md 获取。
• 从 .claude/docs/technical-preferences.md 获取已批准的库和禁止使用的模式（未迁移到 project.yaml）。

引擎参考

• 引擎及其版本对应的 docs/engine-reference/[engine]/VERSION.md。
• docs/engine-reference/[engine]/deprecated-apis.md：其中的 API 将列为禁止使用的 API。
• 若存在，则读取 docs/engine-reference/[engine]/current-best-practices.md。

现有内容

如果存在 docs/architecture/control-manifest.md：本次运行会重新生成该文件；在阶段 5 写入前先读取，因为写入时会替换该文件。如果存在 production/epics/*/EPIC.md：表示已有史诗。阶段 6 会根据两者选择下一步。

报告：“已加载 [A] 个已接受的 ADR（共 [N] 个），引擎：[名称 + 版本]。”

阶段 2：从每份 ADR 中提取规则

对于 A 中的每份 ADR，只阅读四个部分，绝不通读整个文件：

bash .claude/scripts/md-section.sh extract docs/architecture/[adr-file].md "Decision"

以及 Alternatives Considered、Performance Implications 和 Engine Compatibility。Context、Consequences、Migration Plan 和 Validation Criteria 说明了为何做出某项决策；清单记录了要执行的事项。如果某份 ADR 缺少某个部分，请为该 ADR 记录下来，然后继续。如果 A 中的所有 ADR 都缺少某个部分，请报告：“没有已接受的 ADR 包含 [section] 部分——清单中的 [category] 规则将为空。请确认这是有意为之。”只有当某个部分指向其自身之外的内容（“受 Context 中约束条件的限制”）时，才阅读这四个部分之外的内容；此时只阅读那个部分。

从每份 ADR 中提取：

• 必需模式（Decision）：所有“必须”“应该”“需要”“始终”之类的要求，以及其中规定的所有模式或方法，包括其中的任何 ### Implementation Guidelines。绝不要只查找这个子标题：许多 ADR 会直接在 Decision 下列出要求，只搜索该子标题会导致该部分为空。
• 禁止采用的方法（Alternatives Considered）：所有被否决的替代方案，以及将其否决原因作为规则说明（“绝不要使用 X，因为 Y”），还有任何明确指出的反模式。
• 性能约束（Performance Implications）：性能预算（“此系统每帧最多 N 毫秒”）和内存限制。
• 引擎 API 约束（Engine Compatibility）：截止版本之后需要验证的 API、与模型假设不符的行为，以及在固定版本中已更改的字段或方法。

分层。 每条规则都归入其所约束系统所属的层；如果 ADR 有 layer 列，则以该列为准：

• **基础层：**场景管理、事件架构、存档/读档、引擎启动
• **核心层：**核心游戏循环、主要玩家系统、物理与碰撞
• **功能层：**次要系统与机制、AI
• **表现层：**渲染、音频、UI、VFX、着色器

跨多个层的 ADR，应将其规则分别归入每一层。

阶段 3：添加全局规则

每一层的规则都要注明其来源（project.yaml 中的键、technical-preferences.md 或引擎参考文件），与层级规则的来源标注方式相同：

• 命名：来自 naming.*，包括类、变量、信号与事件、文件、常量。
• 性能预算：来自 performance.*，包括目标帧率、帧预算、绘制调用次数、内存上限。
• 禁止使用的 API：来自 deprecated-apis.md，仅限适用于本项目所构建内容的 API。绝不要照搬整个表格：其中的 GodotPhysics3D → Jolt Physics 3D 条目仅适用于 3D，2D 项目不会使用该引擎。如果无法判断某条目是否适用（2D 还是 3D、项目可能不包含的模块），请限定规则范围（“使用 3D 物理时：……”），或将其省略并列为待解决项。/create-stories 会读取此文件，不适用的规则没人会读。
• 必需模式：如果存在，则来自 current-best-practices.md。
• 禁止模式：来自 technical-preferences.md，按原文复制。

阶段 4：先展示摘要，再进行审查

## Control Manifest Preview
Engine: [name + version]
ADRs covered: [ADR numbers]
ADRs left out: [ADR-NNNN ([status]), … — every ADR not in A, or "None"]
Rules extracted:
  - Foundation layer: [N] required, [M] forbidden, [P] guardrails
  - Core layer: [N] required, [M] forbidden, [P] guardrails
  - Feature layer: …
  - Presentation layer: …
  - Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries
Unresolved: [engine entries left out because whether they apply is unclear, or "None"]

询问：“这份规则摘要看起来完整吗？”选项：是 — 审查并撰写 / 添加规则 — 我还有内容要补充 / 移除规则 — 有些规则应该删掉 / 停止 — 我需要先审查 ADR。

技术审查。 阅读上方的 review_gate 行。skill-gates=skip （个人或精简模式）：不使用 Agent；注明 TD-MANIFEST skipped — [Solo | Lean] mode。 skill-gates=run：将审查交给 technical-director Agent，并指定门禁 TD-MANIFEST（.claude/docs/director-gates/td-manifest.md；Agent 会自行读取）。 简述：

• **目标：**在写入规则前检查提取出的规则。
• **提供给它：**上方包含完整规则列表的预览、涵盖的 ADR、引擎版本，以及取自技术偏好或引擎参考文档的规则。
• **检查：**是否已收录并准确表述每项强制性 ADR 模式；禁止采用的方法是否完整且归属正确；每条规则是否都有来源 ADR 或偏好文档；防护措施是否符合 ADR 的约束。
• **返回：**APPROVE、CONCERNS、REJECT 或 NOT ASSESSED，并指出缺少的输入。
• **边界：**不写入任何文件。

根据审查结果采取行动：

• **APPROVE：**进入阶段 5。
• **CONCERNS：**询问：“技术总监提出了疑虑。你想如何继续？”选项：修改标记的规则 / 接受并继续 / 进一步讨论。
• **REJECT：**不写入任何内容；修正标记的规则，并再次展示摘要。
• **NOT ASSESSED：**这不代表批准（.claude/docs/director-gates.md）。指出缺少的内容，然后补充并重新进行审查；或者，如果用户选择在缺少该内容的情况下继续，则进入阶段 5，并在回复和最终结论行中注明 TD-MANIFEST: NOT ASSESSED — [input]。

阶段 5：编写控制清单

询问：“我可以将控制清单写入 docs/architecture/control-manifest.md 吗？” 选项：可以，写入 / 先给我看完整草稿，然后再询问 / 暂不 — 我还想做更多修改。只有得到明确肯定后才能写入。

# Control Manifest

> **Engine**: [name + version]
> **Last Updated**: [date]
> **Manifest Version**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
> **Status**: Active — regenerate with `/create-control-manifest update` when ADRs change

`Manifest Version` is the date this manifest was generated. Stories embed it when
they are written, and `/story-readiness` compares a story's version with this one
to find stories written against old rules. It always equals `Last Updated`: the
same date, for different readers.

This manifest is a programmer's quick reference taken from the Accepted ADRs, the
technical preferences and the engine reference docs. For the reason behind a rule,
read its ADR.

---

## Foundation Layer Rules

*Applies to: scene management, event architecture, save/load, engine start-up*

### Required Patterns
- **[rule]** — source: [ADR-NNNN]

### Forbidden Approaches
- **Never [anti-pattern]** — [brief reason] — source: [ADR-NNNN]

### Performance Guardrails
- **[system]**: max [N]ms/frame — source: [ADR-NNNN]

---

## Core Layer Rules

*Applies to: core gameplay loop, main player systems, physics, collision*

### Required Patterns
...

### Forbidden Approaches
...

### Performance Guardrails
...

---

## Feature Layer Rules

*Applies to: secondary mechanics, AI systems, secondary features*

### Required Patterns
...

### Forbidden Approaches
...

---

## Presentation Layer Rules

*Applies to: rendering, audio, UI, VFX, shaders, animations*

### Required Patterns
...

### Forbidden Approaches
...

---

## Global Rules (All Layers)

### Naming Conventions
| Element | Convention | Example | Source |
|---------|-----------|---------|--------|
| Classes | [convention] | [example] | [`naming.classes` in project.yaml, or technical-preferences.md] |
| Variables | [convention] | [example] | [`naming.variables` in project.yaml, or technical-preferences.md] |
| Signals/Events | [convention] | [example] | [`naming.signals` in project.yaml, or technical-preferences.md] |
| Files | [convention] | [example] | [`naming.files` in project.yaml, or technical-preferences.md] |
| Constants | [convention] | [example] | [`naming.constants` in project.yaml, or technical-preferences.md] |

### Performance Budgets
| Target | Value | Source |
|--------|-------|--------|
| Framerate | [value] | [`performance.target_framerate` in project.yaml, or technical-preferences.md] |
| Frame budget | [value] | [`performance.frame_budget_ms` in project.yaml, or technical-preferences.md] |
| Draw calls | [value] | [`performance.draw_call_limit` in project.yaml, or technical-preferences.md] |
| Memory ceiling | [value] | [`performance.memory_ceiling_mb` in project.yaml, or technical-preferences.md] |

### Approved Libraries / Addons
- [library] — approved for [purpose] — source: technical-preferences.md

### Forbidden APIs ([engine version])
These APIs are deprecated or unverified for [engine + version]:
- `[api name]` — deprecated since [version] / unverified post-cutoff
- Source: `docs/engine-reference/[engine]/deprecated-apis.md`

### Cross-Cutting Constraints
- [constraint that applies in every layer] — source: [ADR-NNNN, preference key or engine-reference file]

阶段 6：后续步骤

• 尚无史诗： “运行 /create-epics layer: foundation，然后运行 /create-stories [epic-slug]：故事会嵌入此清单中的规则和版本。”
• 重新生成：“已更新。请告知团队规则已更改，尤其是新增的 Forbidden 条目。”

每条规则都可追溯到 ADR、技术偏好或引擎参考文档；没有任何规则是凭空编造的，也没有任何规则被改述到改变原意。写入后以 Verdict: COMPLETE — control manifest written 结束；用户拒绝写入时以 Verdict: BLOCKED — user declined the write 结束。