Back to Details

create-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Architecture

创建架构

This skill produces 
docs/architecture/architecture.md
— the master architecture document that translates all approved GDDs into a concrete technical blueprint. It sits between design and implementation, and must exist before sprint planning begins.
Distinct from 
/architecture-decision
: ADRs record individual point decisions. This skill creates the whole-system blueprint that gives ADRs their context.
Resolve the review mode (once, store for all gate spawns this run):
  1. If 
    --review [full|lean|solo]
    was passed → use that
  2. Else read 
    production/review-mode.txt
    → use that value
  3. Else → default to 
    lean
See 
.claude/docs/director-gates.md
for the full check pattern.
Argument modes:
  • No argument / 
    full
    : Full guided walkthrough — all sections, start to finish
  • layers
    : Focus on the system layer diagram only
  • data-flow
    : Focus on data flow between modules only
  • api-boundaries
    : Focus on API boundary definitions only
  • adr-audit
    : Audit existing ADRs for engine compatibility gaps only
本Skill会生成
docs/architecture/architecture.md
——将所有已批准的GDD转化为具体技术蓝图的主架构文档。它处于设计与实现之间，必须在冲刺规划开始前完成。
与
/architecture-decision
的区别：ADR记录单个点决策。本Skill创建为ADR提供上下文的全系统蓝图。
解决审阅模式（本次运行中所有gate生成均使用该模式，仅设置一次）：
  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的引擎兼容性缺口

Phase 0: Load All Context

阶段0：加载所有上下文

Before anything else, load the full project context in this order:
在开始任何操作前，按以下顺序加载完整项目上下文：

0a. Engine Context (Critical)

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

Read the engine reference library completely:
  1. docs/engine-reference/[engine]/VERSION.md
    → Extract: engine name, version, LLM cutoff, post-cutoff risk levels
  2. docs/engine-reference/[engine]/breaking-changes.md
    → Extract: all HIGH and MEDIUM risk changes
  3. docs/engine-reference/[engine]/deprecated-apis.md
    → Extract: APIs to avoid
  4. docs/engine-reference/[engine]/current-best-practices.md
    → Extract: post-cutoff best practices that differ from training data
  5. All files in 
    docs/engine-reference/[engine]/modules/
    → Extract: current API patterns per domain
If no engine is configured, stop and prompt:
"No engine is configured. Run 
/setup-engine
first. Architecture cannot be written without knowing which engine and version you are targeting."
完整读取引擎参考库：
  1. docs/engine-reference/[engine]/VERSION.md
    → 提取：引擎名称、版本、LLM知识截止版本、截止后风险等级
  2. docs/engine-reference/[engine]/breaking-changes.md
    → 提取：所有高风险和中风险变更
  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. Design Context + Technical Requirements Extraction

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

Read all approved design documents and extract technical requirements from each:
  1. design/gdd/game-concept.md
    — game pillars, genre, core loop
  2. design/gdd/systems-index.md
    — all systems, dependencies, priority tiers
  3. .claude/docs/technical-preferences.md
    — naming conventions, performance budgets, allowed libraries, forbidden patterns
  4. Every GDD in 
    design/gdd/
     — for each, extract technical requirements:
    • Data structures implied by the game rules
    • Performance constraints stated or implied
    • Engine capabilities the system requires
    • Cross-system communication patterns (what talks to what, how)
    • State that must persist (save/load implications)
    • Threading or timing requirements
Build a Technical Requirements Baseline — a flat list of all extracted requirements across all GDDs, numbered 
TR-[gdd-slug]-[NNN]
. This is the complete set of what the architecture must cover. Present it as:
undefined
读取所有已批准的设计文档，并从中提取技术需求：
  1. design/gdd/game-concept.md
    — 游戏支柱、类型、核心循环
  2. design/gdd/systems-index.md
    — 所有系统、依赖关系、优先级层级
  3. .claude/docs/technical-preferences.md
    — 命名规范、性能预算、允许使用的库、禁用模式
  4. design/gdd/
    下的所有GDD     — 针对每个GDD，提取以下技术需求：
    • 游戏规则隐含的数据结构
    • 明确或隐含的性能约束
    • 系统所需的引擎能力
    • 跨系统通信模式（哪些系统交互、如何交互）
    • 必须持久化的状态（对存档/读档的影响）
    • 线程或时序要求
