企业官网建设流程全解析

Claude-Code-Game-Studios 的 /consistency-check 技能实战指南：跨 GDD 一致性扫描、冲突分类与验收测试全解析

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

导读：/consistency-check是 Claude Code Game Studios（CCGS）框架中负责"体检"的分析类技能，它扫描design/gdd/下所有 Game Design Document（GDD），检测文档之间的内部冲突，并以结构化发现表输出冲突类型与严重级别。本文以 consistency-check 技能测试规格 为骨架，结合 CCGS 技能测试框架的目录规范、质量评分卡与实体注册表，完整讲解该技能的工作协议、三种判定结论、四类冲突识别、五条验收测试用例及其与实体注册表的联动机制，帮助你理解如何在多系统设计中自动发现公式矛盾、所有权冲突与依赖断裂。

一、技能定位：它是 CCGS 设计流程中的"机械一致性扫描器"

在 CCGS 框架中，/consistency-check属于 analysis 类别技能，与balance-check、code-review、tech-debt、scope-check、asset-audit等并列。它的唯一输入是design/gdd/目录下的一组系统 GDD 文档，输出是一张结构化的发现表（findings table）与一个判定结论。

其核心工作模型可以用一句话概括：只读扫描、机械比对、不自动修复。规格文档（Skill Summary）明确声明：

• 扫描所有 GDD 并检查文档之间的内部冲突（internal conflicts across documents）；
• 产出结构化的发现表，列为System A vs System B、Conflict Type、Severity（HIGH / MEDIUM / LOW）；
• 冲突类型包括：formula mismatch（公式不匹配）、competing ownership（所有权竞争）、stale reference（过期引用）、dependency gap（依赖缺口）；
• 分析阶段全程只读，不挂任何导演门禁（director gates）；
• 只有在用户主动要求时，才可选地将一致性报告写入design/consistency-report-[date].md，且写文件前必须先问 "May I write"。

这条技能与review-all-gdds（深度设计理论分析，如支柱漂移、主导策略）的边界在 Coverage Notes 中划得很清楚：/consistency-check只做结构一致性检查，不做设计理论评判。

二、四种冲突类型与严重级别语义

规格中定义了四类需要识别的冲突，每一类对应一种设计文档间的失配模式：

值得强调的是严重级别的判定依据在技能正文中定义（规格 Coverage Notes 指出"conflict severity rubric (HIGH / MEDIUM / LOW) is defined in the skill body and not re-enumerated here"），而直接公式矛盾被固定视为 HIGH——例如同一实体在两个文档中分别使用damage = attack * 1.5与damage = attack * 2.0，这就是需要立即裁决的硬冲突。

从实现角度，/consistency-check的检测能力依赖 GDD 之间使用一致的公式记号。规格在 Coverage Notes 中明确警告：如果同一机制只是被不同文档用非正式文字描述（informal descriptions），检测可能漏报。这也是它与 design/registry/entities.yaml 实体注册表深度联动的原因——注册表强制要求跨文档出现的命名事实以统一格式登记，为 grep 式的机械比对提供可靠基础。

三、判定结论词汇表：三种互斥的 Verdict

规格要求技能输出且只能输出以下三种判定之一（Protocol Compliance 原文："Verdict is one of exactly: CONSISTENT, CONFLICTS FOUND, DEPENDENCY GAP"）：

三种判定互斥且优先级明确：DEPENDENCY GAP既不是CONSISTENT也不是CONFLICTS FOUND——当 GDD-A 引用了不存在的 system-B 时，即使其余 GDD 全部一致，结论也必须是DEPENDENCY GAP（见 Case 3）。

除三种判定外，还存在一个非判定路径：当design/gdd/目录为空或不存在时，技能不产出发现表、不给出任何 verdict，而是输出错误信息（见第五节 Case 4）。

四、分析协议与写文件边界：只读 + "May I write"

4.1 分析阶段全程只读

技能测试框架的 quality-rubric.md 为 analysis 类别定义了四条 PASS/FAIL 指标，/consistency-check必须全部满足：

• AN1 — Read-only scan：分析阶段只使用 Read / Glob / Grep 工具，扫描过程中不得使用 Write 或 Edit；
• AN2 — Structured findings table：输出必须是发现表或清单（不能只有散文），且每条发现带严重级别；
• AN3 — No auto-write：任何建议的文件写入（如一致性报告）都必须由 "May I write" 门禁把关；
• AN4 — No director gates during analysis：分析技能不得挂导演门禁，只产出供人类评审的发现。

4.2 可选报告的写入流程

规格明确："An optional consistency report can be written todesign/consistency-report-[date].mdif the user requests it, but the skill asks 'May I write' before doing so."即：

