design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is invoked:

调用此技能时：

1. Parse Arguments & Validate

1. 解析参数并验证

Resolve the review mode (once, store for all gate spawns this run):

If
```
--review [full|lean|solo]
```
was passed → use that
Else read
```
production/review-mode.txt
```
→ use that value
Else → default to
```
lean
```

See

.claude/docs/director-gates.md

for the full check pattern.

A system name or retrofit path is required. If missing:

Check if
```
design/gdd/systems-index.md
```
exists.
If it exists: read it, find the highest-priority system with status "Not Started" or equivalent, and use
```
AskUserQuestion
```
:
- Prompt: "The next system in your design order is [system-name] ([priority] | [layer]). Start designing it?"
- Options:
```
[A] Yes — design [system-name]
```
  /
```
[B] Pick a different system
```
  /
```
[C] Stop here
```
- If [A]: proceed with that system name. If [B]: ask which system to design (plain text). If [C]: exit.
If no systems index exists, fail with:
"Usage:
```
/design-system <system-name>
```
— e.g.,
```
/design-system movement
```
Or to fill gaps in an existing GDD:
```
/design-system retrofit design/gdd/[system-name].md
```
No systems index found. Run
```
/map-systems
```
first to map your systems and get the design order."

Detect retrofit mode: If the argument starts with

retrofit

or the argument is a file path to an existing

.md

file in

design/gdd/

, enter retrofit mode:

Read the existing GDD file.
Identify which of the 8 required sections are present (scan for section headings). Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
Identify which sections contain only placeholder text (
```
[To be designed]
```
or equivalent — blank, a single line, or obviously incomplete).

Present to the user before doing anything:

## Retrofit: [System Name]
File: design/gdd/[filename].md

Sections already written (will not be touched):
✓ [section name]
✓ [section name]

Missing or incomplete sections (will be authored):
✗ [section name] — missing
✗ [section name] — placeholder only

Ask: "Shall I fill the [N] missing sections? I will not modify any existing content."
If yes: proceed to Phase 2 (Gather Context) as normal, but in Phase 3 skip creating the skeleton (file already exists) and in Phase 4 skip sections that are already complete. Only run the section cycle for missing/ incomplete sections.
Never overwrite existing section content. Use Edit tool to replace only
```
[To be designed]
```
placeholders or empty section bodies.