构建技术需求基线——所有GDD中提取的需求的扁平化列表，编号格式为
TR-[gdd-slug]-[NNN]
。这是架构必须覆盖的完整需求集合。呈现格式如下：
undefined

Technical Requirements Baseline

技术需求基线

Extracted from [N] GDDs | [X] total requirements
Req IDGDDSystemRequirementDomain
TR-combat-001combat.mdCombatHitbox detection per-framePhysics
TR-combat-002combat.mdCombatCombo state machineCore
TR-inventory-001inventory.mdInventoryItem persistenceSave/Load

This baseline feeds into every subsequent phase. No GDD requirement should be
left without an architectural decision to support it by the end of this session.
提取自[N]份GDD | 共[X]项需求
需求IDGDD系统需求内容领域
TR-combat-001combat.md战斗系统逐帧检测碰撞箱物理
TR-combat-002combat.md战斗系统连招状态机核心
TR-inventory-001inventory.md背包系统物品持久化存档/读档

该基线将为后续所有阶段提供输入。到本次会话结束时，所有GDD需求都应有对应的架构决策来支持。

0c. Existing Architecture Decisions

0c. 现有架构决策

Read all files in 
docs/architecture/
to understand what has already been decided. List any ADRs found and their domains.
读取
docs/architecture/
下的所有文件，了解已做出的决策。列出找到的所有ADR及其所属领域。

0d. Generate Knowledge Gap Inventory

0d. 生成知识缺口清单

Before proceeding, display a structured summary:
undefined
在继续操作前，显示结构化摘要：
undefined

Engine Knowledge Gap Inventory

引擎知识缺口清单

Engine: [name + version] LLM Training Covers: up to approximately [version] Post-Cutoff Versions: [list]
引擎：[名称 + 版本] LLM训练覆盖：约至[版本] 截止后版本：[列表]

HIGH RISK Domains (must verify against engine reference before deciding)

高风险领域（决策前必须对照引擎参考验证）

  • [Domain]: [Key changes]
  • [领域]：[关键变更]

MEDIUM RISK Domains (verify key APIs)

中风险领域（需验证关键API）

  • [Domain]: [Key changes]
  • [领域]：[关键变更]

LOW RISK Domains (in training data, likely reliable)

低风险领域（在训练数据中，可靠性较高）

  • [Domain]: [no significant post-cutoff changes]
  • [领域]：[无重大截止后变更]

Systems from GDD that touch HIGH/MEDIUM risk domains:

涉及高/中风险领域的GDD系统：

  • [GDD system name] → [domain] → [risk level]

Use `AskUserQuestion`:
- Prompt: "One or more engine domains are HIGH RISK — the LLM's knowledge may be unreliable for these areas. Architectural recommendations in these domains should be cross-referenced with the engine docs before being acted on. How would you like to proceed?"
- Options:
  - `[A] Proceed — flag HIGH RISK domains throughout the output`
  - `[B] Let me check the engine reference first — pause here`
  - `[C] Show me which domains are HIGH RISK and why`

---
  • [GDD系统名称] → [领域] → [风险等级]

调用`AskUserQuestion`：
- 提示："存在一个或多个高风险引擎领域——LLM在这些领域的知识可能不可靠。这些领域的架构建议在实施前应与引擎文档交叉验证。您希望如何继续？"
- 选项：
  - `[A] 继续——在输出中标记高风险领域`
  - `[B] 我先查看引擎参考——在此暂停`
  - `[C] 告诉我哪些是高风险领域及原因`

---

Phase 1: System Layer Mapping

阶段1：系统层映射