1. 完整展示发现表（findings table shown in full before any write ask）；
2. 询问 "May I write" 获得用户批准；
3. 批准后才写入design/consistency-report-[date].md。

4.3 不读取 review-mode、不挂门禁

规格 Director Gate Checks 一节声明该技能无导演门禁：一致性检查是机械扫描（mechanical scan），扫描本身不需要创意/技术导演评审。Case 5 进一步验证：即使production/session-state/review-mode.txt存在且内容为full，技能也不得读取该文件，不派生任何 CD-、TD-、PR-、AD- 前缀的门禁代理，输出中不得出现 "Gate: [GATE-ID]" 或 gate-skipped 条目——评审模式对该技能的行为完全无影响。

五、五条验收测试用例详解

规格以行为规格（behavioral spec）形式给出了五条测试用例，每条包含 Fixture（项目状态前提）、Input、Expected behavior 与可勾选断言。这正是 templates/skill-test-spec.md 模板的五个用例范式（Happy Path / Failure / Mode Variant / Edge Case / Director Gate）在 analysis 类别上的具体化。

Case 1：Happy Path —— 4 个无冲突 GDD

Fixture：design/gdd/恰好包含 4 个系统 GDD；所有公式一致（无同一变量不同取值）；没有任何两个 GDD 声称拥有同一实体/机制；所有依赖引用都能指向存在的 GDD。

Expected behavior：技能读取全部 4 个 GDD → 执行跨 GDD 一致性检查（公式、所有权、引用）→ 未发现冲突 → 输出包含 0 个问题的结构化发现表 → 判定CONSISTENT。

关键断言：

• 产出结论前必须读完全部 4 个 GDD；
• 发现表必须存在（即使为空，也要显示 "No conflicts found"）；
• 无冲突时判定为 CONSISTENT；
• 未经用户批准不得写任何文件；
• 结尾必须有下一步交接（next-step handoff）。

Case 2：Failure Path —— 两个 GDD 伤害公式冲突

Fixture：GDD-A 定义damage = attack * 1.5；GDD-B 对同一实体类型定义damage = attack * 2.0；两文档都引用同一个attack变量。

Expected behavior：技能读取全部 GDD 并检测到公式不匹配 → 发现表出现条目GDD-A vs GDD-B | Formula Mismatch | HIGH→ 表中展示具体的冲突公式（不能只说"存在公式冲突"）→ 判定CONFLICTS FOUND。

关键断言：

• 判定必须是 CONFLICTS FOUND 而非 CONSISTENT；
• 冲突条目必须点名两个 GDD 的文件名；
• 冲突类型标注为 Formula Mismatch；
• 直接公式矛盾严重级别为 HIGH；
• 两个冲突公式都要在表中展示；
• 技能不得自动解决冲突（no auto-resolve）。

Case 3：Partial Path —— GDD 引用了不存在的系统

Fixture：GDD-A 的 Dependencies 段声明依赖 "system-B"；design/gdd/下不存在 system-B 的 GDD；其余 GDD 全部一致。

Expected behavior：技能读取全部 GDD 并检查依赖引用 → GDD-A 对 system-B 的引用无法解析 → 发现表出现GDD-A vs (missing) | Dependency Gap | MEDIUM→ 判定DEPENDENCY GAP。

关键断言：

• 判定必须是 DEPENDENCY GAP，区别于 CONSISTENT 与 CONFLICTS FOUND；
• 条目同时点名 GDD-A 与缺失的 system-B；
• 未解析的依赖引用严重级别为 MEDIUM；
• 技能必须建议运行/design-system system-B来补齐缺失的 GDD（这正是该技能结尾 next-step handoff 的标准形态之一）。

Case 4：Edge Case —— 没有任何 GDD

Fixture：design/gdd/为空目录或不存在。

Expected behavior：技能尝试读取design/gdd/下的文件 → 未找到任何 GDD → 输出错误："No GDDs found indesign/gdd/. Run/design-systemto create GDDs first." → 不产出发现表 → 不给出任何 verdict。

关键断言：

• 必须输出清晰的错误信息；
• 不产出任何 verdict（CONSISTENT / CONFLICTS FOUND / DEPENDENCY GAP 均不出现）；
• 推荐正确的下一步动作（/design-system）；
• 不得崩溃，也不得产出残缺报告（no crash or partial report）。

Case 5：Director Gate —— 无门禁、不读 review-mode

Fixture：design/gdd/含 ≥2 个 GDD；production/session-state/review-mode.txt存在且内容为full。

Expected behavior：技能读取全部 GDD 并正常执行一致性扫描 → 不读取 review-mode.txt → 全程不派生任何导演门禁代理 → 正常产出发现表与判定。

