企业官网建设流程全解析

ADR: [Decision Name]

【免费下载链接】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: Reverse-DocumentedSource:[path to implementation code]Date: [YYYY-MM-DD]Decision Makers: [User name or "inferred from code"]Implementation Status: [Deployed | Partial | Planned]

各字段的填写要点与仓库依据： | 字段 | 填写规则 | 说明 | |------|---------|------| | `Decision Name` | 简短、名词化的决策名，如 `Event-System-Architecture` | 最终写入文件名 `docs/architecture/adr-[NNNN]-[slug].md` 时作为 slug | | `Status` | 固定 `Reverse-Documented` | 与文末 Status Legend 对应；反向文档化是"实现完成后补记"的状态 | | `Source` | 实现代码的完整相对路径 | 溯源的关键字段，必须真实存在，禁止虚构 | | `Date` | 反向文档化的创建日期（YYYY-MM-DD） | 不是决策发生日——决策发生日通常已不可考，这正是反向文档的诚实之处 | | `Decision Makers` | 用户确认的决策人，或"inferred from code" | 若无法确认，如实标注推断，不冒充当事人 | | `Implementation Status` | `Deployed` / `Partial` / `Planned` 三选一 | 决定后续 Follow-Up 清单的紧急程度 | 紧接其后的 `Reverse-Documentation Notice` 是**不可省略的声明块**，它向所有读者（包括未来的 Agent 与审查者）明示本文的生成方式： > **⚠️ Reverse-Documentation Notice** > This Architecture Decision Record was created **after** the implementation already existed. It captures the current implementation approach and clarified rationale based on code analysis and user consultation. Some context may be reconstructed rather than contemporaneously documented. 这一声明在 [reverse-document 技能](https://link.gitcode.com/i/f844abdae4b08032bb36875701ddbe66) 的 Phase 7 中同样被要求以 frontmatter 形式写入： ```markdown --- status: reverse-documented source: [path/] date: [today] verified-by: [User name] ---

并在正文开头附带说明："This document was reverse-engineered from the existing implementation." 可见元信息从模板到技能是一以贯之的。

三、Context 小节：把"代码隐含的问题"显式化

## Context是 ADR 中解释"为什么存在这个决策"的部分，共四个子块：

## Context **Problem Statement**: [What problem did this implementation solve?] **Background** (inferred from code): - [Context 1 — why this problem needed solving] - [Context 2 — constraints at the time] - [Context 3 — alternatives that were likely considered] **System Scope**: [What parts of the codebase does this affect?] **Stakeholders**: - [Role 1]: [Their concern or requirement] - [Role 2]: [Their concern or requirement]

模板特意在Background标注了(inferred from code)——这是因为反向文档中，背景信息主要来自代码结构推断（如注释、命名、调用关系），而非当事人的亲口陈述。

根据 reverse-document 技能 的 Phase 2，分析实现时应提取的信息正好对应这里的填充内容：

• 架构类分析要识别模式（ECS、singleton、observer 等）、理解决策（线程、序列化等）、映射依赖与耦合、评估性能特征、找出约束与权衡——这些分别填入 Problem Statement、Background 与 System Scope；
• Stakeholders则来自技能 Phase 3 的澄清对话：向用户提问"这个资源系统是为了节奏控制还是资源管理"，答案就是相关角色的关切点。

工作流示例 展示了一个典型对照：开发者实现了 1200 行技能树代码但从未写设计文档，Agent 分析后首先呈现 STRUCTURE / MECHANICS / IMPLEMENTATION DETAILS，再提出 4 个意图澄清问题（3 棵树代表什么？洗点成本意图？协同系统是有意为之还是涌现？数值是否失衡）——这些问题的答案，最终就沉淀为 Context 与后续 Decision 的 "Clarified Rationale"。

四、Decision 小节：如实记录"代码里实际采用的方案"

## Decision是 ADR 的核心，模板要求同时记录做了什么与为什么这样做：

## Decision **Approach Taken** (as implemented): [Describe the architectural approach found in the code] **Key Implementation Details**: - [Detail 1]: [How it works] - [Detail 2]: [Pattern or structure used] - [Detail 3]: [Notable design choice] **Clarified Rationale** (from user): - [Reason 1 — why this approach was chosen] - [Reason 2 — what problem it solves] - [Reason 3 — what benefit it provides] **Code Locations**: - `[file/path 1]`: [What's there] - `[file/path 2]`: [What's there]

四个子块的写作纪律：

1. Approach Taken必须以(as implemented)为约束——写的是代码里真实存在的方案，而不是理想方案；
2. Key Implementation Details三条起步，聚焦模式与结构，如"使用观察者模式而非轮询"、"状态机以显式枚举驱动"；
3. Clarified Rationale必须来自用户澄清，而不是作者的臆测。技能 Phase 8 的协作协议中有铁律："Never assume intent. Always ask before documenting 'why'."（永远不要假设意图，记录"为什么"之前必须先询问）；
4. Code Locations给精确到文件的路径，作为该决策的证据锚点。

从仓库的架构治理体系看，这段的产出还会向上游沉淀：新 ADR 中确立的状态所有权、接口契约、性能预算、API 选择与禁止模式，需要按 architecture-decision 技能 的 Step 6 登记到 docs/registry/architecture.yaml 的state_ownership、interfaces、performance_budgets、api_decisions、forbidden_patterns五个分区中，供后续/architecture-review做跨 ADR 冲突校验。

五、Alternatives Considered：用"被放弃的选项"证明决策的严肃性

模板强制要求至少列出三个备选方案（可多可少），其中第三个固定为"维持现状"：

## Alternatives Considered *(These may be inferred or clarified with user)* ### Alternative 1: [Approach Name] **Description**: [What this alternative would have been] **Pros**: - ✅ [Advantage 1] - ✅ [Advantage 2] **Cons**: - ❌ [Disadvantage 1] - ❌ [Disadvantage 2] **Why Not Chosen**: [Reason — from user clarification or inference] ### Alternative 2: [Approach Name] [同构：Description / Pros / Cons / Why Not Chosen] ### Alternative 3: [Status Quo / No Change] **Description**: [What "doing nothing" would mean] **Why Not Acceptable**: [Why the problem needed solving]

三个选项的论证各有分工：

• Alternative 1 / 2：具体的技术路线对比。注意模板对每个Why Not Chosen都标注from user clarification or inference——若未与用户确认，至少要在括号里说明这是推断；
• Alternative 3（Status Quo）：论证"什么都不改"不可接受，这直接呼应 Context 中的 Problem Statement，形成闭环。

在反向文档场景中，备选方案常常不是当时真实讨论过的，而是"从代码推断当时可能考虑过的选项"，因此模板在开头特意注明(These may be inferred or clarified with user)。与 architecture-decision 技能 的 Step 4 相比：正向 ADR 会由技能从引擎参考文档 + GDD 需求推导 2-3 个具体备选再交给用户确认；反向 ADR 则由分析者从代码反推，证据强度不同，读者应知晓这一差异。

六、Consequences：把收益、代价与副作用摊开

## Consequences分为三组，模板要求每组至少三条：

## Consequences ### Positive Consequences (Benefits Realized) ✅ **[Benefit 1]**: [How the implementation provides this] ✅ **[Benefit 2]**: [Impact] ✅ **[Benefit 3]**: [Impact] ### Negative Consequences (Trade-offs Accepted) ⚠️ **[Trade-off 1]**: [What was sacrificed or made harder] ⚠️ **[Trade-off 2]**: [Limitation or cost] ⚠️ **[Trade-off 3]**: [Complexity or maintenance burden] ### Neutral Consequences (Observations) ℹ️ **[Observation 1]**: [Emergent property or side effect] ℹ️ **[Observation 2]**: [Unexpected outcome]

这套"正面/负面/中性"的三分法在 CCGS 的架构治理中被延续到注册表：正面收益对应注册表里登记为state_ownership/interface的契约；负面权衡中明确写出的"禁止模式"（如禁止 Autoload 单例耦合、禁止跨系统直接写状态）会被登记到 architecture.yaml 的forbidden_patterns分区，成为后续 ADR 写作时的硬约束——新决策若与已登记禁令冲突，/architecture-decision会直接弹出冲突警告，要求对齐、显式取代或论证例外。

七、Implementation Notes：下沉到模式、依赖与性能的实现级笔记

## Implementation Notes **Patterns Used**: - [Pattern 1]: [Where and why] - [Pattern 2]: [Where and why] **Dependencies Introduced**: - [Dependency 1]: [Why needed] - [Dependency 2]: [Why needed] **Performance Characteristics**: - Time complexity: [O(n), etc.] - Space complexity: [Memory usage] - Bottlenecks: [Known performance concerns] **Thread Safety**: - [Thread safety approach — single-threaded, mutex-protected, lock-free, etc.] **Testing Strategy**: - [How this is tested — unit tests, integration tests, etc.] - Coverage: [Estimated or measured]

这一节是模板中技术密度最高的部分，也是反向文档区别于"流水账代码描述"的关键：

• Patterns Used要求同时给出"在哪用、为什么用"，让读者能回到代码定位；
• Performance Characteristics的复杂度与瓶颈描述只能来自代码分析与用户澄清——本模板及仓库均未提供任何性能数字，填写时严禁虚构基准数据；
• Thread Safety是游戏引擎场景的常见考点，明确标注单线程/互斥锁/无锁等策略；
• Testing Strategy建议区分单元测试与集成测试。仓库的 技能测试规格 展示了测试如何在 Agent 工作流中落地：例如用health_system.gd夹具断言 GDD 是否包含 8 个必需章节、clamping 公式是否进入 Formulas、max_health = 100是否被记为 Tuning Knob，判定标准是 COMPLETE / PARTIAL 二值结论。

八、Validation：用证据链回答"我们怎么知道它是对的"

## Validation **How We Know This Works**: - ✅ [Evidence 1 — e.g., "6 months in production without issues"] - ✅ [Evidence 2 — e.g., "handles 10k entities at 60 FPS"] - ⚠️ [Evidence 3 — e.g., "works but needs monitoring"] **Known Issues** (discovered during analysis): - ⚠️ [Issue 1]: [Problem and potential fix] - ⚠️ [Issue 2]: [Problem and potential fix] **Risks**: - [Risk 1]: [Potential problem if X happens] - [Risk 2]: [Scalability concern]

模板给出的示例（"线上稳定运行 6 个月"、"60 FPS 下处理 1 万实体"）是填充示例而非仓库事实，写文章或填写 ADR 时必须以实际证据替换。与反向文档最契合的验证手段是：

• 用实现代码中的测试与回归套件作为 Evidence；
• 在 CCGS 的机制中，ADR 的验收状态会被 story-readiness / story-done 技能 通过 tr-registry.yaml 校验——该注册表规定 TR-ID 格式为TR-[system-slug]-[NNN]（如TR-combat-001），ID 永久有效、永不重编号，只允许active / deprecated / superseded-by三种状态，因此反向 ADR 中引用的技术需求 ID 必须与该注册表保持一致，否则 story 会校验失败；
• Known Issues 部分尤其适合反向文档：分析代码时发现的魔法数字、未注释逻辑，模板的姊妹机制（/reverse-document技能测试的 PARTIAL 判定）会要求以AMBIGUOUS VALUE标注，例如"150 (unknown units — is this pixels, world units, or tiles?)"，并显式标记需人工复核的章节。

九、Open Questions 与 Follow-Up Work：承认未知，规划后续

## Open Questions **Unresolved During Reverse-Documentation**: 1. **[Question 1]**: [What's unclear about the decision or implementation?] - Needs clarification from: [Who] - Impact if unresolved: [Consequence] 2. **[Question 2]**: [What needs to be decided for future work?] --- ## Follow-Up Work **Immediate**: - [ ] [Task 1 — e.g., "Add missing unit tests"] - [ ] [Task 2 — e.g., "Document edge case handling"] **Short-Term**: - [ ] [Task 3 — e.g., "Refactor X for clarity"] - [ ] [Task 4 — e.g., "Add performance monitoring"] **Long-Term**: - [ ] [Task 5 — e.g., "Revisit decision when Y is available"]

这两个小节是反向文档"诚实性"的最后防线：

• Open Questions明确列出反向文档化过程中无法解答的问题，并标注需要向谁澄清、不解决会有什么影响——这正是 reverse-document 技能 Phase 8 的行为：写完后主动建议后续步骤（如运行/balance-check、为未覆盖的边界情况补测试），而不是装作一切完备；
• Follow-Up Work按 Immediate / Short-Term / Long-Term 分级，每条都是可勾选的 checkbox，与 工作流示例 中"✅ 写入 + ✅ 标记 REVERSE-DOCUMENTED + ✅ 标记待办"的收尾模式一致——反向文档的终点不是写完，而是驱动后续补全。

十、Related Decisions：挂进决策依赖网络

## Related Decisions **Depends On** (ADRs this builds upon): - [ADR-XXX]: [Related decision] **Influences** (ADRs affected by this): - [ADR-YYY]: [How this impacts it] **Supersedes**: - [ADR-ZZZ]: [Old decision this replaces, if any] **Superseded By**: - [None yet | ADR-WWW if this decision is later replaced]

CCGS 的架构治理对依赖关系有严格要求。architecture-decision 技能 的正向 ADR 模板专门设有## ADR Dependencies表（Depends On / Enables / Blocks / Ordering Note），而反向文档模板则以四个内联字段表达同样的语义。填写时需注意：

• 反向文档的Supersedes/Superseded By同样遵循注册表的"永不删除、只标记取代"原则——见 architecture.yaml 中的规则"Never delete entries — set status: superseded_by: ADR-NNNN instead"；
• 依赖关系若与已登记架构立场冲突，architecture-decision 技能 Step 2 会要求当场解决（对齐 / 显式取代 / 论证例外）后才能继续，反向文档成文后同样应接受/architecture-review的交叉校验。

十一、References、Version History 与 Status Legend：收尾三件套

## References **Code Locations**: - `[path/file 1]`: [Primary implementation] - `[path/file 2]`: [Related code] **External Resources**: - [Article/Book]: [Relevant pattern or technique reference] - [Documentation]: [Engine or library docs consulted] **Design Documents**: - [GDD Section]: [If this implements a design] --- ## Version History | Date | Author | Changes | |------|--------|---------| | [Date] | Claude (reverse-doc) | Initial reverse-documentation from `[source path]` | | [Date] | [User] | Clarified rationale for [X] | --- ## Status Legend - **Proposed**: Under discussion, not implemented - **Accepted**: Decided, implementation in progress - **Deprecated**: No longer recommended, but may exist in code - **Superseded**: Replaced by another decision - **Reverse-Documented**: Created after implementation (this document)

• References的 Code Locations 必须与头部Source一致并指向真实文件；External Resources 仅记录实际参考过的资料，不可杜撰外部链接；
• Version History的首行作者固定为Claude (reverse-doc)，与模板页脚的生成签名"This ADR was generated by/reverse-document architecture [path]"相互印证；
• Status Legend定义了 CCGS 中 ADR 的全部生命周期状态，本文模板对应的状态是五种之一：Reverse-Documented（实现之后补记）。文末的**Current Status**: **Reverse-Documented**字段再次收束确认。

十二、Appendix：用代码片段把决策"钉死"

## Appendix: Code Snippets **Key Implementation Pattern**: ```[language] [Code snippet showing the core pattern or decision]

Rationale: [Why this code structure embodies the decision]

Alternative Approach(not chosen):

[Code snippet showing what the alternative would look like]

Why Not: [Why the implemented approach was preferred]

【免费下载链接】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