Map every system from 
systems-index.md
into an architecture layer. The standard game architecture layers are:
┌─────────────────────────────────────────────┐
│  PRESENTATION LAYER                         │  ← UI, HUD, menus, VFX, audio
├─────────────────────────────────────────────┤
│  FEATURE LAYER                              │  ← gameplay systems, AI, quests
├─────────────────────────────────────────────┤
│  CORE LAYER                                 │  ← physics, input, combat, movement
├─────────────────────────────────────────────┤
│  FOUNDATION LAYER                           │  ← engine integration, save/load,
│                                             │    scene management, event bus
├─────────────────────────────────────────────┤
│  PLATFORM LAYER                             │  ← OS, hardware, engine API surface
└─────────────────────────────────────────────┘
For each GDD system, ask:
  • Which layer does it belong to?
  • What are its module boundaries?
  • What does it own exclusively? (data, state, behaviour)
Present the proposed layer assignment and ask for approval before proceeding to the next section. Write the approved layer map immediately to the skeleton file.
Engine awareness check: For each system assigned to the Core and Foundation layers, flag if it touches a HIGH or MEDIUM risk engine domain. Show the relevant engine reference excerpt inline.
将
systems-index.md
中的每个系统映射到架构层。标准游戏架构层如下：
┌─────────────────────────────────────────────┐
│  表现层（PRESENTATION LAYER）               │  ← UI、HUD、菜单、视觉特效、音频
├─────────────────────────────────────────────┤
│  功能层（FEATURE LAYER）                    │  ← 游戏玩法系统、AI、任务
├─────────────────────────────────────────────┤
│  核心层（CORE LAYER）                       │  ← 物理、输入、战斗、移动
├─────────────────────────────────────────────┤
│  基础层（FOUNDATION LAYER）                 │  ← 引擎集成、存档/读档、
│                                             │    场景管理、事件总线
├─────────────────────────────────────────────┤
│  平台层（PLATFORM LAYER）                   │  ← 操作系统、硬件、引擎API接口
└─────────────────────────────────────────────┘
针对每个GDD系统，确认：
  • 它属于哪个层？
  • 它的模块边界是什么？
  • 它独家负责哪些内容？（数据、状态、行为）
在进入下一章节前，呈现提议的层分配方案并请求批准。立即将批准后的层映射写入框架文件。
引擎感知检查：对于分配到核心层和基础层的每个系统，标记它是否涉及高风险或中风险引擎领域。在文中内联显示相关的引擎参考摘录。

Phase 2: Module Ownership Map

阶段2：模块所有权映射

For each module defined in Phase 1, define ownership:
  • Owns: what data and state this module is solely responsible for
  • Exposes: what other modules may read or call
  • Consumes: what it reads from other modules
  • Engine APIs used: which specific engine classes/nodes/signals this module calls directly (with version and risk level noted)
Format as a table per layer, then as an ASCII dependency diagram.
Engine awareness check: For every engine API listed, verify against the relevant module reference doc. If an API is post-cutoff, flag it:
⚠️  [ClassName.method()] — Godot 4.6 (post-cutoff, HIGH risk)
    Verified against: docs/engine-reference/godot/modules/[domain].md
    Behaviour confirmed: [yes / NEEDS VERIFICATION]
Get user approval on the ownership map before writing.
针对阶段1中定义的每个模块，明确所有权：
  • 负责（Owns）：该模块独家负责的数据和状态
  • 暴露（Exposes）：其他模块可读取或调用的内容
  • 依赖（Consumes）：它从其他模块读取的内容
  • 使用的引擎API：该模块直接调用的具体引擎类/节点/信号（注明版本和风险等级）
按层以表格形式呈现，再以ASCII依赖图展示。
引擎感知检查：对于列出的每个引擎API，对照相关模块参考文档进行验证。如果API是截止后版本，标记如下：
⚠️  [ClassName.method()] — Godot 4.6（截止后版本，高风险）
    验证来源：docs/engine-reference/godot/modules/[domain].md
    行为确认：[是 / 需要验证]
