---
name: create-architecture
description: "逐节引导编写游戏主架构文档。读取所有 GDD、系统索引、现有 ADR 及引擎参考库，在编写任何代码之前生成完整的架构蓝图。具备引擎版本感知能力：标记知识缺口，并针对已锁定的引擎版本验证各项决策。"
argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Task
agent: technical-director
---

# 创建架构

本技能生成 `docs/architecture/architecture.md`——主架构文档，负责将所有已审批的 GDD 转化为具体的技术蓝图。它处于设计与实现之间，必须在迭代规划开始之前完成。

**与 `/architecture-decision` 的区别**：ADR 记录单个节点决策。本技能创建的是整体系统蓝图，为 ADR 提供上下文。

一次性确定评审模式（存储以供本次运行的所有关卡触发使用）：
1. 如果传入了 `--review [full|lean|solo]` → 使用该值
2. 否则读取 `production/review-mode.txt` → 使用该值
3. 否则 → 默认为 `lean`

完整的关卡检查模式见 `.claude/docs/director-gates.md`。

**参数模式：**
- **无参数 / `full`**：完整引导流程——所有章节，从头到尾
- **`layers`**：仅聚焦系统层级图
- **`data-flow`**：仅聚焦模块间的数据流
- **`api-boundaries`**：仅聚焦 API 边界定义
- **`adr-audit`**：仅审计现有 ADR 的引擎兼容性缺口

---

## 阶段 0：加载全量上下文

在做任何操作之前，按以下顺序加载完整的项目上下文：

### 0a. 引擎上下文（关键）

完整读取引擎参考库：

1. `docs/engine-reference/[engine]/VERSION.md`
   → 提取：引擎名称、版本、LLM 知识截止时间、截止后风险等级
2. `docs/engine-reference/[engine]/breaking-changes.md`
   → 提取：所有 HIGH 和 MEDIUM 风险变更
3. `docs/engine-reference/[engine]/deprecated-apis.md`
   → 提取：需要避免的 API
4. `docs/engine-reference/[engine]/current-best-practices.md`
   → 提取：与训练数据不同的截止后最佳实践
5. `docs/engine-reference/[engine]/modules/` 下的所有文件
   → 提取：各领域的当前 API 模式

如果没有配置引擎，停止并提示：
> "未配置引擎。请先运行 `/setup-engine`。在不知道目标引擎及版本的情况下，无法编写架构文档。"

### 0b. 设计上下文 + 技术需求提取

读取所有已审批的设计文档，并从每份文档中提取技术需求：

1. `design/gdd/game-concept.md` — 游戏支柱、类型、核心循环
2. `design/gdd/systems-index.md` — 所有系统、依赖关系、优先级层级
3. `.claude/docs/technical-preferences.md` — 命名规范、性能预算、允许的库、禁止的模式
4. **`design/gdd/` 中的每一份 GDD** — 对每份文档提取技术需求：
   - 游戏规则隐含的数据结构
   - 明确或隐含的性能约束
   - 系统所需的引擎能力
   - 跨系统通信模式（什么与什么通信、如何通信）
   - 必须持久化的状态（存档/读档含义）
   - 线程或时序要求

建立**技术需求基准**——跨所有 GDD 提取的全量需求列表，编号格式为 `TR-[gdd-slug]-[NNN]`。这是架构必须覆盖的完整集合。展示格式为：

```
## 技术需求基准
提取自 [N] 份 GDD | 共 [X] 条需求

| 需求 ID | GDD | 系统 | 需求内容 | 领域 |
|--------|-----|------|---------|------|
| TR-combat-001 | combat.md | 战斗 | 每帧碰撞箱检测 | 物理 |
| TR-combat-002 | combat.md | 战斗 | 连击状态机 | 核心 |
| TR-inventory-001 | inventory.md | 背包 | 道具持久化 | 存档/读档 |
```

该基准将输入到后续每个阶段。在本次会话结束时，每条 GDD 需求都应有对应的架构决策来支撑。

### 0c. 现有架构决策

读取 `docs/architecture/` 中的所有文件，了解已做出的决策。列出所有已找到的 ADR 及其领域。

### 0d. 生成知识缺口清单

在继续之前，展示结构化汇总：

```
## 引擎知识缺口清单
引擎：[名称 + 版本]
LLM 训练数据覆盖：约 [版本] 之前
截止后版本：[列表]

### HIGH 风险领域（决策前必须对照引擎参考文档核实）
- [领域]：[关键变更]

### MEDIUM 风险领域（核实关键 API）
- [领域]：[关键变更]

### LOW 风险领域（在训练数据中，可能较为可靠）
- [领域]：[截止后无重大变更]

### GDD 中涉及 HIGH/MEDIUM 风险领域的系统：
- [GDD 系统名] → [领域] → [风险等级]
```

询问："该清单识别出 [N] 个系统处于 HIGH 风险引擎领域。是否继续构建架构，并在全程标注这些警告？"

---

## 阶段 1：系统层级映射

