Imported from brand6/Claude-Code-Game-Studios-zh-auto (.claude/skills/create-architecture/SKILL.md). Install upstream with npx skills add brand6/Claude-Code-Game-Studios-zh-auto --skill create-architecture. Copyright stays with the author.

创建架构

本技能生成 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。对每条需求，检查是否有 ADR 的"已解决的 GDD 需求"章节或决策内容涵盖了它：

统计：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？"

文档结构：

# [游戏名称] — 主架构

## 文档状态
- 版本：[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