在写入前获取用户对所有权映射的批准。

Phase 3: Data Flow

阶段3：数据流

Define how data moves between modules during key game scenarios. Cover at minimum:
  1. Frame update path: Input → Core systems → State → Rendering
  2. Event/signal path: How systems communicate without tight coupling
  3. Save/load path: What state is serialised, which module owns serialisation
  4. Initialisation order: Which modules must boot before others
Use ASCII sequence diagrams where helpful. For each data flow:
  • Name the data being transferred
  • Identify the producer and consumer
  • State whether this is synchronous call, signal/event, or shared state
  • Flag any data flows that cross thread boundaries
Get user approval per scenario before writing.
定义关键游戏场景中模块间的数据流动方式。至少覆盖以下场景：
  1. 帧更新路径：输入 → 核心系统 → 状态 → 渲染
  2. 事件/信号路径：系统如何在不紧密耦合的情况下通信
  3. 存档/读档路径：哪些状态被序列化，哪个模块负责序列化
  4. 初始化顺序：哪些模块必须在其他模块之前启动
必要时使用ASCII序列图。针对每个数据流：
  • 命名传输的数据
  • 确定生产者和消费者
  • 说明这是同步调用、信号/事件还是共享状态
  • 标记任何跨线程边界的数据流
针对每个场景获取用户批准后再写入。

Phase 4: API Boundaries

阶段4：API边界

Define the public contracts between modules. For each boundary:
  • What is the interface a module exposes to the rest of the system?
  • What are the entry points (functions/signals/properties)?
  • What invariants must callers respect?
  • What must the module guarantee to callers?
Write in pseudocode or the project's actual language (from technical preferences). These become the contracts programmers implement against.
Engine awareness check: If any interface uses engine-specific types (e.g. 
Node
, 
Resource
, 
Signal
in Godot), flag the version and verify the type exists and has not changed signature in the target engine version.
定义模块间的公共契约。针对每个边界：
  • 模块向系统其他部分暴露的接口是什么？
  • 入口点有哪些（函数/信号/属性）？
  • 调用者必须遵守哪些不变量？
  • 模块必须向调用者保证什么？
用伪代码或项目实际使用的语言（来自技术偏好）编写。这些将成为程序员实现时遵循的契约。
引擎感知检查：如果任何接口使用引擎特定类型（如Godot中的
Node
、
Resource
、
Signal
），标记版本并验证该类型在目标引擎版本中存在且签名未变更。

Phase 5: ADR Audit + Traceability Check

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

Review all existing ADRs from Phase 0c against both the architecture built in Phases 1-4 AND the Technical Requirements Baseline from Phase 0b.
对照阶段1-4构建的架构以及阶段0b的技术需求基线，复查阶段0c中的所有现有ADR。

ADR Quality Check

ADR质量检查

For each ADR:
  • Does it have an Engine Compatibility section?
  • Is the engine version recorded?
  • Are post-cutoff APIs flagged?
  • Does it have a "GDD Requirements Addressed" section?
  • Does it conflict with the layer/ownership decisions made in this session?
  • Is it still valid for the pinned engine version?
ADREngine CompatVersionGDD LinkageConflictsValid
ADR-0001: [title]✅/❌✅/❌✅/❌None/[conflict]✅/⚠️
针对每个ADR：
  • 是否包含引擎兼容性章节？
  • 是否记录了引擎版本？
  • 是否标记了截止后API？
  • 是否包含“已覆盖的GDD需求”章节？
  • 是否与本次会话中做出的层/所有权决策冲突？
  • 对于固定的引擎版本是否仍然有效？
ADR引擎兼容性版本记录GDD关联冲突情况是否有效
ADR-0001: [标题]✅/❌✅/❌✅/❌无/[冲突内容]✅/⚠️

Traceability Coverage Check

可追溯性覆盖检查