将 `systems-index.md` 中的每个系统归入一个架构层级。标准游戏架构层级如下：

```
┌─────────────────────────────────────────────┐
│  表现层（PRESENTATION LAYER）               │  ← UI、HUD、菜单、VFX、音频
├─────────────────────────────────────────────┤
│  功能层（FEATURE LAYER）                    │  ← 游戏玩法系统、AI、任务
├─────────────────────────────────────────────┤
│  核心层（CORE LAYER）                       │  ← 物理、输入、战斗、移动
├─────────────────────────────────────────────┤
│  基础层（FOUNDATION LAYER）                 │  ← 引擎集成、存档/读档、
│                                             │    场景管理、事件总线
├─────────────────────────────────────────────┤
│  平台层（PLATFORM LAYER）                   │  ← 操作系统、硬件、引擎 API 接口
└─────────────────────────────────────────────┘
```

对每个 GDD 系统，思考：
- 它属于哪个层级？
- 它的模块边界是什么？
- 它独占拥有什么？（数据、状态、行为）

展示建议的层级分配，在继续下一章节之前征得批准。将已审批的层级图立即写入骨架文件。

**引擎感知检查**：对于分配到核心层和基础层的每个系统，如果涉及 HIGH 或 MEDIUM 风险的引擎领域，则进行标注，并内联展示相关引擎参考文档摘录。

---

## 阶段 2：模块归属图

对阶段 1 中定义的每个模块，明确归属：

- **归属（Owns）**：该模块独自负责的数据和状态
- **暴露（Exposes）**：其他模块可读取或调用的内容
- **消费（Consumes）**：它从其他模块读取的内容
- **使用的引擎 API**：该模块直接调用的引擎类/节点/信号（注明版本和风险等级）

先按层级以表格形式输出，再以 ASCII 依赖关系图呈现。

**引擎感知检查**：对列出的每个引擎 API，对照相关模块参考文档进行核实。如果 API 是截止后的，进行标注：

```
⚠️  [ClassName.method()] — Godot 4.6（截止后，HIGH 风险）
    核实依据：docs/engine-reference/godot/modules/[domain].md
    行为已确认：[是 / 待核实]
```

在写入前征得用户对归属图的批准。

---

## 阶段 3：数据流

定义关键游戏场景中数据在模块间的流动方式。至少覆盖以下场景：

1. **帧更新路径**：输入 → 核心系统 → 状态 → 渲染
2. **事件/信号路径**：系统如何在无紧耦合的情况下通信
3. **存档/读档路径**：哪些状态被序列化、哪个模块负责序列化
4. **初始化顺序**：哪些模块必须先于其他模块启动

在适当位置使用 ASCII 时序图。对每条数据流：
- 命名被传输的数据
- 标识生产者和消费者
- 说明是同步调用、信号/事件还是共享状态
- 标注跨线程边界的任何数据流

逐场景征得用户批准后再写入。

---

## 阶段 4：API 边界

定义模块间的公共契约。对每个边界：

- 模块向系统其他部分暴露什么接口？
- 有哪些入口点（函数/信号/属性）？
- 调用方必须遵守哪些不变量？
- 模块对调用方有哪些保证？

用伪代码或项目实际语言（来自技术偏好文档）表述。这些契约将成为程序员的实现依据。

**引擎感知检查**：如果任何接口使用了引擎特定类型（例如 Godot 中的 `Node`、`Resource`、`Signal`），标注其版本，并核实该类型在目标引擎版本中是否存在且签名未变更。

---

## 阶段 5：ADR 审计 + 可追溯性检查

对照阶段 1-4 构建的架构以及阶段 0b 的技术需求基准，审查阶段 0c 中所有已有的 ADR。

### ADR 质量检查

对每个 ADR：
- [ ] 是否包含引擎兼容性章节？
- [ ] 是否记录了引擎版本？
- [ ] 是否标注了截止后的 API？
- [ ] 是否包含"已解决的 GDD 需求"章节？
- [ ] 是否与本次会话中的层级/归属决策冲突？
- [ ] 对于已锁定的引擎版本，该 ADR 是否仍然有效？

| ADR | 引擎兼容性 | 版本 | GDD 关联 | 冲突 | 有效性 |
|-----|----------|------|---------|------|-------|
| ADR-0001：[标题] | ✅/❌ | ✅/❌ | ✅/❌ | 无/[冲突] | ✅/⚠️ |

### 可追溯性覆盖检查

将技术需求基准中的每条需求映射到现有 ADR。对每条需求，检查是否有 ADR 的"已解决的 GDD 需求"章节或决策内容涵盖了它：

| 需求 ID | 需求内容 | ADR 覆盖 | 状态 |
|--------|---------|---------|------|
| TR-combat-001 | 每帧碰撞箱检测 | ADR-0003 | ✅ |
| TR-combat-002 | 连击状态机 | — | ❌ 缺口 |

统计：X 条已覆盖，Y 条缺口。每个缺口成为一个**必须新建的 ADR**。

### 需要新建的 ADR