If NOT in retrofit mode, normalize the system name to kebab-case for the filename (e.g., "combat system" becomes

combat-system

确定审查模式（本次运行中所有关卡生成均使用该模式）：

如果传入了
```
--review [full|lean|solo]
```
→ 使用该值
否则读取
```
production/review-mode.txt
```
→ 使用该文件中的值
否则 → 默认使用
```
lean
```

完整的检查规则请参见

.claude/docs/director-gates.md

。

系统名称或改造路径为必填项。如果缺失：

检查
```
design/gdd/systems-index.md
```
是否存在。
如果存在：读取该文件，找到状态为“未开始”或同等状态的最高优先级系统，并调用
```
AskUserQuestion
```
：
- 提示：“您的设计顺序中的下一个系统是 [system-name]（优先级：[priority] | 层级：[layer]）。是否开始设计它？”
- 选项：
```
[A] 是 — 设计 [system-name]
```
  /
```
[B] 选择其他系统
```
  /
```
[C] 到此为止
```
- 如果选[A]：使用该系统名称继续。如果选[B]：询问要设计的系统名称（纯文本）。如果选[C]：退出。
如果系统索引不存在，返回错误：
“用法：
```
/design-system <system-name>
```
— 示例：
```
/design-system movement
```
或为现有GDD补全内容：
```
/design-system retrofit design/gdd/[system-name].md
```
未找到系统索引，请先运行
```
/map-systems
```
来映射您的系统并获取设计顺序。”

检测改造模式： 如果参数以

retrofit

开头，或者参数是

design/gdd/

目录下现有

.md

文件的路径，则进入改造模式：

读取现有GDD文件。
识别8个必填章节中哪些已存在（扫描章节标题）。必填章节：概述、玩家体验设想、详细设计/规则、公式、边缘情况、依赖关系、调节参数、验收标准。
识别哪些章节仅包含占位符文本（
```
[To be designed]
```
或类似内容——空白、单行文本或明显未完成）。

在进行任何操作前向用户展示：

## 改造：[系统名称]
文件：design/gdd/[filename].md

已完成的章节（不会被修改）：
✓ [章节名称]
✓ [章节名称]

缺失或未完成的章节（将进行创作）：
✗ [章节名称] — 缺失
✗ [章节名称] — 仅含占位符

询问：“是否需要我补全这[N]个缺失的章节？我不会修改任何现有内容。”
如果是：正常进入阶段2（收集上下文），但在阶段3跳过创建文件框架（文件已存在），在阶段4跳过已完成的章节。仅对缺失/未完成的章节执行章节循环流程。
绝不要覆盖现有章节内容。仅使用编辑工具替换
```
[To be designed]
```
占位符或空白章节内容。

如果未处于改造模式，将系统名称标准化为短横线分隔式（kebab-case）作为文件名（例如，“combat system”变为

combat-system

）。

2. Gather Context (Read Phase)

2. 收集上下文（读取阶段）

Read all relevant context before asking the user anything. This is the skill's primary advantage over ad-hoc design — it arrives informed.

在向用户提问前，先读取所有相关上下文。这是该技能相较于临时设计的主要优势——它会带着充足信息开始工作。

2a: Required Reads

2a：必填读取项

Game concept: Read
```
design/gdd/game-concept.md
```
— fail if missing:
"No game concept found. Run
```
/brainstorm
```
first."
Systems index: Read
```
design/gdd/systems-index.md
```
— fail if missing:
"No systems index found. Run
```
/map-systems
```
first to map your systems."
Target system: Find the system in the index. If not listed, warn:

"[system-name] is not in the systems index. Would you like to add it, or design it as an off-index system?"
Entity registry: Read
```
design/registry/entities.yaml
```
if it exists. Extract all entries referenced by or relevant to this system (grep
```
referenced_by.*[system-name]
```
and
```
source.*[system-name]
```
). Hold these in context as known facts — values that other GDDs have already established and this GDD must not contradict.
Reflexion log: Read
```
docs/consistency-failures.md
```
if it exists. Extract entries whose Domain matches this system's category. These are recurring conflict patterns — present them under "Past failure patterns" in the Phase 2d context summary so the user knows where mistakes have occurred before in this domain.

游戏概念：读取
```
design/gdd/game-concept.md
```
—— 如果缺失则返回错误：
“未找到游戏概念，请先运行
```
/brainstorm
```
。”
系统索引：读取
```
design/gdd/systems-index.md
```
—— 如果缺失则返回错误：
“未找到系统索引，请先运行
```
/map-systems
```
来映射您的系统。”
目标系统：在索引中查找该系统。如果未列出，发出警告：

“[system-name] 未在系统索引中。您是否想要将其添加到索引中，还是作为索引外系统进行设计？”
实体注册表：如果
```
design/registry/entities.yaml
```
存在则读取它。提取所有与该系统相关或被该系统引用的条目（使用grep查找
```
referenced_by.*[system-name]
```
和
```
source.*[system-name]
```
）。将这些作为已知事实保存在上下文中——这些是其他GDD已确定的值，本GDD不得与之矛盾。
反思日志：如果
```
docs/consistency-failures.md
```
存在则读取它。提取领域与该系统类别匹配的条目。这些是反复出现的冲突模式——在阶段2d的上下文摘要中展示“过往失败模式”部分，让用户了解该领域之前出现过哪些错误。

2b: Dependency Reads

2b：依赖项读取

From the systems index, identify:

Upstream dependencies: Systems this one depends on. Read their GDDs if they exist (these contain decisions this system must respect).
Downstream dependents: Systems that depend on this one. Read their GDDs if they exist (these contain expectations this system must satisfy).

For each dependency GDD that exists, extract and hold in context:

Key interfaces (what data flows between the systems)
Formulas that reference this system's outputs
Edge cases that assume this system's behavior
Tuning knobs that feed into this system

从系统索引中识别：

上游依赖：当前系统所依赖的系统。如果它们的GDD存在则读取（这些包含当前系统必须遵循的决策）。
下游依赖：依赖当前系统的系统。如果它们的GDD存在则读取（这些包含当前系统必须满足的期望）。

对于每个存在的依赖GDD，提取并保存在上下文中：

关键接口（系统间的数据流向）
引用当前系统输出的公式
假设当前系统行为的边缘情况
输入到当前系统的调节参数

2c: Optional Reads

2c：可选读取项

Game pillars: Read
```
design/gdd/game-pillars.md
```
if it exists
Existing GDD: Read
```
design/gdd/[system-name].md
```
if it exists (resume, don't restart from scratch)
Related GDDs: Glob
```
design/gdd/*.md
```
and read any that are thematically related (e.g., if designing a system that overlaps with another in scope, read the related GDD even if it's not a formal dependency)

游戏支柱：如果
```
design/gdd/game-pillars.md
```
存在则读取
现有GDD：如果
```
design/gdd/[system-name].md
```
存在则读取（继续创作，而非从头开始）
相关GDD：使用Glob匹配
```
design/gdd/*.md
```
并读取任何主题相关的文件（例如，设计与其他系统范围重叠的系统时，即使不是正式依赖，也读取相关GDD）

2d: Present Context Summary

2d：展示上下文摘要

Before starting design work, present a brief summary to the user:

Designing: [System Name]

Priority: [from index] | Layer: [from index]

Depends on: [list, noting which have GDDs vs. undesigned]

Depended on by: [list, noting which have GDDs vs. undesigned]

Existing decisions to respect: [key constraints from dependency GDDs]

Pillar alignment: [which pillar(s) this system primarily serves]

Known cross-system facts (from registry):

[entity_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])

[item_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD])

[formula_name]: variables=[list], output=[min–max] (owned by [source GDD])

[constant_name]: [value] [unit] (owned by [source GDD]) (These values are locked — if this GDD needs different values, surface the conflict before writing. Do not silently use different numbers.)

If no registry entries are relevant: omit the "Known cross-system facts" section.

If any upstream dependencies are undesigned, warn:

"[dependency] doesn't have a GDD yet. We'll need to make assumptions about its interface. Consider designing it first, or we can define the expected contract and flag it as provisional."

在开始设计工作前，向用户展示简要摘要：

正在设计：[系统名称]

优先级：[来自索引] | 层级：[来自索引]

依赖于：[列表，标注哪些已有GDD vs. 未设计]

被依赖于：[列表，标注哪些已有GDD vs. 未设计]

需要遵循的现有决策：[来自依赖GDD的关键约束]

支柱对齐：[该系统主要服务的支柱]

已知跨系统事实（来自注册表）：

[entity_name]：[attribute]=[value], [attribute]=[value]（由[来源GDD]定义）

[item_name]：[attribute]=[value], [attribute]=[value]（由[来源GDD]定义）

[formula_name]：变量=[列表], 输出=[min–max]（由[来源GDD]定义）

[constant_name]：[value] [unit]（由[来源GDD]定义） （这些值已锁定——如果本GDD需要不同值，请在写入前提出冲突。不要擅自使用不同数值。）

如果没有相关注册表条目：省略“已知跨系统事实”部分。

如果任何上游依赖未设计，发出警告：

“[dependency] 尚未有GDD。我们需要对其接口做出假设。考虑先设计它，或者我们可以定义预期的契约并标记为临时版本。”

2e: Technical Feasibility Pre-Check

2e：技术可行性预检查

Before asking the user to begin designing, load engine context and surface any constraints or knowledge gaps that will shape the design.

Step 1 — Determine the engine domain for this system: Map the system's category (from systems-index.md) to an engine domain:

System Category	Engine Domain
Combat, physics, collision	Physics
Rendering, visual effects, shaders	Rendering
UI, HUD, menus	UI
Audio, sound, music	Audio
AI, pathfinding, behavior trees	Navigation / Scripting
Animation, IK, rigs	Animation
Networking, multiplayer, sync	Networking
Input, controls, keybinding	Input
Save/load, persistence, data	Core
Dialogue, quests, narrative	Scripting

Step 2 — Read engine context (if available):

Read
```
.claude/docs/technical-preferences.md
```
to identify the engine and version

If engine is configured, read

docs/engine-reference/[engine]/VERSION.md

Read

docs/engine-reference/[engine]/modules/[domain].md

if it exists

Read

docs/engine-reference/[engine]/breaking-changes.md

for domain-relevant entries

Glob
```
docs/architecture/adr-*.md
```
and read any ADRs whose domain matches (check the Engine Compatibility table's "Domain" field)

Step 3 — Present the Feasibility Brief:

If engine reference docs exist, present before starting design:

undefined

在要求用户开始设计前，加载引擎上下文并指出将影响设计的约束或知识缺口。

步骤1 — 确定该系统的引擎领域： 将系统类别（来自systems-index.md）映射到引擎领域：

系统类别	引擎领域
战斗、物理、碰撞	物理
渲染、视觉效果、着色器	渲染
UI、HUD、菜单	UI
音频、音效、音乐	音频
AI、寻路、行为树	导航/脚本
动画、反向运动学(IK)、骨骼绑定	动画
网络、多人游戏、同步	网络
输入、控制、按键绑定	输入
保存/加载、持久化、数据	核心
对话、任务、叙事	脚本

步骤2 — 读取引擎上下文（如果可用）：

读取
```
.claude/docs/technical-preferences.md
```
以确定引擎和版本

如果已配置引擎，读取

docs/engine-reference/[engine]/VERSION.md

如果存在，读取

docs/engine-reference/[engine]/modules/[domain].md

读取

docs/engine-reference/[engine]/breaking-changes.md

中与领域相关的条目

使用Glob匹配
```
docs/architecture/adr-*.md
```
并读取任何领域匹配的ADR（检查引擎兼容性表中的“领域”字段）

步骤3 — 展示可行性简报：

如果引擎参考文档存在，在开始设计前展示：

undefined

Technical Feasibility Brief: [System Name]

技术可行性简报：[系统名称]

Engine: [name + version] Domain: [domain]

引擎：[名称 + 版本] 领域：[领域]

Known Engine Capabilities (verified for [version])

已知引擎能力（已针对[版本]验证）

[capability relevant to this system]
[capability 2]

[与该系统相关的能力]
[能力2]

Engine Constraints That Will Shape This Design

将影响本设计的引擎约束

[constraint from engine-reference or existing ADR]

[来自引擎参考文档或现有ADR的约束]

Knowledge Gaps (verify before committing to these)

知识缺口（在确定前需验证）

[post-cutoff feature this design might rely on — mark HIGH/MEDIUM risk]

[本设计可能依赖的 cutoff 后功能 — 标记高/中风险]

Existing ADRs That Constrain This System

约束本系统的现有ADR

ADR-XXXX: [decision summary] — means [implication for this GDD] (or "None yet")


If no engine reference docs exist (engine not yet configured), show a short note:
> "No engine configured yet — skipping technical feasibility check. Run
> `/setup-engine` before moving to architecture if you haven't already."

**Step 4 — Ask before proceeding:**

Use `AskUserQuestion`:
- "Any constraints to add before we begin, or shall we proceed with these noted?"
  - Options: "Proceed with these noted", "Add a constraint first", "I need to check the engine docs — pause here"

---

Use `AskUserQuestion`:
- "Ready to start designing [system-name]?"
  - Options: "Yes, let's go", "Show me more context first", "Design a dependency first"

---

ADR-XXXX：[决策摘要] — 意味着[对本GDD的影响] （或“暂无”）


如果引擎参考文档不存在（尚未配置引擎），显示简短提示：
> “尚未配置引擎 — 跳过技术可行性检查。如果尚未运行，请在进入架构阶段前运行 `/setup-engine`。”

**步骤4 — 继续前询问：**

调用 `AskUserQuestion`：
- “在开始前是否需要添加任何约束，还是基于已记录的内容继续？”
  - 选项：“基于已记录的内容继续”、“先添加约束”、“我需要查看引擎文档 — 在此暂停”

---

调用 `AskUserQuestion`：
- “准备好开始设计[system-name]了吗？”
  - 选项：“是的，开始吧”、“先展示更多上下文”、“先设计依赖项”

---

3. Create File Skeleton

3. 创建文件框架

Once the user confirms, immediately create the GDD file with empty section headers. This ensures incremental writes have a target.

Use the template structure from

.claude/docs/templates/game-design-document.md

markdown

undefined

一旦用户确认，立即创建带有空白章节标题的GDD文件。这确保了逐步写入有明确的目标。

使用

.claude/docs/templates/game-design-document.md

中的模板结构：

markdown

undefined

[System Name]

[系统名称]

Status: In Design Author: [user + agents] Last Updated: [today's date] Implements Pillar: [from context]

状态：设计中作者：[用户 + agents] 最后更新：[今日日期] 实现支柱：[来自上下文]

Overview

概述

[To be designed]

Player Fantasy

玩家体验设想

[To be designed]

Detailed Design

详细设计

Core Rules

核心规则

[To be designed]

States and Transitions

状态与转换

[To be designed]

Interactions with Other Systems

与其他系统的交互

[To be designed]

Formulas

公式

[To be designed]

Edge Cases

边缘情况

[To be designed]

Dependencies

依赖关系

[To be designed]

Tuning Knobs

调节参数

[To be designed]

Visual/Audio Requirements

视觉/音频要求

[To be designed]

UI Requirements

UI要求

[To be designed]

Acceptance Criteria

验收标准

[To be designed]

Open Questions

未解决问题

[To be designed]


Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?"

After writing, update `production/session-state/active.md`:
- Use Glob to check if the file exists.
- If it **does not exist**: use the **Write** tool to create it. Never attempt Edit on a file that may not exist.
- If it **already exists**: use the **Edit** tool to update the relevant fields.

File content:
- Task: Designing [system-name] GDD
- Current section: Starting (skeleton created)
- File: design/gdd/[system-name].md

---

[To be designed]


询问：“是否可以在 `design/gdd/[system-name].md` 创建框架文件？”

写入后，更新 `production/session-state/active.md`：
- 使用Glob检查文件是否存在。
- 如果**不存在**：使用**写入**工具创建它。绝不要对可能不存在的文件尝试编辑。
- 如果**已存在**：使用**编辑**工具更新相关字段。

文件内容：
- 任务：设计[system-name] GDD
- 当前章节：开始（框架已创建）
- 文件：design/gdd/[system-name].md

---

4. Section-by-Section Design

4. 分章节设计

Walk through each section in order. For each section, follow this cycle:

按顺序完成每个章节。对于每个章节，遵循以下循环：

The Section Cycle

章节循环流程

Context  ->  Questions  ->  Options  ->  Decision  ->  Draft  ->  Approval  ->  Write

Context: State what this section needs to contain, and surface any relevant decisions from dependency GDDs that constrain it.
Questions: Ask clarifying questions specific to this section. Use
```
AskUserQuestion
```
for constrained questions, conversational text for open-ended exploration.
Options: Where the section involves design choices (not just documentation), present 2-4 approaches with pros/cons. Explain reasoning in conversation text, then use
```
AskUserQuestion
```
to capture the decision.
Decision: User picks an approach or provides custom direction.
Draft: Write the section content in conversation text for review. Flag any provisional assumptions about undesigned dependencies.
Approval: Immediately after the draft — in the SAME response — use
```
AskUserQuestion
```
. NEVER use plain text. NEVER skip this step.
- Prompt: "Approve the [Section Name] section?"
- Options:
```
[A] Approve — write it to file
```
  /
```
[B] Make changes — describe what to fix
```
  /
```
[C] Start over
```
The draft and the approval widget MUST appear together in one response. If the draft appears without the widget, the user is left at a blank prompt with no path forward — this is a protocol violation.
Write: Use the Edit tool to replace the placeholder with the approved content. CRITICAL: Always include the section heading in the
```
old_string
```
to ensure uniqueness — never match
```
[To be designed]
```
alone, as multiple sections use the same placeholder and the Edit tool requires a unique match. Use this pattern:
```
old_string: "## [Section Name]\n\n[To be designed]"
new_string: "## [Section Name]\n\n[approved content]"
```
Confirm the write.
Registry conflict check (Sections C and D only — Detailed Design and Formulas): After writing, scan the section content for entity names, item names, formula names, and numeric constants that appear in the registry. For each match:
- Compare the value just written against the registry entry.
- If they differ: surface the conflict immediately before starting the next section. Do not continue silently.
  
  "Registry conflict: [name] is registered in [source GDD] as [registry_value]. This section just wrote [new_value]. Which is correct?"
- If new (not in registry): flag it as a candidate for registry registration (will be handled in Phase 5).

After writing each section, update

production/session-state/active.md

with the completed section name. Use Glob to check if the file exists — use Write to create it if absent, Edit to update it if present.

上下文  ->  问题  ->  选项  ->  决策  ->  草稿  ->  审批  ->  写入

上下文：说明本章节需要包含的内容，并指出来自依赖GDD的相关约束决策。
问题：提出针对本章节的澄清问题。对于受限问题使用
```
AskUserQuestion
```
，开放式探索使用对话文本。
选项：当章节涉及设计选择（而非仅文档记录）时，提供2-4种带有优缺点的方案。在对话文本中解释理由，然后使用
```
AskUserQuestion
```
获取决策。
决策：用户选择方案或提供自定义方向。
草稿：在对话文本中编写章节内容供审核。标记对未设计依赖项的临时假设。
审批：草稿完成后——在同一回复中——使用
```
AskUserQuestion
```
。绝不要使用纯文本。绝不要跳过此步骤。
- 提示：“是否批准[章节名称]章节？”
- 选项：
```
[A] 批准 — 写入文件
```
  /
```
[B] 修改 — 描述需要修正的内容
```
  /
```
[C] 重新开始
```
草稿和审批组件必须在一个回复中同时出现。如果只出现草稿而没有组件，用户将面临空白提示且无法继续——这违反了协议。
写入：使用编辑工具将占位符替换为已批准的内容。关键：始终在
```
old_string
```
中包含章节标题以确保唯一性——绝不要仅匹配
```
[To be designed]
```
，因为多个章节使用相同的占位符，编辑工具需要唯一匹配。使用以下模式：
```
old_string: "## [章节名称]\n\n[To be designed]"
new_string: "## [章节名称]\n\n[已批准内容]"
```
确认写入完成。
注册表冲突检查（仅针对章节C和D——详细设计和公式）：写入后，扫描章节内容以查找出现在注册表中的实体名称、物品名称、公式名称和数值常量。对于每个匹配项：
- 将刚写入的值与注册表条目进行比较。
- 如果不同：立即提出冲突，然后再开始下一章节。不要静默继续。
  
  “注册表冲突：[name] 在[来源GDD]中注册为[registry_value]。本章节刚写入[new_value]。哪个是正确的？”
- 如果是新条目（不在注册表中）：标记为注册表候选条目（将在阶段5处理）。

每个章节写入后，更新

production/session-state/active.md

中的已完成章节名称。使用Glob检查文件是否存在——如果不存在则使用写入创建，如果已存在则使用编辑更新。

Section-Specific Guidance

各章节特定指南

Each section has unique design considerations and may benefit from specialist agents:

每个章节都有独特的设计考量，可能需要专家agents的支持：

Section A: Overview

章节A：概述

Goal: One paragraph a stranger could read and understand.

Derive recommended options before building the widget: Read the system's category and layer from the systems index (already in context from Phase 2), then determine the recommended option for each tab:

Framing tab: Foundation/Infrastructure layer →
```
[A]
```
recommended. Player-facing categories (Combat, UI, Dialogue, Character, Animation, Visual Effects, Audio) →
```
[C] Both
```
recommended.
ADR ref tab: Glob
```
docs/architecture/adr-*.md
```
and grep for the system name in the GDD Requirements section of any ADR. If a matching ADR is found →
```
[A] Yes — cite the ADR
```
recommended. If none found →
```
[B] No
```
recommended.
Fantasy tab: Foundation/Infrastructure layer →
```
[B] No
```
recommended. All other categories →
```
[A] Yes
```
recommended.

Append

(Recommended)

to the appropriate option text in each tab.

Framing questions (ask BEFORE drafting): Use

AskUserQuestion

with a multi-tab widget:

Tab "Framing" — "How should the overview frame this system?" Options:

[A] As a data/infrastructure layer (technical framing)

[B] Through its player-facing effect (design framing)

[C] Both — describe the data layer and its player impact

Tab "ADR ref" — "Should the overview reference the existing ADR for this system?" Options:

[A] Yes — cite the ADR for implementation details

[B] No — keep the GDD at pure design level

Tab "Fantasy" — "Does this system have a player fantasy worth stating?" Options:

[A] Yes — players feel it directly

[B] No — pure infrastructure, players feel what it enables

Use the user's answers to shape the draft. Do NOT answer these questions yourself and auto-draft.

Questions to ask:

What is this system in one sentence?
How does a player interact with it? (active/passive/automatic)
Why does this system exist — what would the game lose without it?

Cross-reference: Check that the description aligns with how the systems index describes it. Flag discrepancies.

Design vs. implementation boundary: Overview questions must stay at the behavior level — what the system does, not how it is built. If implementation questions arise during the Overview (e.g., "Should this use an Autoload singleton or a signal bus?"), note them as "→ becomes an ADR" and move on. Implementation patterns belong in

/architecture-decision

, not the GDD. The GDD describes behavior; the ADR describes the technical approach used to achieve it.

目标：陌生人阅读后能理解的一段文字。

在创建组件前推导推荐选项：从系统索引中读取系统的类别和层级（已在阶段2的上下文中），然后确定每个选项卡的推荐选项：

框架选项卡：基础/基础设施层 → 推荐
```
[A]
```
。面向玩家的类别（战斗、UI、对话、角色、动画、视觉效果、音频）→ 推荐
```
[C] 两者兼具
```
。
ADR引用选项卡：使用Glob匹配
```
docs/architecture/adr-*.md
```
并在任何ADR的GDD要求部分中grep查找系统名称。如果找到匹配的ADR → 推荐
```
[A] 是 — 引用ADR
```
。如果未找到 → 推荐
```
[B] 否
```
。
体验设想选项卡：基础/基础设施层 → 推荐
```
[B] 否
```
。所有其他类别 → 推荐
```
[A] 是
```
。

在每个选项卡的相应选项文本后添加

(推荐)

。

框架问题（在起草前询问）：使用多选项卡组件调用

AskUserQuestion

：

选项卡“框架” — “概述应如何定位该系统？” 选项：

[A] 作为数据/基础设施层（技术定位）

[B] 通过其面向玩家的效果（设计定位）

[C] 两者兼具 — 描述数据层及其对玩家的影响

选项卡“ADR引用” — “概述是否应引用该系统的现有ADR？” 选项：
```
[A] 是 — 引用ADR获取实现细节
```
/
```
[B] 否 — 保持GDD纯设计层面
```

选项卡“体验设想” — “该系统是否有值得阐述的玩家体验设想？” 选项：

[A] 是 — 玩家能直接感受到

[B] 否 — 纯基础设施，玩家感受到的是它所实现的功能

根据用户的回答来起草内容。不要自行回答这些问题并自动起草。

需要询问的问题：

用一句话描述这个系统是什么？
玩家如何与它交互？（主动/被动/自动）
这个系统存在的意义是什么——没有它游戏会失去什么？

交叉引用：检查描述是否与系统索引中的描述一致。标记差异。

设计与实现边界：概述问题必须停留在行为层面——系统做什么，而不是如何构建。如果在概述阶段出现实现问题（例如，“应该使用自动加载单例还是信号总线？”），将其记录为“→ 成为ADR”并继续。实现模式属于

/architecture-decision

，而非GDD。GDD描述行为；ADR描述实现该行为的技术方案。

Section B: Player Fantasy

章节B：玩家体验设想

Goal: The emotional target — what the player should feel.

Derive recommended option before building the widget: Read the system's category and layer from Phase 2 context:

Player-facing categories (Combat, UI, Dialogue, Character, Animation, Audio, Level/World) →
```
[A] Direct
```
recommended
Foundation/Infrastructure layer →
```
[B] Indirect
```
recommended
Mixed categories (Camera/input, Economy, AI with visible player effects) →
```
[C] Both
```
recommended

Append

(Recommended)

to the appropriate option text.

Framing question (ask BEFORE drafting): Use

AskUserQuestion

Prompt: "Is this system something the player engages with directly, or infrastructure they experience indirectly?"

Options:

[A] Direct — player actively uses or feels this system

[B] Indirect — player experiences the effects, not the system

[C] Both — has a direct interaction layer and infrastructure beneath it

Use the answer to frame the Player Fantasy section appropriately. Do NOT assume the answer.

Questions to ask:

What emotion or power fantasy does this serve?
What reference games nail this feeling? What specifically creates it?
Is this a "system you love engaging with" or "infrastructure you don't notice"?

Cross-reference: Must align with the game pillars. If the system serves a pillar, quote the relevant pillar text.

Agent delegation (MANDATORY): After the framing answer is given but before drafting, spawn

creative-director

via Task:

Provide: system name, framing answer (direct/indirect/both), game pillars, any reference games the user mentioned, the game concept summary
Ask: "Shape the Player Fantasy for this system. What emotion or power fantasy should it serve? What player moment should we anchor to? What tone and language fits the game's established feeling? Be specific — give me 2-3 candidate framings."
Collect the creative-director's framings and present them to the user alongside the draft.

Do NOT draft Section B without first consulting
creative-director
. The framing answer tells us what kind of fantasy it is; the creative-director shapes how it's described — tone, language, the specific player moment to anchor to.

目标：情感目标——玩家应该感受到什么。

在创建组件前推导推荐选项：从阶段2的上下文中读取系统的类别和层级：

面向玩家的类别（战斗、UI、对话、角色、动画、音频、关卡/世界）→ 推荐
```
[A] 直接
```
基础/基础设施层 → 推荐
```
[B] 间接
```
混合类别（相机/输入、经济、带有可见玩家效果的AI）→ 推荐
```
[C] 两者兼具
```

在相应选项文本后添加

(推荐)

。

框架问题（在起草前询问）：调用

AskUserQuestion

：

提示：“玩家是直接与该系统交互，还是间接体验其基础设施？”

选项：

[A] 直接 — 玩家主动使用或感受该系统

[B] 间接 — 玩家体验效果，而非系统本身

[C] 两者兼具 — 既有直接交互层又有底层基础设施

根据回答来恰当地构建玩家体验设想章节。不要假设答案。

需要询问的问题：

它服务于哪种情感或能力体验设想？
哪些参考游戏完美呈现了这种感受？具体是什么创造了这种感受？
这是一个“玩家乐于参与的系统”还是“玩家不会注意到的基础设施”？

交叉引用：必须与游戏支柱保持一致。如果系统服务于某个支柱，引用相关的支柱文本。

Agent委托（强制性）：在得到框架答案后但起草前，通过Task调用

creative-director

：

提供：系统名称、框架答案（直接/间接/两者兼具）、游戏支柱、用户提到的任何参考游戏、游戏概念摘要
询问：“塑造该系统的玩家体验设想。它应该服务于哪种情感或能力体验设想？我们应该锚定哪个玩家时刻？哪种语气和语言符合游戏既定的感受？请具体说明——给我2-3个候选方案。”
收集creative-director的方案，并与草稿一起呈现给用户。

在未咨询
creative-director
前，绝不要起草章节B。框架答案告诉我们体验设想的类型；creative-director塑造描述方式——语气、语言、要锚定的具体玩家时刻。

Section C: Detailed Design (Core Rules, States, Interactions)

章节C：详细设计（核心规则、状态、交互）

Goal: Unambiguous specification a programmer could implement without questions.

This is usually the largest section. Break it into sub-sections:

Core Rules: The fundamental mechanics. Use numbered rules for sequential processes, bullets for properties.
States and Transitions: If the system has states, map every state and every valid transition. Use a table.
Interactions with Other Systems: For each dependency (upstream and downstream), specify what data flows in, what flows out, and who owns the interface.

Questions to ask:

Walk me through a typical use of this system, step by step
What are the decision points the player faces?
What can the player NOT do? (Constraints are as important as capabilities)

Agent delegation (MANDATORY): Before drafting Section C, spawn specialist agents via Task in parallel:

Look up the system category in the routing table (Section 6 of this skill)
Spawn the Primary Agent AND Supporting Agent(s) listed for this category
Provide each agent: system name, game concept summary, pillar set, dependency GDD excerpts, the specific section being worked on
Collect their findings before drafting
Surface any disagreements between agents to the user via
```
AskUserQuestion
```
Draft only after receiving specialist input

Do NOT draft Section C without first consulting the appropriate specialists. A

systems-designer

reviewing rules and mechanics will catch design gaps the main session cannot.

Cross-reference: For each interaction listed, verify it matches what the dependency GDD specifies. If a dependency defines a value or formula and this system expects something different, flag the conflict.

目标：明确的规范，程序员无需疑问即可实现。

这通常是最大的章节。将其分为子章节：

核心规则：基础机制。对于顺序流程使用编号规则，对于属性使用项目符号。
状态与转换：如果系统有状态，映射每个状态和每个有效转换。使用表格。
与其他系统的交互：对于每个依赖项（上游和下游），指定流入流出的数据以及谁拥有接口。

需要询问的问题：

逐步引导我了解该系统的典型使用流程
玩家面临哪些决策点？
玩家不能做什么？（约束与能力同样重要）

Agent委托（强制性）：在起草章节C前，通过Task并行调用专家agents：

在路由表（本技能的第6节）中查找系统类别
调用该类别列出的主Agent和辅助Agent
向每个Agent提供：系统名称、游戏概念摘要、支柱集合、依赖GDD摘录、正在处理的具体章节
在起草前收集他们的结论
通过
```
AskUserQuestion
```
向用户展示agents之间的任何分歧
仅在收到专家输入后起草

在未咨询相应专家前，绝不要起草章节C。

systems-designer

审查规则和机制会发现主会话无法察觉的设计缺口。

交叉引用：对于列出的每个交互，验证其是否与依赖GDD的规定一致。如果依赖项定义了一个值或公式，而当前系统期望不同的值，标记冲突。

Section D: Formulas

章节D：公式

Goal: Every mathematical formula, with variables defined, ranges specified, and edge cases noted.

Completion Steering — always begin each formula with this exact structure:

The [formula_name] formula is defined as:

`[formula_name] = [expression]`

**Variables:**
| Variable | Symbol | Type | Range | Description |
|----------|--------|------|-------|-------------|
| [name] | [sym] | float/int | [min–max] | [what it represents] |

**Output Range:** [min] to [max] under normal play; [behaviour at extremes]
**Example:** [worked example with real numbers]

Do NOT write

[Formula TBD]

or describe a formula in prose without the variable table. A formula without defined variables cannot be implemented without guesswork.

Questions to ask:

What are the core calculations this system performs?
Should scaling be linear, logarithmic, or stepped?
What should the output ranges be at early/mid/late game?

Agent delegation (MANDATORY): Before proposing any formulas or balance values, spawn specialist agents via Task in parallel:

Always spawn
systems-designer
: provide Core Rules from Section C, tuning goals from user, balance context from dependency GDDs. Ask them to propose formulas with variable tables and output ranges.
For economy/cost systems, also spawn
economy-designer
: provide placement costs, upgrade cost intent, and progression goals. Ask them to validate cost curves and ratios.
Present the specialists' proposals to the user for review via
```
AskUserQuestion
```
The user decides; the main session writes to file
Do NOT invent formula values or balance numbers without specialist input. A user without balance design expertise cannot evaluate raw numbers — they need the specialists' reasoning.

Cross-reference: If a dependency GDD defines a formula whose output feeds into this system, reference it explicitly. Don't reinvent — connect.

目标：每个数学公式，包含变量定义、范围指定和边缘情况说明。

完成指导 — 每个公式必须以以下精确结构开头：

[formula_name] 公式定义为：

`[formula_name] = [表达式]`

**变量：**
| 变量 | 符号 | 类型 | 范围 | 描述 |
|----------|--------|------|-------|-------------|
| [名称] | [符号] | float/int | [min–max] | [代表含义] |

**输出范围：** 正常游戏中为[min]至[max]；极端情况下的行为：[说明]
**示例：** [使用真实数值的演算示例]

不要写

[Formula TBD]

或仅用散文描述公式而不提供变量表。没有定义变量的公式无法在无猜测的情况下实现。

需要询问的问题：

该系统执行哪些核心计算？
缩放应该是线性、对数还是阶梯式？
游戏早期/中期/后期的输出范围应该是什么？

Agent委托（强制性）：在提出任何公式或平衡值前，通过Task并行调用专家agents：

始终调用
systems-designer
：提供章节C的核心规则、用户的调优目标、来自依赖GDD的平衡上下文。要求他们提出带有变量表和输出范围的公式。
对于经济/成本系统，还需调用
economy-designer
：提供放置成本、升级成本意图和进度目标。要求他们验证成本曲线和比率。
通过
```
AskUserQuestion
```
向用户展示专家的提案供审核
用户做出决策；主会话写入文件
在无专家输入的情况下，绝不要发明公式值或平衡数值。 没有平衡设计专业知识的用户无法评估原始数值——他们需要专家的推理。

交叉引用：如果依赖GDD定义了一个输出输入到当前系统的公式，明确引用它。不要重新发明——要建立关联。

Section E: Edge Cases

章节E：边缘情况

Goal: Explicitly handle unusual situations so they don't become bugs.

Completion Steering — format each edge case as:

If [condition]: [exact outcome]. [rationale if non-obvious]

Example (adapt terminology to the game's domain):

If [resource] reaches 0 while [protective condition] is active: hold at minimum until condition ends, then apply consequence.
If two [triggers/events] fire simultaneously: resolve in [defined priority order]; ties use [defined tiebreak rule].

Do NOT write vague entries like "handle appropriately" — each must name the exact condition and the exact resolution. An edge case without a resolution is an open design question, not a specification.

Questions to ask:

What happens at zero? At maximum? At out-of-range values?
What happens when two rules apply at the same time?
What happens if a player finds an unintended interaction? (Identify degenerate strategies)

Agent delegation (MANDATORY): Spawn

systems-designer

via Task before finalising edge cases. Provide: the completed Sections C and D, and ask them to identify edge cases from the formula and rule space that the main session may have missed. For narrative systems, also spawn

narrative-director

. Present their findings and ask the user which to include.

Cross-reference: Check edge cases against dependency GDDs. If a dependency defines a floor, cap, or resolution rule that this system could violate, flag it.

目标：明确处理异常情况，避免成为漏洞。

完成指导 — 每个边缘情况格式如下：

如果 [条件]：[精确结果]。[非明显情况的理由]

示例（根据游戏领域调整术语）：

如果 [资源] 在 [保护条件] 激活时降至0：保持最小值直到条件结束，然后应用后果。
如果两个 [触发事件] 同时触发：按[定义的优先级顺序]解决；平局使用[定义的平局规则]。

不要写“适当处理”之类的模糊条目——每个条目必须明确条件和精确解决方案。没有解决方案的边缘情况是未解决的设计问题，而非规范。

需要询问的问题：

为0时会发生什么？达到最大值时？超出范围的值时？
两个规则同时适用时会发生什么？
如果玩家发现意外交互会发生什么？（识别退化策略）

Agent委托（强制性）：在最终确定边缘情况前，通过Task调用

systems-designer

。提供：已完成的章节C和D，并要求他们识别主会话可能遗漏的公式和规则空间中的边缘情况。对于叙事系统，还需调用

narrative-director

。展示他们的发现并询问用户要包含哪些。

交叉引用：检查边缘情况是否与依赖GDD一致。如果依赖项定义了当前系统可能违反的下限、上限或解决规则，标记冲突。

Section F: Dependencies

章节F：依赖关系

Goal: Map every system connection with direction and nature.

This section is partially pre-filled from the context gathering phase. Present the known dependencies from the systems index and ask:

Are there dependencies I'm missing?
For each dependency, what's the specific data interface?
Which dependencies are hard (system cannot function without it) vs. soft (enhanced by it but works without it)?

Cross-reference: This section must be bidirectionally consistent. If this system lists "depends on Combat", then the Combat GDD should list "depended on by [this system]". Flag any one-directional dependencies for correction.

目标：映射每个系统连接的方向和性质。

本部分部分内容从上下文收集阶段预填充。展示来自系统索引的已知依赖关系并询问：

是否有我遗漏的依赖项？
对于每个依赖项，具体的数据接口是什么？
哪些依赖项是硬依赖（系统无法脱离它运行） vs. 软依赖（受其增强但无它也能运行）？

交叉引用：本部分必须双向一致。如果当前系统列出“依赖战斗系统”，那么战斗GDD应列出“被[当前系统]依赖”。标记任何单向依赖以修正。

Section G: Tuning Knobs

章节G：调节参数

Goal: Every designer-adjustable value, with safe ranges and extreme behaviors.

Questions to ask:

What values should designers be able to tweak without code changes?
For each knob, what breaks if it's set too high? Too low?
Which knobs interact with each other? (Changing A makes B irrelevant)

Agent delegation: If formulas are complex, delegate to

systems-designer

to derive tuning knobs from the formula variables.

Cross-reference: If a dependency GDD lists tuning knobs that affect this system, reference them here. Don't create duplicate knobs — point to the source of truth.

目标：每个设计师可调整的值，包含安全范围和极端行为。

需要询问的问题：

设计师无需修改代码即可调整哪些值？
对于每个参数，设置过高会破坏什么？设置过低呢？
哪些参数相互影响？（修改A会使B无关紧要）

Agent委托：如果公式复杂，委托给

systems-designer

从公式变量中推导调节参数。

交叉引用：如果依赖GDD列出了影响当前系统的调节参数，在此引用它们。不要创建重复参数——指向真实来源。

Section H: Acceptance Criteria

章节H：验收标准

Goal: Testable conditions that prove the system works as designed.

Completion Steering — format each criterion as Given-When-Then:

GIVEN [initial state], WHEN [action or trigger], THEN [measurable outcome]

Example (adapt terminology to the game's domain):

GIVEN [initial state], WHEN [player action or system trigger], THEN [specific measurable outcome].
GIVEN [a constraint is active], WHEN [player attempts an action], THEN [feedback shown and action result].

Include at least: one criterion per core rule from Section C, and one per formula from Section D. Do NOT write "the system works as designed" — every criterion must be independently verifiable by a QA tester without reading the GDD.

Agent delegation (MANDATORY): Spawn

qa-lead

via Task before finalising acceptance criteria. Provide: the completed GDD sections C, D, E, and ask them to validate that the criteria are independently testable and cover all core rules and formulas. Surface any gaps or untestable criteria to the user.

Questions to ask:

What's the minimum set of tests that prove this works?
What performance budget does this system get? (frame time, memory)
What would a QA tester check first?

Cross-reference: Include criteria that verify cross-system interactions work, not just this system in isolation.

目标：可测试的条件，证明系统按设计运行。

完成指导 — 每个标准格式为Given-When-Then：

给定 [初始状态]，当 [动作或触发]，则 [可测量结果]

示例（根据游戏领域调整术语）：

给定 [初始状态]，当 [玩家动作或系统触发]，则 [具体可测量结果]。
给定 [约束已激活]，当 [玩家尝试动作]，则 [显示反馈并给出动作结果]。

至少包含：章节C中每个核心规则对应一个标准，章节D中每个公式对应一个标准。不要写“系统按设计运行”——每个标准必须能由QA测试人员独立验证，无需阅读GDD。

Agent委托（强制性）：在最终确定验收标准前，通过Task调用

qa-lead

。提供：已完成的GDD章节C、D、E，并要求他们验证标准是否可独立测试且覆盖所有核心规则和公式。向用户展示任何缺口或不可测试的标准。

需要询问的问题：

证明系统正常运行的最小测试集是什么？
该系统的性能预算是多少？（帧时间、内存）
QA测试人员首先会检查什么？

交叉引用：包含验证跨系统交互正常运行的标准，而非仅验证当前系统孤立运行的情况。

Optional Sections: Visual/Audio, UI Requirements, Open Questions

可选章节：视觉/音频、UI要求、未解决问题

These sections are included in the template. Visual/Audio is REQUIRED for visual system categories — not optional. Determine the requirement level before asking:

Visual/Audio is REQUIRED (mandatory — do not offer to skip) for these system categories:

Combat, damage, health
UI systems (HUD, menus)
Animation, character movement
Visual effects, particles, shaders
Character systems
Dialogue, quests, lore
Level/world systems

For required systems: spawn
art-director
via Task before drafting this section. Provide: system name, game concept, game pillars, art bible sections 1–4 if they exist. Ask them to specify: (1) VFX and visual feedback requirements for this system's events, (2) any animation or visual style constraints, (3) which art bible principles most directly apply to this system. Present their output; do NOT leave this section as

[To be designed]

for visual systems.

For all other system categories (Foundation/Infrastructure, Economy, AI/pathfinding, Camera/input), offer the optional sections after the required sections:

Use

AskUserQuestion

"The 8 required sections are complete. Do you want to also define Visual/Audio requirements, UI requirements, or capture open questions?"
- Options: "Yes, all three", "Just open questions", "Skip — I'll add these later"

For Visual/Audio (non-required systems): Coordinate with

art-director

and

audio-director

if detail is needed. Often a brief note suffices at the GDD stage.

Asset Spec Flag: After the Visual/Audio section is written with real content, output this notice: "📌 Asset Spec — Visual/Audio requirements are defined. After the art bible is approved, run
/asset-spec system:[system-name]
to produce per-asset visual descriptions, dimensions, and generation prompts from this section."

For UI Requirements: Coordinate with

ux-designer

for complex UI systems. After writing this section, check whether it contains real content (not just

[To be designed]

or a note that this system has no UI). If it does have real UI requirements, output this flag immediately:

📌 UX Flag — [System Name]: This system has UI requirements. In Phase 4 (Pre-Production), run
/ux-design
to create a UX spec for each screen or HUD element this system contributes to before writing epics. Stories that reference UI should cite
design/ux/[screen].md
, not the GDD directly.
Note this in the systems index for this system if you update it.

For Open Questions: Capture anything that came up during design that wasn't fully resolved. Each question should have an owner and target resolution date.

这些章节包含在模板中。视觉/音频章节对于视觉系统类别是必填——并非可选。在询问前确定要求级别：

视觉/音频章节为必填（强制——不得跳过）的系统类别：

战斗、伤害、生命值
UI系统（HUD、菜单）
动画、角色移动
视觉效果、粒子、着色器
角色系统
对话、任务、传说
关卡/世界系统

对于必填系统：在起草本章节前通过Task调用
art-director
。提供：系统名称、游戏概念、游戏支柱、艺术手册第1-4节（如果存在）。要求他们指定：(1) 该系统事件的视觉特效和视觉反馈要求，(2) 任何动画或视觉风格约束，(3) 艺术手册中哪些原则最直接适用于该系统。展示他们的输出；视觉系统的本章节不得留为

[To be designed]

。

对于所有其他系统类别（基础/基础设施、经济、AI/寻路、相机/输入），在完成必填章节后提供可选章节：

调用

AskUserQuestion

：

“8个必填章节已完成。您是否还想定义视觉/音频要求、UI要求或记录未解决问题？”
- 选项：“是的，全部三个”、“仅未解决问题”、“跳过——我稍后添加”

对于视觉/音频（非必填系统）：如果需要详细内容，与

art-director

和

audio-director

协作。在GDD阶段通常简短说明即可。

资产规格标记：当视觉/音频章节写入实际内容后，输出此通知： “📌 资产规格 — 已定义视觉/音频要求。艺术手册批准后，运行
/asset-spec system:[system-name]
从本章节生成每个资产的视觉描述、尺寸和生成提示。”

对于UI要求：复杂UI系统需与

ux-designer

协作。写入本章节后，检查是否包含实际内容（而非仅

[To be designed]

或该系统无UI的说明）。如果包含实际UI要求，立即输出此标记：

📌 UX标记 — [系统名称]：该系统有UI要求。在阶段4（预生产），运行
/ux-design
为该系统贡献的每个屏幕或HUD元素创建UX规格在编写史诗故事之前。引用UI的故事应引用
design/ux/[screen].md
，而非直接引用GDD。
如果更新系统索引，请在该系统的条目中记录此内容。

对于未解决问题：记录设计过程中出现的所有未完全解决的问题。每个问题应包含负责人和目标解决日期。

5. Post-Design Validation

5. 设计后验证

After all sections are written:

所有章节写入后：

5a: Self-Check

5a：自我检查

Read back the complete GDD from file (not from conversation memory — the file is the source of truth). Verify:

All 8 required sections have real content (not placeholders)
Formulas reference defined variables
Edge cases have resolutions
Dependencies are listed with interfaces
Acceptance criteria are testable

从文件中读取完整的GDD（而非从对话内存中——文件是唯一来源）。验证：

所有8个必填章节都有实际内容（非占位符）
公式引用已定义的变量
边缘情况有解决方案
依赖关系列出了接口
验收标准可测试

5a-bis: Creative Director Pillar Review

5a-bis：创意总监支柱审查

Review mode check — apply before spawning CD-GDD-ALIGN:

```
solo
```
→ skip. Note: "CD-GDD-ALIGN skipped — Solo mode." Proceed to Step 5b.
```
lean
```
→ skip (not a PHASE-GATE). Note: "CD-GDD-ALIGN skipped — Lean mode." Proceed to Step 5b.
```
full
```
→ spawn as normal.

Before finalizing the GDD, spawn

creative-director

via Task using gate CD-GDD-ALIGN (

.claude/docs/director-gates.md

Pass: completed GDD file path, game pillars (from

design/gdd/game-concept.md

design/gdd/game-pillars.md

), MDA aesthetics target.

Handle verdict per the standard rules in

director-gates.md

. After resolution, record the verdict in the GDD Status header:

> **Creative Director Review (CD-GDD-ALIGN)**: APPROVED [date] / CONCERNS (accepted) [date] / REVISED [date]

审查模式检查 — 在调用CD-GDD-ALIGN前应用：

```
solo
```
→ 跳过。记录：“CD-GDD-ALIGN已跳过——单人模式。” 继续步骤5b。
```
lean
```
→ 跳过（非阶段关卡）。记录：“CD-GDD-ALIGN已跳过——精简模式。” 继续步骤5b。
```
full
```
→ 正常调用。

在最终确定GDD前，通过Task使用关卡 CD-GDD-ALIGN（

.claude/docs/director-gates.md

）调用

creative-director

。

传递：已完成的GDD文件路径、游戏支柱（来自

design/gdd/game-concept.md

或

design/gdd/game-pillars.md

）、MDA美学目标。

根据

director-gates.md

中的标准规则处理评审结果。解决后，在GDD状态标题中记录评审结果：

> **创意总监审查（CD-GDD-ALIGN）**：已批准 [日期] / 已接受意见 [日期] / 已修订 [日期]

5b: Update Entity Registry

5b：更新实体注册表

Scan the completed GDD for cross-system facts that should be registered:

Named entities (enemies, NPCs, bosses) with stats or drops
Named items with values, weights, or categories
Named formulas with defined variables and output ranges
Named constants referenced by value in more than one place

For each candidate, check if it already exists in

design/registry/entities.yaml

Grep pattern="  - name: [candidate_name]" path="design/registry/entities.yaml"

Present a summary:

Registry candidates from this GDD:
  NEW (not yet registered):
    - [entity_name] [entity]: [attribute]=[value], [attribute]=[value]
    - [item_name] [item]: [attribute]=[value], [attribute]=[value]
    - [formula_name] [formula]: variables=[list], output=[min–max]
  ALREADY REGISTERED (referenced_by will be updated):
    - [constant_name] [constant]: value=[N] ← matches registry ✅

Ask: "May I update

design/registry/entities.yaml

with these [N] new entries and update

referenced_by

for the existing entries?"

If yes: append new entries and update

referenced_by

arrays. Never modify existing

value

/ attribute fields without surfacing it as a conflict first.

扫描已完成的GDD以查找应注册的跨系统事实：

带有属性或掉落物的命名实体（敌人、NPC、Boss）
带有数值、重量或类别的命名物品
带有定义变量和输出范围的命名公式
在多个地方按值引用的命名常量

对于每个候选条目，检查是否已存在于

design/registry/entities.yaml

中：

Grep pattern="  - name: [candidate_name]" path="design/registry/entities.yaml"

展示摘要：

本GDD中的注册表候选条目：
  新增（尚未注册）：
    - [entity_name] [entity类型]：[attribute]=[value], [attribute]=[value]
    - [item_name] [item类型]：[attribute]=[value], [attribute]=[value]
    - [formula_name] [formula类型]：变量=[列表], 输出=[min–max]
  已注册（将更新referenced_by）：
    - [constant_name] [constant类型]：值=[N] ← 与注册表匹配 ✅

询问：“是否可以更新

design/registry/entities.yaml

添加这[N]个新条目，并更新现有条目的

referenced_by

？”

如果是：追加新条目并更新

referenced_by

数组。在未先提出冲突的情况下，绝不要修改现有的

value

/ 属性字段。

5c: Offer Design Review

5c：提供设计审查

Present a completion summary:

GDD Complete: [System Name]

Sections written: [list]

Provisional assumptions: [list any assumptions about undesigned dependencies]

Cross-system conflicts found: [list or "none"]

To validate this GDD, open a fresh Claude Code session and run:
/design-review design/gdd/[system-name].md
Never run
/design-review
in the same session as
/design-system
. The reviewing agent must be independent of the authoring context. Running it here would inherit the full design history, making independent critique impossible.

NEVER offer to run
/design-review
inline. Always direct the user to a fresh window.

展示完成摘要：

GDD完成：[系统名称]

已写入章节：[列表]

临时假设：[列出对未设计依赖项的任何假设]

发现的跨系统冲突：[列表或“无”]

要验证本GDD，请打开新的Claude Code会话并运行：
/design-review design/gdd/[system-name].md
绝不要在与
/design-system
相同的会话中运行
/design-review
。审查Agent必须独立于创作上下文。在此运行会继承完整的设计历史，使其无法进行独立批判。

绝不要提供内联运行
/design-review
的选项。始终引导用户打开新窗口。

5d: Update Systems Index

5d：更新系统索引

After the GDD is complete (and optionally reviewed):

Read the systems index
Update the target system's row:
- If design-review was run and verdict is APPROVED: Status → "Approved"
- If design-review was run and verdict is NEEDS REVISION: Status → "In Review"
- If design-review was skipped: Status → "Designed" (pending review)
- If the user chose "I'll review it myself first": Status → "Designed"
- Design Doc: link to
```
design/gdd/[system-name].md
```
Update the Progress Tracker counts

Ask: "May I update the systems index at

design/gdd/systems-index.md

GDD完成后（可选审查后）：

读取系统索引
更新目标系统的行：
- 如果已运行design-review且结果为已批准：状态 → “已批准”
- 如果已运行design-review且结果为需要修订：状态 → “审查中”
- 如果跳过design-review：状态 → “已设计”（待审查）
- 如果用户选择“我先自行审查”：状态 → “已设计”
- 设计文档：链接到
```
design/gdd/[system-name].md
```
更新进度跟踪器计数

询问：“是否可以更新

design/gdd/systems-index.md

中的系统索引？”

5d: Update Session State

5d：更新会话状态

Update

production/session-state/active.md

with:

Task: [system-name] GDD
Status: Complete (or In Review if design-review was run)
File: design/gdd/[system-name].md
Sections: All 8 written
Next: [suggest next system from design order]

更新

production/session-state/active.md

：

任务：[system-name] GDD
状态：完成（或如果已运行design-review则为审查中）
文件：design/gdd/[system-name].md
章节：8个全部已写入
下一步：[建议设计顺序中的下一个系统]

5e: Suggest Next Steps

5e：建议下一步操作

Use

AskUserQuestion

"What's next?"
- Options:
  - "Run
```
/consistency-check
```
    — verify this GDD's values don't conflict with existing GDDs (recommended before designing the next system)"
  - "Design next system ([next-in-order])" — if undesigned systems remain
  - "Fix review findings" — if design-review flagged issues
  - "Stop here for this session"
  - "Run
```
/gate-check
```
    " — if enough MVP systems are designed

调用

AskUserQuestion

：

“下一步做什么？”
- 选项：
  - “运行
```
/consistency-check
```
    — 验证本GDD的值与现有GDD无冲突（设计下一个系统前推荐）”
  - “设计下一个系统 ([next-in-order])” — 如果仍有未设计的系统
  - “修复审查发现的问题” — 如果design-review标记了问题
  - “本次会话到此为止”
  - “运行
```
/gate-check
```
    ” — 如果已设计足够的MVP系统

6. Specialist Agent Routing

6. 专家Agent路由

This skill delegates to specialist agents for domain expertise. The main session orchestrates the overall flow; agents provide expert content.

System Category	Primary Agent	Supporting Agent(s)
Foundation/Infrastructure (event bus, save/load, scene mgmt, service locator)	`systems-designer`	`gameplay-programmer` (feasibility), `engine-programmer` (engine integration)
Combat, damage, health	`game-designer`	`systems-designer` (formulas), `ai-programmer` (enemy AI), `art-director` (hit feedback visual direction, VFX intent)
Economy, loot, crafting	`economy-designer`	`systems-designer` (curves), `game-designer` (loops)
Progression, XP, skills	`game-designer`	`systems-designer` (curves), `economy-designer` (sinks)
Dialogue, quests, lore	`game-designer`	`narrative-director` (story), `writer` (content), `art-director` (character visual profiles, cinematic tone)
UI systems (HUD, menus)	`game-designer`	`ux-designer` (flows), `ui-programmer` (feasibility), `art-director` (visual style direction), `technical-artist` (render/shader constraints)
Audio systems	`game-designer`	`audio-director` (direction), `sound-designer` (specs)
AI, pathfinding, behavior	`game-designer`	`ai-programmer` (implementation), `systems-designer` (scoring)
Level/world systems	`game-designer`	`level-designer` (spatial), `world-builder` (lore)
Camera, input, controls	`game-designer`	`ux-designer` (feel), `gameplay-programmer` (feasibility)
Animation, character movement	`game-designer`	`art-director` (animation style, pose language), `technical-artist` (rig/blend constraints), `gameplay-programmer` (feel)
Visual effects, particles, shaders	`game-designer`	`art-director` (VFX visual direction), `technical-artist` (performance budget, shader complexity), `systems-designer` (trigger/state integration)
Character systems (stats, archetypes)	`game-designer`	`art-director` (character visual archetype), `narrative-director` (character arc alignment), `systems-designer` (stat formulas)

When delegating via Task tool:

Provide: system name, game concept summary, dependency GDD excerpts, the specific section being worked on, and what question needs expert input
The agent returns analysis/proposals to the main session
The main session presents the agent's output to the user via
```
AskUserQuestion
```
The user decides; the main session writes to file
Agents do NOT write to files directly — the main session owns all file writes

本技能委托给专家agents获取领域专业知识。主会话协调整体流程；agents提供专业内容。

系统类别	主Agent	辅助Agent
基础/基础设施（事件总线、保存/加载、场景管理、服务定位器）	`systems-designer`	`gameplay-programmer` （可行性）、 `engine-programmer` （引擎集成）
战斗、伤害、生命值	`game-designer`	`systems-designer` （公式）、 `ai-programmer` （敌人AI）、 `art-director` （命中反馈视觉方向、视觉特效意图）
经济、战利品、制作	`economy-designer`	`systems-designer` （曲线）、 `game-designer` （循环）
进度、经验值、技能	`game-designer`	`systems-designer` （曲线）、 `economy-designer` （消耗）
对话、任务、传说	`game-designer`	`narrative-director` （故事）、 `writer` （内容）、 `art-director` （角色视觉档案、电影化语气）
UI系统（HUD、菜单）	`game-designer`	`ux-designer` （流程）、 `ui-programmer` （可行性）、 `art-director` （视觉风格方向）、 `technical-artist` （渲染/着色器约束）
音频系统	`game-designer`	`audio-director` （方向）、 `sound-designer` （规格）
AI、寻路、行为	`game-designer`	`ai-programmer` （实现）、 `systems-designer` （评分）
关卡/世界系统	`game-designer`	`level-designer` （空间设计）、 `world-builder` （传说）
相机、输入、控制	`game-designer`	`ux-designer` （手感）、 `gameplay-programmer` （可行性）
动画、角色移动	`game-designer`	`art-director` （动画风格、姿态语言）、 `technical-artist` （骨骼绑定/混合约束）、 `gameplay-programmer` （手感）
视觉效果、粒子、着色器	`game-designer`	`art-director` （视觉特效方向）、 `technical-artist` （性能预算、着色器复杂度）、 `systems-designer` （触发/状态集成）
角色系统（属性、原型）	`game-designer`	`art-director` （角色视觉原型）、 `narrative-director` （角色弧对齐）、 `systems-designer` （属性公式）

通过Task工具委托时：

提供：系统名称、游戏概念摘要、依赖GDD摘录、正在处理的具体章节、需要专家输入的问题
Agent向主会话返回分析/提案
主会话通过
```
AskUserQuestion
```
向用户展示Agent的输出
用户做出决策；主会话写入文件
Agents不得直接写入文件——所有文件写入由主会话负责

7. Recovery & Resume

7. 恢复与继续

If the session is interrupted (compaction, crash, new session):

Read
```
production/session-state/active.md
```
— it records the current system and which sections are complete
Read
```
design/gdd/[system-name].md
```
— sections with real content are done; sections with
```
[To be designed]
```
still need work
Resume from the next incomplete section — no need to re-discuss completed ones

This is why incremental writing matters: every approved section survives any disruption.

如果会话中断（压缩、崩溃、新会话）：

读取
```
production/session-state/active.md
```
—— 它记录了当前系统和已完成的章节
读取
```
design/gdd/[system-name].md
```
—— 带有实际内容的章节已完成；带有
```
[To be designed]
```
的章节仍需处理
从下一个未完成的章节继续——无需重新讨论已完成的章节

这就是逐步写入的重要性：每个已批准的章节都能在任何中断后保留。

Collaborative Protocol

协作协议

This skill follows the collaborative design principle at every step:

Question -> Options -> Decision -> Draft -> Approval for every section
AskUserQuestion at every decision point (Explain -> Capture pattern):
- Phase 2: "Ready to start, or need more context?"
- Phase 3: "May I create the skeleton?"
- Phase 4 (each section): Design questions, approach options, draft approval
- Phase 5: "Run design review? Update systems index? What's next?"
"May I write to [filepath]?" before the skeleton and before each section write
Incremental writing: Each section is written to file immediately after approval
Session state updates: After every section write
Cross-referencing: Every section checks existing GDDs for conflicts
Specialist routing: Complex sections get expert agent input, presented to the user for decision — never written silently

Never auto-generate the full GDD and present it as a fait accompli. Never write a section without user approval. Never contradict an existing approved GDD without flagging the conflict. Always show where decisions come from (dependency GDDs, pillars, user choices).

本技能在每个步骤都遵循协作设计原则：

每个章节遵循问题 -> 选项 -> 决策 -> 草稿 -> 审批流程
每个决策点使用
```
AskUserQuestion
```
（解释 -> 捕获模式）：
- 阶段2：“准备开始，还是需要更多上下文？”
- 阶段3：“是否可以创建框架？”
- 阶段4（每个章节）：设计问题、方案选项、草稿审批
- 阶段5：“运行设计审查？更新系统索引？下一步做什么？”
在创建框架和每个章节写入前询问**“是否可以写入[filepath]？”**
逐步写入：每个章节在批准后立即写入文件
会话状态更新：每个章节写入后更新
交叉引用：每个章节检查现有GDD是否存在冲突
专家路由：复杂章节获取专家Agent输入，呈现给用户决策——绝不静默写入

绝不要自动生成完整GDD并将其作为既成事实呈现。 绝不要在未获得用户批准的情况下写入章节。 绝不要在未标记冲突的情况下与现有已批准GDD矛盾。始终展示决策的来源（依赖GDD、支柱、用户选择）。

Context Window Awareness

上下文窗口感知

This is a long-running skill. After writing each section, check if the status line shows context at or above 70%. If so, append this notice to the response:

Context is approaching the limit (≥70%). Your progress is saved — all approved sections are written to
design/gdd/[system-name].md
. When you're ready to continue, open a fresh Claude Code session and run
/design-system [system-name]
— it will detect which sections are complete and resume from the next one.

这是一个长期运行的技能。每个章节写入后，检查状态行是否显示上下文达到或超过70%。如果是，在回复中附加此通知：

上下文即将达到限制（≥70%）。 您的进度已保存——所有已批准章节已写入
design/gdd/[system-name].md
。准备好继续时，打开新的Claude Code会话并运行
/design-system [system-name]
——它会检测哪些章节已完成并从下一个章节继续。