Map every requirement from the Technical Requirements Baseline to existing ADRs. For each requirement, check if any ADR's "GDD Requirements Addressed" section or decision text covers it:
Req IDRequirementADR CoverageStatus
TR-combat-001Hitbox detection per-frameADR-0003✅
TR-combat-002Combo state machine—❌ GAP
Count: X covered, Y gaps. For each gap, it becomes a Required New ADR.
将技术需求基线中的每个需求映射到现有ADR。针对每个需求，检查是否有任何ADR的“已覆盖的GDD需求”章节或决策文本涵盖了该需求：
需求ID需求内容ADR覆盖情况状态
TR-combat-001逐帧检测碰撞箱ADR-0003✅
TR-combat-002连招状态机—❌ 缺口
统计：已覆盖X项，缺口Y项。每个缺口将成为需新增的ADR。

Required New ADRs

需新增的ADR

List all decisions made during this architecture session (Phases 1-4) that do not yet have a corresponding ADR, PLUS all uncovered Technical Requirements. Group by layer — Foundation first:
Foundation Layer (must create before any coding):
  • /architecture-decision [title]
    → covers: TR-[id], TR-[id]
Core Layer:
  • /architecture-decision [title]
    → covers: TR-[id]
列出本次架构会话（阶段1-4）中做出的所有尚未有对应ADR的决策，以及所有未覆盖的技术需求。按层分组——先列基础层：
基础层（编码前必须创建）：
  • /architecture-decision [标题]
    → 覆盖：TR-[id], TR-[id]
核心层：
  • /architecture-decision [标题]
    → 覆盖：TR-[id]

Phase 6: Missing ADR List

阶段6：缺失ADR清单

Based on the full architecture, produce a complete list of ADRs that should exist but don't yet. Group by priority:
Must have before coding starts (Foundation & Core decisions):
  • [e.g. "Scene management and scene loading strategy"]
  • [e.g. "Event bus vs direct signal architecture"]
Should have before the relevant system is built:
  • [e.g. "Inventory serialisation format"]
Can defer to implementation:
  • [e.g. "Specific shader technique for water"]
基于完整架构，生成应存在但尚未创建的ADR完整清单。按优先级分组：
编码开始前必须创建（基础层和核心层决策）：
  • [例如：“场景管理与场景加载策略”]
  • [例如：“事件总线 vs 直接信号架构”]
相关系统构建前应创建：
  • [例如：“背包序列化格式”]
可延迟至实现阶段：
  • [例如：“水面特效的特定着色器技术”]

Phase 7: Write the Master Architecture Document

阶段7：编写主架构文档

Once all sections are approved, write the complete document to 
docs/architecture/architecture.md
.
Display a one-paragraph summary of what the document will contain (layers, modules, data flows, ADR gaps). Then use 
AskUserQuestion
:
  • "All sections approved. May I write the master architecture document?"
    • [A] Yes — write to 
      docs/architecture/architecture.md
      now
    • [B] Show me the full draft inline first, then ask again
    • [C] Not yet — I have more changes to discuss
The document structure:
markdown
undefined
所有章节获得批准后，将完整文档写入
docs/architecture/architecture.md
。
显示文档内容的一段摘要（涵盖层、模块、数据流、ADR缺口）。然后调用
AskUserQuestion
：
  • "所有章节已批准。是否可以编写主架构文档？"
    • [A] 是——立即写入
      docs/architecture/architecture.md
    • [B] 先在文中显示完整草稿，再询问
    • [C] 暂不编写——我还有更多修改意见要讨论
文档结构：
markdown
undefined

[Game Name] — Master Architecture

[游戏名称] — 主架构文档

Document Status

文档状态

  • Version: [N]
  • Last Updated: [date]
  • Engine: [name + version]
  • GDDs Covered: [list]
  • ADRs Referenced: [list]
  • 版本：[N]
  • 最后更新：[日期]
  • 引擎：[名称 + 版本]
  • 覆盖的GDD：[列表]
  • 参考的ADR：[列表]

Engine Knowledge Gap Summary

引擎知识缺口摘要

