ADR-[NNNN]: [Title]
【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios
Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
Date
[YYYY-MM-DD — when this ADR was written]
- **编号**：NNNN 为三位零填充序号，由技能扫描 `docs/architecture/` 下已有 ADR 文件名自动递增分配，不允许手工猜号（见 [架构决策技能 Step 2](https://link.gitcode.com/i/ff0150bf823a47962c76155002ceab99)）。 - **Status 四种取值**：`Proposed`（草拟）、`Accepted`（已接受）、`Deprecated`（已弃用）、`Superseded by ADR-XXXX`（被新 ADR 取代）。新写的 ADR **永远从 Proposed 开始**——技能明确禁止向用户询问状态，除非有导演关卡 APPROVED。 - **Date**：记录决策书写日期。 ### 2. Last Verified（最近复核日期） ```markdown ## Last Verified [YYYY-MM-DD — when this ADR was last confirmed accurate against the current engine version and design. Update this date when you re-read and confirm it is still correct, even if nothing changed.]这是模板独有的"保鲜"机制：即使内容未变，只要重新对照当前引擎版本与设计复核过，就要更新此日期。它让"内容过时但无人知晓"的 ADR 显形——技能检查器可以按 Last Verified 的时间戳识别需要复核的旧决策。
3. Decision Makers 与 Summary
## Decision Makers [Who was involved in this decision] ## Summary [2 sentences: what problem this ADR solves, and what was decided. Written for tiered context loading — a skill scanning 20 ADRs uses this to decide whether to read the full decision. Be specific: name the system, the problem, and the chosen approach.]- Decision Makers：记录参与决策的角色（例如 technical-director、lead-programmer、相关引擎专家）。
- Summary是"分层上下文加载"（tiered context loading）的关键字段：当技能一次性扫描 20 份 ADR 时，只靠 Summary 就能判断是否需要读取全文。因此要求两句话内点名系统、问题、所选方案三个要素。写不好 Summary 的 ADR，在长会话中会被技能漏读。
4. Engine Compatibility（引擎兼容性矩阵）
| Field | Value | |-------|-------| | **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] | | **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] | | **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] | | **References Consulted** | [e.g. `docs/engine-reference/godot/modules/physics.md`, `breaking-changes.md`] | | **Post-Cutoff APIs Used** | [Specific APIs from post-cutoff engine versions this decision depends on, or "None"] | | **Verification Required** | [Concrete behaviours to test against the target engine version before shipping, or "None"] |这是 CCGS 应对"LLM 知识截止线"的核心防线。以 Godot 引擎版本参考 docs/engine-reference/godot/VERSION.md 为例：项目锁定 Godot 4.6（2026 年 1 月发布），而 LLM 知识截止为 2025 年 5 月，4.4/4.5/4.6 均存在模型未知的变更（如 Jolt 物理成为默认、glow 重构、D3D12 默认渲染）。因此：
- Domain必须是模板列出的枚举值之一，便于技能按域检索对应 模块参考文档；
- Knowledge Risk直接取自 VERSION.md 的风险表；
- Post-Cutoff APIs Used显式列出决策依赖的、截止线之后才出现的 API；没有则写 "None"；
- Verification Required填写上线前必须实测的行为，形成可执行的验证清单。
模板对此有硬性规则：若 Knowledge Risk 为 MEDIUM 或 HIGH，一旦项目升级引擎版本，该 ADR 必须重新验证，标记为 "Superseded" 并重写新 ADR。这正是 引擎风险审核关卡 TD-ENGINE-RISK 的存在意义——它要求审核者核对 API 在锁定版本中是否存在、签名是否变化、有无弃用替代。
5. ADR Dependencies（ADR 依赖矩阵）
| Field | Value | |-------|-------| | **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] | | **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] | | **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] | | **Ordering Note** | [Any sequencing constraint that isn't captured above] |该矩阵把 ADR 组织成依赖图：某 ADR 依赖的上游必须已 Accepted 才能实施；它又可能解锁下游 ADR 或阻塞某个 Epic 启动。在 架构决策技能 Step 4 中，这三问被显式要求向用户确认：是否依赖未 Accepted 的 ADR？是否解锁/解锁其他 ADR 或 Epic？是否阻塞具体 Epic？没有约束则逐项填 "None"。/story-readiness依赖此字段判断 Story 能否进入 Sprint——Status 缺失时它无法验证 ADR 接受状态，因此 retrofit 模式把 Status 列为BLOCKING级缺失项。
6. Context（决策上下文）
Context 由四个子块组成，回答"为什么要现在决定、不决定的代价是什么"：
### Problem Statement [What problem are we solving? Why must this decision be made now? What is the cost of not deciding?] ### Current State [How does the system work today? What is wrong with the current approach?] ### Constraints - [Technical constraints -- engine limitations, platform requirements] - [Timeline constraints -- deadline pressures, dependencies] - [Resource constraints -- team size, expertise available] - [Compatibility requirements -- must work with existing systems] ### Requirements - [Functional requirement 1] - [Functional requirement 2] - [Performance requirement -- specific, measurable] - [Scalability requirement]注意约束与需求是两类不同信息：Constraints 是外部给定的边界（引擎限制、平台要求、工期压力、团队规模、兼容要求），Requirements 是决策必须满足的目标（功能、可测量的性能指标、扩展性）。性能需求必须具体可测——这为后续 Performance Implications 区块提供了"Before/After/Budget"的填写依据。
7. Decision（决策主体）
## Decision [The specific technical decision, described in enough detail for someone to implement it without further clarification.] ### Architecture[ASCII diagram showing the system architecture this decision creates. Show components, data flow direction, and key interfaces.]
### Key Interfaces[Pseudocode or language-specific interface definitions that this decision creates. These become the contracts that implementers must respect.]
### Implementation Guidelines [Specific guidance for the programmer implementing this decision.]这是整个 ADR 的"契约"部分，判定标准是"不依赖进一步澄清即可被实现"。三个子块各司其职：
- Architecture：ASCII 架构图，必须表达组件、数据流方向、关键接口，而不是画示意图；
- Key Interfaces：伪代码或语言相关的接口定义——这是实现者必须遵守的合同，也是后续 GDD 同步检查的比对基准；
- Implementation Guidelines：给实现程序员的专项指引。
在 架构决策技能 Step 5.5 中，Decision 与 Key Interfaces 会被提交给主引擎专家（primary engine specialist，按.claude/docs/technical-preferences.md配置）做 API 层面校验，确认方案对锁定引擎版本是否惯用（idiomatic）、有无已弃用或改名的 API；随后提交给技术总监走 TD-ADR 关卡做架构一致性审查。任何一个环节发现阻塞性问题，Decision 区块都要修订后重走流程。
8. Alternatives Considered（备选方案）
### Alternative 1: [Name] - **Description**: [How this approach would work] - **Pros**: [What is good about this approach] - **Cons**: [What is bad about this approach] - **Estimated Effort**: [Relative effort compared to chosen approach] - **Rejection Reason**: [Why this was not chosen] ### Alternative 2: [Name] [Same structure as above]每个备选方案必须给出相对工作量与明确拒绝理由。TD-ADR 关卡会专门审查"被拒绝的备选方案是否被认真考虑过"——只列方案名称而缺 Pros/Cons/拒绝理由的 Alternatives 区块会被直接打回。技能在撰写前会基于 GDD 需求与引擎参考库主动推导 2-3 个候选（来自引擎参考、来自 GDD 需求、来自常见模式），经用户确认后进入草稿。
9. Consequences（决策后果）
### Positive - [Good outcomes of this decision] ### Negative - [Trade-offs and costs we are accepting] ### Neutral - [Changes that are neither good nor bad, just different]Positive / Negative / Neutral 三分法强制诚实记录代价。"Negative"中明确表达的"不要使用 X"类禁令，会在注册阶段被抽取为 forbidden_patterns 条目（见下文注册表章节）。
10. Risks（风险矩阵）
| Risk | Probability | Impact | Mitigation | |------|------------|--------|-----------|四列风险矩阵，每行一条风险。引擎专家发现的小问题（minor notes）会并入 Risks 区块；阻塞性问题则直接修订 Decision 区块。
11. Performance Implications（性能影响表）
| Metric | Before | Expected After | Budget | |--------|--------|---------------|--------| | CPU (frame time) | [X]ms | [Y]ms | [Z]ms | | Memory | [X]MB | [Y]MB | [Z]MB | | Load Time | [X]s | [Y]s | [Z]s | | Network (if applicable) | [X]KB/s | [Y]KB/s | [Z]KB/s |四行指标（CPU 帧时间、内存、加载时间、可选网络带宽）全部要求Before / Expected After / Budget三列数值。这不仅让决策"可度量"，还直接服务于注册表中的 performance_budgets 条目：ADR 声称的帧时间分配会被/architecture-review求和验证，所有系统预算之和超过总帧预算即判定不可发布。
12. Migration Plan（迁移计划）
## Migration Plan [If this changes existing systems, the step-by-step plan to migrate.] 1. [Step 1 -- what changes, what breaks, how to verify] 2. [Step 2] 3. [Step 3] **Rollback plan**: [How to revert if this decision proves wrong]当决策改动既有系统时，给出编号步骤，每步说明"改什么、破坏什么、如何验证"，并强制给出回滚方案。这是让高风险决策可逆的关键结构。
13. Validation Criteria（验证标准）
## Validation Criteria [How we will know this decision was correct after implementation.] - [ ] [Measurable criterion 1] - [ ] [Measurable criterion 2] - [ ] [Performance criterion]可勾选的验证清单，全部要求可测量。它把"决策是否成功"从主观感受变成上线后可执行的检查项，与 Engine Compatibility 区块的 Verification Required 呼应。
14. GDD Requirements Addressed（GDD 需求回溯）
<!-- This section is MANDATORY. Every ADR must trace back to at least one GDD requirement, or explicitly state it is a foundational decision with no GDD dependency. Traceability is audited by /architecture-review. --> | GDD Document | System | Requirement | How This ADR Satisfies It | |-------------|--------|-------------|--------------------------| | [e.g. `design/gdd/combat.md`] | [e.g. Combat] | [e.g. "Hitbox detection must resolve within 1 frame"] | [e.g. "Jolt physics collision queries run synchronously in _physics_process"] |模板用注释声明此区块MANDATORY（强制）：每份 ADR 要么回溯到至少一条 GDD 需求，要么显式声明"Foundational——无 GDD 依赖"并列出该决策解锁/约束了哪些 GDD 系统。可追溯性由/architecture-review审计。
这里的 Requirement 列对应的正是 技术需求 ID 注册表 docs/architecture/tr-registry.yaml 中登记的技术需求。该注册表为每条 GDD 技术需求分配永久 ID（格式TR-[system-slug]-[NNN]，如TR-combat-001），规则是：ID 永不复用、永不删除，需求改写只更新requirement文本并加revised日期，删除用status: deprecated，拆分用status: superseded-by。Story 通过嵌入 TR-ID 与需求建立引用，/story-done复核时用 ID 查最新需求文本，/story-readiness校验 ID 存在且 active。ADR 中定义的 TR 编号变化会同步回写此注册表。
15. Related（关联链接）
## Related - [Link to related ADRs -- note if supersedes, contradicts, or depends on] - [Link to relevant code files once implemented]【免费下载链接】Claude-Code-Game-StudiosTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.项目地址: https://gitcode.com/GitHub_Trending/cl/Claude-Code-Game-Studios
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