列出本次架构会话（阶段 1-4）中做出的、尚无对应 ADR 的所有决策，加上所有未覆盖的技术需求。按层级分组——基础层优先：

**基础层（编码开始前必须创建）：**
- `/architecture-decision [标题]` → 覆盖：TR-[id], TR-[id]

**核心层：**
- `/architecture-decision [标题]` → 覆盖：TR-[id]

---

## 阶段 6：缺失 ADR 清单

基于完整架构，生成应当存在但尚未创建的 ADR 完整列表。按优先级分组：

**编码开始前必须有（基础层和核心层决策）：**
- [例如"场景管理与场景加载策略"]
- [例如"事件总线 vs. 直接信号架构"]

**相关系统构建前应当有：**
- [例如"背包序列化格式"]

**可推迟到实现阶段：**
- [例如"水面渲染的具体着色器技术"]

---

## 阶段 7：编写主架构文档

所有章节获批后，将完整文档写入 `docs/architecture/architecture.md`。

询问："是否允许我将主架构文档写入 `docs/architecture/architecture.md`？"

文档结构：

```markdown
# [游戏名称] — 主架构

## 文档状态
- 版本：[N]
- 最后更新：[日期]
- 引擎：[名称 + 版本]
- 已覆盖的 GDD：[列表]
- 引用的 ADR：[列表]

## 引擎知识缺口摘要
[来自阶段 0d 清单的精简版——HIGH/MEDIUM 风险领域及其影响]

## 系统层级图
[来自阶段 1]

## 模块归属
[来自阶段 2]

## 数据流
[来自阶段 3]

## API 边界
[来自阶段 4]

## ADR 审计
[来自阶段 5]

## 需要创建的 ADR
[来自阶段 6]

## 架构原则
[3-5 条指导本项目所有技术决策的核心原则，
 从游戏概念、GDD 和技术偏好文档中提炼而来]

## 待解决问题
[已推迟的决策——必须在构建相关层级之前解决]
```

---

## 阶段 7b：技术总监签字 + 主程序员可行性评审

完成主架构文档后，在移交之前执行明确的签字流程。

**步骤 1 — 技术总监自我审查**（本技能以 technical-director 身份运行）：

将关卡 **TD-ARCHITECTURE**（`.claude/docs/director-gates.md`）作为自我审查，针对已完成的文档检查该关卡定义的四项标准。

**评审模式检查** — 在生成 LP-FEASIBILITY 前应用：
- `solo` → 跳过。注明："LP-FEASIBILITY 已跳过——Solo 模式。"继续进行阶段 8 移交。
- `lean` → 跳过（非 PHASE-GATE）。注明："LP-FEASIBILITY 已跳过——Lean 模式。"继续进行阶段 8 移交。
- `full` → 正常生成。

**步骤 2 — 通过 Task 工具生成 `lead-programmer` 子智能体，应用关卡 LP-FEASIBILITY（`.claude/docs/director-gates.md`）：**

传入：架构文档路径、技术需求基准摘要、ADR 列表。

**步骤 3 — 向用户同时展示两份评估结果：**

并排展示技术总监评估与主程序员结论。

使用 `AskUserQuestion`——"技术总监和主程序员已完成架构评审。您希望如何处理？"
选项：`接受——继续移交` / `先修正标注的问题` / `讨论具体关切`

**步骤 4 — 在架构文档中记录签字：**

更新文档状态章节：
```
- 技术总监签字：[日期] — APPROVED / APPROVED WITH CONDITIONS
- 主程序员可行性：FEASIBLE / CONCERNS ACCEPTED / REVISED
```

询问："是否允许我更新 `docs/architecture/architecture.md` 文档状态章节中的签字信息？"

---

## 阶段 8：移交

文档写入完成后，提供清晰的移交说明：

1. **接下来运行这些 ADR**（来自阶段 6，按优先级排序）：列出前 3 个
2. **关卡检查**："主架构文档已完成。所有必要的 ADR 也写完后，运行 `/gate-check pre-production`。"
3. **更新会话状态**：将摘要写入 `production/session-state/active.md`

---

## 协作协议

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

1. **静默加载上下文** — 不要旁白读取文件的过程
2. **展示发现** — 呈现知识缺口清单和层级建议
3. **决策前先询问** — 对每个架构选择提供选项
4. **写入前征得批准** — 每个阶段章节只有在用户批准内容后才写入
5. **增量写入** — 每个获批章节立即写入；不要积攒所有内容最后一次性写入。这样可以在会话崩溃时幸存。

不得在未获得用户输入的情况下做出有约束力的架构决策。如果用户不确定，在请其决策之前先提供 2-4 个选项并分析利弊。

---

## 推荐下一步

- 对阶段 6 中列出的每个必要 ADR 运行 `/architecture-decision [标题]`——基础层 ADR 优先
- 所有必要 ADR 写完后，运行 `/create-control-manifest` 以生成层级规则清单
- 所有必要 ADR 写完且架构获得签字确认后，运行 `/gate-check pre-production`