[Condensed from Phase 0d inventory — HIGH/MEDIUM risk domains and their implications]
[摘自阶段0d的清单——高/中风险领域及其影响]

System Layer Map

系统层映射

[From Phase 1]
[来自阶段1]

Module Ownership

模块所有权

[From Phase 2]
[来自阶段2]

Data Flow

数据流

[From Phase 3]
[来自阶段3]

API Boundaries

API边界

[From Phase 4]
[来自阶段4]

ADR Audit

ADR审核

[From Phase 5]
[来自阶段5]

Required ADRs

需新增的ADR

[From Phase 6]
[来自阶段6]

Architecture Principles

架构原则

[3-5 key principles that govern all technical decisions for this project, derived from the game concept, GDDs, and technical preferences]
[3-5项指导本项目所有技术决策的核心原则，源自游戏概念、GDD和技术偏好]

Open Questions

待解决问题

[Decisions deferred — must be resolved before the relevant layer is built]

---
[延迟做出的决策——必须在相关层构建前解决]

---

Phase 7b: Technical Director Sign-Off + Lead Programmer Feasibility Review

阶段7b：技术总监签字确认 + 首席程序员可行性评审

After writing the master architecture document, perform an explicit sign-off before handoff.
Step 1 — Technical Director self-review (this skill runs as technical-director):
Apply gate TD-ARCHITECTURE (
.claude/docs/director-gates.md
) as a self-review. Check all four criteria from that gate definition against the completed document.
Review mode check — apply before spawning LP-FEASIBILITY:
  • solo
    → skip. Note: "LP-FEASIBILITY skipped — Solo mode." Proceed to Phase 8 handoff.
  • lean
    → skip (not a PHASE-GATE). Note: "LP-FEASIBILITY skipped — Lean mode." Proceed to Phase 8 handoff.
  • full
    → spawn as normal.
Step 2 — Spawn 
lead-programmer
via Task using gate LP-FEASIBILITY (
.claude/docs/director-gates.md
):
Pass: architecture document path, technical requirements baseline summary, ADR list.
Step 3 — Present both assessments to the user:
Show the Technical Director assessment and Lead Programmer verdict side by side.
Use 
AskUserQuestion
— "Technical Director and Lead Programmer have reviewed the architecture. How would you like to proceed?" Options: 
Accept — proceed to handoff
/ 
Revise flagged items first
/ 
Discuss specific concerns
Step 4 — Record sign-off in the architecture document:
Update the Document Status section:
- Technical Director Sign-Off: [date] — APPROVED / APPROVED WITH CONDITIONS
- Lead Programmer Feasibility: FEASIBLE / CONCERNS ACCEPTED / REVISED
Show the proposed Document Status block inline, then use 
AskUserQuestion
:
  • "May I update the Document Status section with the sign-off results?"
    • [A] Yes — apply to 
      docs/architecture/architecture.md
    • [B] Not yet — I want to revisit the concerns first
编写完主架构文档后，在移交前执行明确的签字确认流程。
步骤1 — 技术总监自我评审（本Skill以技术总监身份运行）：
应用
TD-ARCHITECTURE
gate（
.claude/docs/director-gates.md
）进行自我评审。对照已完成的文档检查该gate定义的所有四项标准。
审阅模式检查 — 在生成LP-FEASIBILITY前应用：
  • solo
    → 跳过。备注：“LP-FEASIBILITY已跳过——单人模式。” 进入阶段8移交。
  • lean
    → 跳过（非PHASE-GATE）。备注：“LP-FEASIBILITY已跳过——精简模式。” 进入阶段8移交。
  • full
    → 正常生成。
