从已有代码反推设计文档CCGS 项目 /reverse-document 技能的实现规范与验证体系【免费下载链接】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本文以 Claude-Code-Game-StudiosCCGS仓库中 /reverse-document 技能的测试规格 为核心骨架展开。该技能用于从既有源代码中推断设计意图并生成 GDD游戏设计文档骨架或架构概览是棕地brownfield项目接入 CCGS 工作流的关键补课工具。读完本文你将掌握它的输入输出契约、八段式 GDD 骨架结构、COMPLETE/PARTIAL 双裁决机制、协作式写入协议以及仓库如何用五类测试用例对该技能进行系统验证。一、技能定位把已经写出来的代码翻译回设计文档CCGS 项目把整个游戏开发工作室的职能建模为一套 Agent 与 Skill 协作系统仓库 catalog.yaml 中对 72 个技能与 49 个 Agent 进行登记与分类。绝大多数技能遵循设计先行的流水线先写 GDD再拆 Epic/Story再实现代码。而/reverse-document是少数几个逆流而上的工具。正如其在 测试规格 的 Skill Summary 中所定义的/reverse-document从已有源码生成设计或架构文档。它读取指定的源文件从类结构、方法名、常量和注释中推断设计意图并为玩法系统产出 GDD 骨架为技术系统产出架构概览。它解决的是游戏开发中极其常见的现实问题代码已经写了 1200 行、甚至已经跑起来了但设计文档从来不存在。在 reverse 文档化工作流示例 中开发者的原话就是I never wrote a design doc. Can we create one from the implementation?从规格与示例可以归纳出该技能的核心输入输出契约维度约定输入一个或多个源文件路径如src/gameplay/health_system.gd可以是单个文件也可以是互相引用的多个文件推断依据类结构、方法命名、常量尤其是export导出变量、注释与文档字符串输出玩法系统 → GDD 骨架技术/基础设施系统 → 架构概览多文件 → 跨系统架构概览写作前置必须先询问 May I write to [推断路径]?得到用户许可后才落盘裁决COMPLETE推断干净、无歧义或 PARTIAL存在歧义字段需人工复核导演门禁无它是文档工具类技能不触发任何 Director Gate在 WORKFLOW-GUIDE.md 的Reverse Documentation一节docs/WORKFLOW-GUIDE.md#L1321-L1329中给出了它在真实流水线中的典型调用方式/reverse-document src/gameplay/combat/并注明Reads existing code and generates GDD-format design documentation from it.读取已有代码并从中生成 GDD 格式的设计文档。二、输出格式GDD 骨架的八个必需区块规格的测试用例 Case 1 明确规定了当目标是玩法系统时技能必须产出包含8 个必需区块的 GDD 骨架Overview概览系统是什么、解决什么问题Player Fantasy玩家幻想玩家体验层面的设计意图Detailed Rules详细规则系统具体行为规则Formulas公式数值公式例如从代码中推断出的钳制clamping公式Edge Cases边界情况极端输入与异常路径Dependencies依赖对 UI、存档、教程等其他系统的依赖Tuning Knobs可调旋钮可配置数值例如max_health 100这类从export变量推断出的调参项Acceptance Criteria验收标准判定系统完成的客观标准规格给出 Case 1 的测试夹具是一个结构良好的 Godot 健康系统源码export var max_health: int 100func take_damage(amount: int)内含钳制逻辑signal health_changed(new_value: int)所有公开方法都有文档字符串技能对它的期望行为是读取源码 → 识别健康系统 → 推断设计意图最大生命、受伤行为、生命变化信号→ 产出完整 8 区块 GDD 骨架其中Formulas 区块必须包含推断出的钳制公式Tuning Knobs 区块必须标注max_health 100为可配置值最后询问 May I write todesign/gdd/health-system.md?写入后裁决为 COMPLETE。仓库中 reverse 文档化工作流示例 给出了同构的真实会话技能树系统3 棵树 × 5 层 × 45 个技能被反推出包含 Overview、Design Pillars、Detailed Design、Balance Framework、Edge Cases、Dependencies、Acceptance Criteria、Open Questions 的完整文档骨架落盘后标记为[REVERSE-DOCUMENTED FROM IMPLEMENTATION]。三、输出类型的分流GDD、架构概览与跨系统概览规格的 Coverage Notes 明确指出输出类型不是写死的而是由源文件的性质决定玩法逻辑代码如health_system.gd、enemy_ai.gd→ 产出 GDD 骨架引擎/基础设施代码→ 产出架构概览文档格式与 GDD 不同多个互相引用的源文件Case 3→ 产出跨系统架构概览而不是为每个文件各写一份独立文档。Case 3 的夹具是combat_system.gd与damage_resolver.gd两个互相引用的文件combat 调用 damage_resolver。期望行为是技能同时读取两个文件、识别依赖关系、产出描述 Combat System → Damage Resolver 交互、共享接口、两者间数据流 的跨系统概览并询问写入docs/architecture/combat-damage-overview.md注意落盘目录是docs/architecture/而非design/gdd/以对应其技术文档性质。这一按文件数量与性质分流的设计与 session-adopt-brownfield.md 中第 5 步的做法相互印证棕地项目迁移计划建议用/reverse-document与/architecture-decision组合从已有代码中捕获已经做出的架构决策ADRs——即先反推、再固化为正式架构记录。四、裁决机制COMPLETE 与 PARTIAL以及魔法数字处理规格定义了两档裁决核心区别在于推断的干净程度裁决含义处理方式COMPLETE推断干净、无歧义文档正常落盘标注完整PARTIAL部分字段存在歧义需要人工复核文档照常落盘但带 PARTIAL 标记与 AMBIGUOUS VALUE 注解Case 2 展示了最典型的 PARTIAL 触发场景魔法数字magic numbers。夹具是enemy_ai.gd包含内联魔法数字if distance 150:、speed 3.5没有注释、没有文档字符串复杂且不具自解释性的状态机逻辑期望行为是技能检测到无上下文魔法数字 → 在 GDD 骨架中写入注解AMBIGUOUS VALUE: 150 (unknown units — is this pixels, world units, or tiles?)→ 将 Formulas 与 Tuning Knobs 区块标记为需人工复核 → 询问写入design/gdd/enemy-ai.md并附 PARTIAL 提示 →文件仍然写入裁决为 PARTIAL。规格特别强调了这一点File is still written — PARTIAL is not a blocking failure文件仍会写入——PARTIAL 不是阻断性失败。这与 CCGS 系统中门禁类技能如/gate-check的 FAIL 会阻断阶段推进形成鲜明对比反推文档天然带有不确定性与其阻断产出不如把歧义显式标注出来交给人类设计师裁决。五、协作协议写文档前的 May I write 确认整个技能系统共享一条协作式写入协议而/reverse-document是它的严格执行者。规格的 Static Assertions 与 Protocol Compliance 部分都要求技能在创建任何输出文件之前必须询问 May I write to [推断路径]?并附带推断出的目标路径用户批准后才写入结束时应给出下一步交接建议例如用/design-review验证生成的文档。在 reverse 文档化工作流示例 中可以完整看到这条协议的实践Game-Designer Agent 在分析完技能树代码后没有直接写文档而是先抛出 4 个澄清问题设计意图、洗点成本、协同系统意图、平衡哲学待用户回答意图后展示草稿最后才询问 May I write this to design/gdd/skill-system.md?。这个示例展示了比规格更进一步的协作姿态先澄清为什么再反推是什么——设计文档捕获的是代码背后的意图why而不只是代码做了什么what。六、无门禁的设计为何它是纯工具类技能规格的 Director Gate Checks 与 Case 5 都验证了同一个结论/reverse-document不触发任何导演门禁。在 CCGS 的体系中门禁gate用于阶段转换时的正式评审例如 WORKFLOW-GUIDE.md 中/gate-check的 PASS/CONCERNS/FAIL 裁决会控制production/stage.txt的更新。而/reverse-document的定位是文档化工具它的产物设计文档后续会由/design-review等评审技能把关因此自身无需门禁。Case 5 的断言清单写得很明确技能生成并写入设计文档后——不 spawn 任何导演 Agent、输出中不出现任何 gate ID、不出现 gate 跳过消息、裁决仅为 COMPLETE 或 PARTIAL。这也解释了为何它在 catalog.yaml 中被登记为priority: low、category: utility它不处于关键路径上是随取随用的补课工具。七、测试规格的构成五类用例如何验证该技能reverse-document 测试规格 本身遵循 skill-test-spec.md 模板 的结构由 Skill Summary、Static Assertions、Director Gate Checks、Test Cases、Protocol Compliance、Coverage Notes 六部分组成。其中五类测试用例完整覆盖了该技能的正常路径、歧义路径、多文件路径、错误路径与门禁路径用例夹具/输入验证要点期望裁决Case 1结构良好的源码health_system.gd有 export、信号、文档字符串8 区块齐全、钳制公式入 Formulas、max_health 100入 Tuning Knobs、May I write 带推断路径COMPLETECase 2歧义源码enemy_ai.gd魔法数字、无注释AMBIGUOUS VALUE 注解、需复核区块显式标记、文件仍写入PARTIALCase 3多文件互相引用combat_system.gddamage_resolver.gd两份文件合并分析、跨系统依赖被记录、落盘于docs/architecture/COMPLETE 或 PARTIALCase 4源文件不存在inventory_system.gd不存在报错信息带完整路径、建议核对路径或运行/map-systems、不调用写工具、不下裁决错误态无裁决Case 5门禁检查结构良好的源码不 spawn 导演 Agent、无 gate ID、无 gate 跳过消息COMPLETE 或 PARTIAL其中 Case 4 的错误处理契约值得注意当源文件不存在时技能输出Source file not found: src/gameplay/inventory_system.gd报错含完整路径并建议运行/map-systems来定位正确的源文件——把失败转化为通向正确工作流的导航。同时不调用任何写工具、不发布裁决意味着错误态与 PARTIAL 态被严格区分PARTIAL 是产出但标注歧义错误态是根本不产出。八、结构断言与协议合规清单规格的 Static Assertions结构断言定义了该技能文件本身必须满足的元级要求由/skill-test static自动验证、无需夹具frontmatter 必须包含name、description、argument-hint、user-invocable、allowed-tools字段至少包含 2 个阶段标题phase headings包含裁决关键词 COMPLETE、PARTIAL包含 May I write 协作协议用语在写文档之前具备下一步交接建议如用/design-review验证生成的文档。Protocol Compliance协议合规清单则约束运行期行为生成任何内容前先读源文件目标是玩法系统时产出全部 8 个 GDD 区块歧义值用 AMBIGUOUS VALUE 标记多文件时产出跨系统概览而非多份独立文档创建任何输出文件前先问 May I write裁决为 COMPLETE 或 PARTIAL。这些清单与 skill-test.md 描述的验证流程一一对应——/skill-test以 spec 模式读取测试规格文件并逐条断言求值产出逐用例的 PASS/FAIL 表。九、覆盖范围与已知边界规格的 Coverage Notes 诚实地列出了该技能验证未覆盖的边界这些边界对使用者同样有参考价值架构概览与 GDD 的格式差异技术/基础设施系统产出的是架构概览格式而非 GDD 格式推断的输出类型由源文件性质决定玩法逻辑 → GDD引擎/基础设施代码 → 架构文档纯样板代码场景未测试源文件可读但只包含自动生成的样板代码、无实际逻辑时技能很可能产出近乎空白的骨架并给出 PARTIAL 裁决——这是规格明确承认未被测试的情况跨语言一致性C# 与 Blueprint 源文件遵循与 GDScript 相同的推断模式语言差异由技能主体内部处理。这三条边界意味着/reverse-document的产出质量强依赖于源码的可推断性——好的命名、导出变量、文档字符串和注释是获得 COMPLETE 裁决的前提反之魔法数字与无注释代码会触发 PARTIAL 并移交人工复核。这反过来也是一种代码质量信号一个容易被反推的代码库通常也是一个注释与命名良好的代码库。十、在完整流水线中的位置与下一步在 WORKFLOW-GUIDE.md 的技能速查表中docs/WORKFLOW-GUIDE.md#L1478/reverse-document被归入 Reviews and Analysis评审与分析类别适用阶段为Any任意阶段这是它区别于大多数受阶段约束技能的关键属性——无论项目处于设计期还是上线维护期只要有有代码无文档的情况就可以随时补课。它的典型上下游衔接是上游/adopt棕地项目接入识别出代码存在但设计文档缺失的缺口后将/reverse-document作为迁移计划的一步见 session-adopt-brownfield.md 第 5 步或/map-systems帮助定位正确的源文件见 Case 4 的错误处理建议下游/design-review按 8 区块标准验证反推出的 GDD/architecture-review验证架构概览/balance-check校验被反推出的数值曲线对存在歧义的调参项可在确认后更新源码配置并落 TODO工作流示例中即为 tier-5 被动 50% 调至 30% 的 TODO。整套机制形成了一个闭环代码先于文档存在时/reverse-document把实现反向固化为可评审、可检索、可被其他技能引用的设计资产同时通过 COMPLETE/PARTIAL 双裁决与 May I write 协议确保从代码推断的真相与设计师心中的意图在落盘前得到一次人工对齐。延伸阅读仓库内资源/reverse-document 测试规格全文本文核心文档含全部静态断言、五类测试用例与协议合规清单Reverse Documentation Workflow Example技能树系统反推设计文档的完整会话记录展示先澄清意图、再反推实现的协作模式Session: Brownfield Project Onboarding棕地项目接入示例展示/reverse-document在迁移计划中的位置Skill Test Spec 模板本规格所遵循的通用模板解释各组成部分的意图/skill-test 技能规格负责对 skill 规格逐条断言求值、产出 PASS/FAIL 表与裁决的元技能WORKFLOW-GUIDE.md技能速查表与 Reverse Documentation 调用示例定位/reverse-document在流水线中的适用阶段catalog.yamlreverse-document在技能目录中的登记记录priority: lowcategory: utility。【免费下载链接】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），仅供参考