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-StudiosStatus: 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 ScopeStakeholders则来自技能 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]: [Whats there] - [file/path 2]: [Whats there]四个子块的写作纪律Approach Taken必须以(as implemented)为约束——写的是代码里真实存在的方案而不是理想方案Key Implementation Details三条起步聚焦模式与结构如使用观察者模式而非轮询、状态机以显式枚举驱动Clarified Rationale必须来自用户澄清而不是作者的臆测。技能 Phase 8 的协作协议中有铁律Never assume intent. Always ask before documenting why.永远不要假设意图记录为什么之前必须先询问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 3Status 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-001ID 永久有效、永不重编号只允许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]**: [Whats 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考