步骤2 — 通过Task生成
lead-programmer
，应用LP-FEASIBILITY gate（
.claude/docs/director-gates.md
）：
传递：架构文档路径、技术需求基线摘要、ADR列表。
步骤3 — 向用户呈现两项评估结果：
并排显示技术总监评估结果和首席程序员评审结论。
调用
AskUserQuestion
— "技术总监和首席程序员已评审架构文档。您希望如何继续？" 选项：
接受——进入移交环节
/ 
先修改标记的问题
/ 
讨论具体问题
步骤4 — 在架构文档中记录签字确认：
更新文档状态章节：
- 技术总监签字确认：[日期] — 批准 / 有条件批准
- 首席程序员可行性评审：可行 / 问题已接受 / 已修订
在文中显示提议的文档状态块，然后调用
AskUserQuestion
：
  • "是否可以将签字确认结果更新到文档状态章节？"
    • [A] 是——应用到
      docs/architecture/architecture.md
    • [B] 暂不更新——我想先重新讨论相关问题

Phase 8: Handoff

阶段8：移交

Step 1 — Update session state: Write a summary to 
production/session-state/active.md
covering: artifact written, TD/LP sign-off verdicts, any blockers, required ADRs remaining, and next step.
Step 2 — Output the handoff using exactly this template (no freeform prose, no rephrasing of section titles):
步骤1 — 更新会话状态：向
production/session-state/active.md
写入摘要，涵盖：已生成的工件、技术总监/首席程序员的签字结论、任何阻塞项、剩余需创建的ADR、下一步操作。
步骤2 — 输出移交内容，严格使用以下模板（不得使用自由格式文本，不得重命名章节标题）：

Architecture Complete

架构文档已完成

docs/architecture/architecture.md
v1.0 — [TD verdict: APPROVED / APPROVED WITH CONCERNS / CONCERNS]. [One sentence on what the architecture covers.]
docs/architecture/architecture.md
v1.0 — [技术总监结论：批准 / 有条件批准 / 存在问题]。[一句话说明架构文档涵盖的内容。]

Run These ADRs Next

下一步需创建的ADR

1. 
/architecture-decision "[Title]"
→ ADR-[XXXX] [One sentence: what it defines and what it unblocks.]
2. 
/architecture-decision "[Title]"
→ ADR-[XXXX] [One sentence.]
3. 
/architecture-decision "[Title]"
→ ADR-[XXXX] [One sentence.]
List top 3 from Phase 6 in priority order. If fewer than 3 remain, list only what's outstanding.
1. 
/architecture-decision "[标题]"
→ ADR-[XXXX] [一句话：定义内容及解锁的事项。]
2. 
/architecture-decision "[标题]"
→ ADR-[XXXX] [一句话说明。]
3. 
/architecture-decision "[标题]"
→ ADR-[XXXX] [一句话说明。]
按优先级列出阶段6中的前3项。如果剩余不足3项，仅列出未完成的项。

Gate-Check Readiness

Gate检查准备情况

Required before 
/gate-check [stage]
:
  • Accept ADRs: [list Proposed ADR IDs that must be Accepted]
  • Write ADRs: [list ADR IDs that must still be written]
  • Run 
    /test-setup
    — scaffolds 
    tests/unit/
    , 
    tests/integration/
    , CI workflow, and an example test file
  • Run 
    /ux-design
    — creates 
    design/ux/interaction-patterns.md
    and 
    design/accessibility-requirements.md
Run 
/gate-check [stage]
when all boxes are checked.
If nothing is blocking, write instead:
No blockers — run 
/gate-check [stage]
now.
运行
/gate-check [stage]
前需完成：
  • 接受ADR：[列出必须接受的提议ADR ID]
  • 编写ADR：[列出仍需编写的ADR ID]
  • 运行
    /test-setup
    — 搭建
    tests/unit/
    、
    tests/integration/
    、CI工作流及示例测试文件
  • 运行
    /ux-design
    — 创建
    design/ux/interaction-patterns.md
    和
    design/accessibility-requirements.md
所有复选框完成后运行
/gate-check [stage]
。
如果无阻塞项，改为：
无阻塞项——立即运行
/gate-check [stage]
。

Open Questions to Watch

需关注的待解决问题