关键断言：

• 不派生任何导演门禁代理（无 CD-、TD-、PR-、AD- 前缀门禁）；
• 不读取production/session-state/review-mode.txt；
• 输出不含 "Gate: [GATE-ID]" 或 gate-skipped 条目；
• 评审模式对该技能行为无影响。

六、静态断言：结构性合规检查

规格的 Static Assertions 一节给出了无需 fixture、可由/skill-test static自动验证的六项结构性要求：

• 具备必需 frontmatter 字段：name、description、argument-hint、user-invocable、allowed-tools；
• 具备 ≥2 个阶段标题；
• 包含判定关键词：CONSISTENT、CONFLICTS FOUND、DEPENDENCY GAP；
• 分析阶段不要求"May I write" 语言（只读扫描）；
• 结尾有下一步交接；
• 明确说明报告写入是可选的且需批准。

这些断言通过 CCGS Skill Testing Framework/README.md 中的命令执行验证：/skill-test static consistency-check（单技能 7 项检查）或/skill-test static all（全部 72 个技能）。在 catalog.yaml 中，consistency-check的spec字段指向本文所对应的规格文件，用于覆盖度追踪。

七、与实体注册表的联动：grep-first、GDD-second

/consistency-check并非孤立运行。在 design/registry/entities.yaml 的文件头注释中，明确写明了技能之间的读写关系：

• WRITTEN BY：/design-system（Phase 5，GDD 各节批准后）以及/consistency-check（解决冲突时）；
• READ BY：/design-system（Phase 2 与 Section C/D 写入后的冲突检查）、/consistency-check（primary input —— grep-first, GDD-second）、/review-all-gdds（Phase 1 基线）、/architecture-review（数据结构与接口校验）。

"grep-first, GDD-second" 是关键检索策略：技能先对entities.yaml执行精确 Grep 匹配（如Grep pattern="^ - name:" path="design/registry/entities.yaml"列出全部实体名、Grep pattern="source: design/gdd/combat.md"查看某个 GDD 拥有哪些事实），命中后再回到对应 GDD 全文核对。注册表本身约束了跨文档命名事实的登记规则：

• 只登记跨越系统边界的事实，单个 GDD 内部使用的公式无需登记；
• 永不删除条目，改用status: deprecated；
• 值变更时必须更新revised:日期并注释旧值与变更来源 GDD；
• source:指向"拥有"该事实的权威 GDD，其他引用它的 GDD 在referenced_by中列出自身路径；
• 新 GDD 引用已有条目时追加到referenced_by，禁止创建重复条目。

这套规则从作者侧降低了不一致产生的概率，而/consistency-check则在评审侧兜底扫描——二者共同构成 CCGS 设计一致性的双层防线。

八、协议合规清单与边界说明

规格 Protocol Compliance 一节汇总了最终验收清单：

• 产出发现表前读完所有 GDD；
• 请求写报告前完整展示发现表；
• 判定严格限定为 CONSISTENT / CONFLICTS FOUND / DEPENDENCY GAP 三者之一；
• 无导演门禁、不读 review-mode.txt；
• 报告写入（如被请求）由 "May I write" 批准把关；
• 以与判定匹配的下一步交接收尾。

Coverage Notes 提示的能力边界（引用时务必如实告知用户）：

1. 该技能只做 GDD 之间的结构一致性检查，支柱漂移、主导策略等深层设计理论分析归/review-all-gdds处理；
2. 公式冲突检测依赖 GDD 间一致的公式记号，非正式文字描述可能漏检；
3. 严重级别评分细则（HIGH / MEDIUM / LOW）定义在技能正文中，规格文件不再重复枚举。

该技能在 UPGRADING.md 中也被登记为框架新增技能之一（"/consistency-check— cross-GDD entity consistency scanner"），其行为规格位于CCGS Skill Testing Framework/skills/analysis/consistency-check.md，可直接用/skill-test spec consistency-check按上述五条用例做行为级验收，或用/skill-test category consistency-check对照 analysis 类别的 AN1–AN4 指标逐项评分。

结语

/consistency-check用一套极简但完备的协议解决了多系统设计文档最常见的质量问题：公式矛盾、所有权竞争、过期引用与依赖缺口。它的价值不在于"发现多少问题"，而在于以机械、可复现、可验收的方式把一致性检查固化进框架：只读扫描守住数据安全边界，三种互斥判定让结论无歧义，五条测试用例让行为可回归，实体注册表让比对从模糊的自然语言上升到精确的 grep 事实层。对任何使用 CCGS 框架管理复杂系统设计的团队而言，在每次大规模设计变更后运行/consistency-check，都是最廉价、最可靠的"设计健康体检"。

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