IDSummaryPriorityResolution Path
QQ-XX[short description]High / Medium / Low[ADR or system that resolves it]
Omit this section entirely if there are no open QQs.
(End of handoff. Do not add trailing commentary after the closing rule.)
ID摘要优先级解决路径
QQ-XX[简短描述]高 / 中 / 低[解决该问题的ADR或系统]
如果没有待解决问题，完全省略本章节。
（移交结束。请勿在结束分隔线后添加任何评论。）

Collaborative Protocol

协作协议

This skill follows the collaborative design principle at every phase:
  1. Load context silently — do not narrate file reads
  2. Present findings — show the knowledge gap inventory and layer proposals
  3. Ask before deciding — present options for each architectural choice
  4. Draft before approval — show the content inline before asking to write it. Never ask approval for a section the user has not yet seen.
  5. Use 
    AskUserQuestion
    for write approvals     — plain text "May I?" is not sufficient. Use the structured tool with labeled options [A]/[B]/[C] (write now / show full draft first / not yet). For multi-file changesets, list every file and what changes, then ask once grouped — not separate plain-text asks per file.
  6. Incremental writing — write each approved section immediately; do not accumulate everything and write at the end. This survives session crashes.
Never make a binding architectural decision without user input. If the user is unsure, present 2-4 options with pros/cons before asking them to decide.
本Skill在每个阶段都遵循协作设计原则：
  1. 静默加载上下文 — 不要叙述文件读取过程
  2. 呈现发现结果 — 展示知识缺口清单和层提议
  3. 决策前询问 — 为每个架构选择呈现选项
  4. 先草稿后批准 — 在请求写入前先在文中显示内容。绝不要在用户尚未查看章节内容的情况下请求批准。
  5. 使用
    AskUserQuestion
    请求写入批准     — 纯文本“是否可以？”不够。使用带[A]/[B]/[C]标签选项的结构化工具（立即写入 / 先显示完整草稿 / 暂不写入）。对于多文件变更集，列出每个文件及变更内容，然后一次性请求批准——不要对每个文件单独使用纯文本询问。
  6. 增量式写入 — 立即写入每个已批准的章节；不要累积所有内容再一次性写入。这样可以避免会话崩溃导致的内容丢失。
未经用户输入，不得做出具有约束力的架构决策。如果用户不确定，先呈现2-4个带有优缺点的选项，再请求用户决策。

Recommended Next Steps

推荐下一步操作

  • Run 
    /architecture-decision [title]
    for each required ADR listed in Phase 6 — Foundation layer ADRs first
  • Run 
    /architecture-review
    — bootstraps the Requirements Traceability Matrix and TR registry from the ADRs just written. Required before the Pre-Production gate.
  • Run 
    /test-setup
    to scaffold 
    tests/unit/
    , 
    tests/integration/
    , CI workflow, and an example test (required for gate-check)
  • Run 
    /ux-design
    to initialize 
    design/ux/interaction-patterns.md
    and 
    design/accessibility-requirements.md
    (required for gate-check)
  • Run 
    /create-control-manifest
    once the required ADRs are written to produce the layer rules manifest
  • Run 
    /gate-check pre-production
    when all required ADRs, 
    /test-setup
    , and 
    /ux-design
    are complete
  • 为阶段6中列出的每个需新增ADR运行
    /architecture-decision [title]
    — 优先创建基础层ADR
  • 运行
    /architecture-review
    — 从刚创建的ADR中引导生成需求可追溯矩阵和TR注册表。预生产gate前必须完成。
  • 运行
    /test-setup
    搭建
    tests/unit/
    、
    tests/integration/
    、CI工作流及示例测试（gate检查必需）
  • 运行
    /ux-design
    初始化
    design/ux/interaction-patterns.md
    和
    design/accessibility-requirements.md
    （gate检查必需）
  • 需新增的ADR创建完成后，运行
    /create-control-manifest
    生成层规则清单
  • 所有需新增ADR、
    /test-setup
    和
    /ux-design
    完成后，运行
    /gate-check pre-production
    ",