Claude Code Game Studios 数据文件规范：assets/data 下 JSON 数据资产的结构、命名与校验机制全解析-编程实验室

Claude Code Game Studios 数据文件规范：assets/data 下 JSON 数据资产的结构、命名与校验机制全解析

【免费下载链接】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 Studios（CCGS）中，assets/data/**目录承载着所有可供 AI 代理与游戏引擎共享读取的结构化数据资产（敌人配置、掉落表、经济数值等）。本文围绕仓库中的路径规则文档 .claude/rules/data-files.md 展开，系统讲解数据文件必须遵守的 JSON 有效性、命名模式、Schema 文档化、数值可解释性等九大硬性要求，并结合 .claude/hooks/validate-assets.sh 与 .claude/settings.json 揭示这些规则如何在每次写入后被自动强制校验。读完本文，你将掌握一套可直接套用在自己游戏项目上的数据驱动内容规范，以及用 Claude Code Hooks 实现"规则即自动化"的落地思路。

一、规则定位：数据文件规则是 CCGS 规则体系的组成部分

CCGS 仓库在 .claude/docs/rules-reference.md 中维护了一份"路径即规则"的映射表：每条规则文件通过 YAML front matter 声明其作用路径，Claude Code 会在编辑匹配路径下的文件时自动加载并强制执行对应规则。其中：

规则文件	路径模式	强制内容
data-files.md	`assets/data/**`	JSON 有效性、命名约定、Schema 规则
gameplay-code.md	`src/gameplay/**`	数据驱动数值、delta time、无 UI 引用
test-standards.md	`tests/**`	测试命名、覆盖率要求、fixture 模式

可以看到，数据文件规则与代码规则、设计文档规则（design-docs.md，作用于design/gdd/**）共同构成 CCGS 的三层治理体系：设计层定义"做什么"，数据层定义"数值是什么"，代码层定义"怎么读数据"。本规则的作用域assets/data/**是三者之间的承重墙——一旦 JSON 损坏或命名混乱，设计文档、代码与运行时数据之间的契约就会断裂。

规则的 front matter 声明方式如下（摘自>--- paths: - "assets/data/**" ---

该路径声明同时被 validate-assets.sh 钩子脚本读取参考（脚本中对应为(^|/)assets/data/.*\.json$的匹配逻辑），实现"规则声明"与"机器校验"的同一路径口径。

二、九大核心规则逐条解读

规则一：所有 JSON 文件必须是合法 JSON

All JSON files must be valid JSON — broken JSON blocks the entire build pipeline

这是全部规则中最具"破坏性"的一条：一条格式错误的 JSON 会阻断整个构建管线。原因在于游戏数据资产在运行时被引擎批量加载，任何文件解析失败都会导致加载流程整体中断，而不是优雅跳过。

这在源码层面得到了硬性保证。查看资产校验钩子 validate-assets.sh：

# BLOCKING: Check JSON validity for data files # Invalid JSON will break runtime loading -- this is a build-breaking error if echo "$FILE_PATH" | grep -qE '(^|/)assets/data/.*\.json$'; then if [ -f "$FILE_PATH" ]; then # Find a working Python command PYTHON_CMD="" for cmd in python python3 py; do if command -v "$cmd" >/dev/null 2>&1; then PYTHON_CMD="$cmd" break fi done if [ -n "$PYTHON_CMD" ]; then if ! "$PYTHON_CMD" -m json.tool "$FILE_PATH" > /dev/null 2>&1; then ERRORS="$ERRORS\n FORMAT: $FILE_PATH is not valid JSON — fix syntax errors before continuing" fi fi fi fi

关键实现要点：

校验时机：脚本注册在 .claude/settings.json 的PostToolUse钩子中，matcher为Write|Edit，意味着每一次 AI 代理写入或编辑文件后都会自动触发；
校验工具：优先使用python -m json.tool（依次探测python、python3、py，兼顾 Windows Git Bash 环境），以严格模式解析整个文件；
错误分级：JSON 语法错误被归类为ERRORS（阻断级），脚本最终exit 1，直接在 CI 或编辑会话层面阻止操作继续——这就是"broken JSON blocks the entire build pipeline"的落地形态；
可手动复验：仓库 settings.json 的权限白名单允许执行Bash(python -m json.tool*)，开发者也可在任何时刻手动用该命令验证任意数据文件的合法性。

规则二：文件命名必须遵循`[system]_[name].json`

File naming: lowercase with underscores only, following[system]_[name].jsonpattern

所有数据文件必须全小写、仅使用下划线作为分隔符，并遵循[system]_[name].json的两段式命名：

[system]：所属系统，如combat、economy、loot；
[name]：文件内数据主体，如enemies、goblin_common。

正确的文件名示例：

combat_enemies.json # 战斗系统-敌人配置 loot_goblin_common.json # 掉落系统-哥布林普通掉落表

该约定与 CCGS 的资产命名体系一脉相承：例如资产规格技能 .claude/skills/asset-spec/SKILL.md 中要求的资产命名样例vfx_frost_hit_01.png，同样采用"系统前缀 + 语义名 + 序号"的结构。这种一致性让 AI 代理在跨文件引用资源时（如敌人配置里的lootTable字段指向loot_goblin_common）可以仅凭文件名就推断出所属系统与内容。

校验钩子同样为命名规则提供了机器检查（validate-assets.sh）：

# ADVISORY: Check naming convention (lowercase with underscores only) if echo "$FILENAME" | grep -qE '[A-Z[:space:]-]'; then WARNINGS="$WARNINGS\n NAMING: $FILE_PATH must be lowercase with underscores (got: $FILENAME)" fi

注意这里的分级处理：文件名含大写字母、空格或连字符时，脚本输出WARNINGS（建议级）并打印 "Fix before final commit"，但不阻断写入（exit 0）；而 JSON 语法错误则是阻断级。这个设计体现了规则文档与钩子实现的分层意图——命名是风格契约，语法是生存底线。

规则三：每个数据文件必须有文档化的 Schema

Every data file must have a documented schema (either JSON Schema or documented in the corresponding design doc)

裸的 JSON 对人和 AI 都是不透明的：键名含义、取值类型、范围约束必须显式化。规则给出了两种可接受方案：

JSON Schema 文件：为数据文件配套一份独立的 JSON Schema（如combat_enemies.schema.json），声明字段类型、必填项与取值范围；
在设计文档中记录：在对应的 design/gdd 设计文档中完整说明每个字段的语义与约束。

这与设计文档规则形成闭环——design-docs.md 要求"Formulas must include variable definitions, expected value ranges, and example calculations"（公式必须包含变量定义、预期值域和示例计算）。数据文件里的数值由此总能回溯到设计文档中的原始公式或依据（"Balance values must link to their source formula or rationale"）。

规则四：数值必须附带含义说明

Numeric values must include comments or companion docs explaining what the numbers mean

游戏数值的致命陷阱是"魔法数字"：50可能是血量、也可能是伤害、冷却或价格。规则强制要求两种做法之一：

JSON 内联注释：部分 JSON 解析器/构建工具支持注释（如带注释的 JSONC、或构建期预处理）；
配套说明文档：在对应设计文档或数据说明文档中逐一解释每个数值字段的业务含义、单位与合理取值范围。

推荐在 Schema 或设计文档中这样描述数值字段：

baseHealth: type: number min: 1 description: "哥布林的基础生命值，受 design/gdd/combat.md §4 公式 health = baseHealth * level_multiplier 约束"

规则五：JSON 内键名统一使用 camelCase

Use consistent key naming: camelCase for keys within JSON files

这是与文件命名（snake_case）刻意形成对比的约定：文件名用 snake_case，文件内键名用 camelCase。以规则文档中的正确示例combat_enemies.json为例：

{ "goblin": { "baseHealth": 50, "baseDamage": 8, "moveSpeed": 3.5, "lootTable": "loot_goblin_common" } }

键名baseHealth、baseDamage、moveSpeed、lootTable均为 camelCase，与主流游戏引擎（Godot 的 GDScript 属性、C#/Unity 的属性命名）的惯例一致，可直接映射到运行时类字段，减少数据反序列化时的命名转换成本。同时，一致性保证了 AI 代理在生成或检索数据时行为可预测——camelCase 让跨文件 grep、跨系统复用（如掉落表与敌人配置互引）都更可靠。

规则六：禁止孤儿数据条目

No orphaned data entries — every entry must be referenced by code or another data file

每一条数据都必须有"消费者"——要么被代码引用，要么被另一个数据文件引用。这条规则针对的是游戏项目中最常见的腐烂源头：策划反复调整后遗留的废弃配置。孤儿数据会造成：

维护成本：AI 代理与开发者无法判断某条数据是否仍在生效，不敢清理；
平衡性污染：废弃的高/低数值可能被误用于推导新平衡；
引用断裂：被删除或重命名的条目会让引用方静默失效（因为 JSON 键缺失通常不报错）。

规则给出的检查方法是反向追踪：对每个条目搜索引用（代码中的资源加载路径、其他数据文件中的lootTable、referenced-by等字段），无引用的条目必须删除或在文档中显式标注为"已废弃保留"。CCGS 的资产管线在这一点上有成熟参照：资产规格技能 asset-spec/SKILL.md 中的 Shared Asset Protocol 要求复用既有 ASSET-ID 并维护 manifest 的referenced-by列，正是"每条资产/数据都有明确引用方"的同一治理思想。

规则七：破坏性 Schema 变更必须版本化数据文件

Version data files when making breaking schema changes

当数据文件的 Schema 发生破坏性变更（删除字段、修改键名、改变类型、改变语义）时，不能直接覆盖原文件，而必须对数据文件进行版本化，常见做法：

文件名携带版本：combat_enemies_v2.json；
或文件内声明版本字段："schemaVersion": 2；
或采用迁移文件 + 版本号映射。

版本化的目的是保护运行时兼容性与引用方契约：旧代码/旧存档仍能读取旧版本数据，新版本数据则可并行引入并逐步迁移。这一约定与 CCGS 对引擎 API 的态度一致——仓库 docs/engine-reference 中维护了各引擎的breaking-changes.md与deprecated-apis.md，说明"破坏性变更必须显式追踪"是整个项目的一贯原则。

规则八：所有可选字段必须有合理的默认值

Include sensible defaults for all optional fields

可选字段一旦缺失默认值，就会出现两类问题：其一，消费者代码必须为"字段不存在"写防御逻辑，膨胀代码且易遗漏；其二，AI 代理生成数据时无法确定"没写"到底是"故意留空"还是"忘了填"。规则要求：

每个可选字段在 Schema 中声明default值；
默认值必须"合理"——即真实可用的数值，而非0或null的敷衍占位；
消费方代码按"字段缺失即取默认值"的统一策略读取。

例如移动速度字段如果可选，Schema 应声明"moveSpeed": { "type": "number", "default": 3.0 }，而不是让运行时去猜。

三、正确与错误的完整对照

规则文档给出了正反两组示例，这里逐字段解析其合规性。

正确示例（combat_enemies.json）：

{ "goblin": { "baseHealth": 50, "baseDamage": 8, "moveSpeed": 3.5, "lootTable": "loot_goblin_common" }, "goblin_chief": { "baseHealth": 150, "baseDamage": 20, "moveSpeed": 2.8, "lootTable": "loot_goblin_rare" } }

合规点：文件名符合[system]_[name]小写下划线模式；键名全为 camelCase；数值字段语义清晰（血量/伤害/移速）；lootTable通过字符串引用其他数据文件（loot_goblin_common、loot_goblin_rare），形成可追踪的引用链，满足"无孤儿数据"与"数值有说明"的要求。

错误示例（EnemyData.json）：

{ "Goblin": { "hp": 50 } }

规则文档明确列出三项违规：

文件名违规：EnemyData.json含大写字母，违反"lowercase with underscores only"——会被钩子以 NAMING 警告捕获（validate-assets.sh）；
键名违规：键Goblin首字母大写，违反 camelCase 约定；
结构违规：未遵循[system]_[name]模式，且hp缩写字段缺少必填的配套字段（如伤害、掉落引用），同时缺失 Schema 文档、数值无含义说明，属于多项规则的复合违例。

四、规则的执行机制：从文档到自动化的三级防线

规则文档本身只是文本约束，真正保证"规则被遵守"的是 CCGS 的 Hook 体系。梳理 .claude/settings.json 可以还原完整的执行链路：

第一道防线：路径绑定。规则 front matter 的paths: ["assets/data/**"]让 Claude Code 在代理处理该目录下文件时自动加载规则上下文（对应 rules-reference.md 的机制说明）。

第二道防线：PostToolUse 钩子。每次Write|Edit后，validate-assets.sh 被自动执行（settings.json 中PostToolUse→matcher: "Write|Edit"）。脚本采用 jq 优先、grep 兜底的方式解析工具输入的file_path，并做了 Windows 反斜杠路径归一化以兼容跨平台开发。其分级输出设计非常值得借鉴：

=== Asset Validation: Warnings === NAMING: xxx must be lowercase with underscores ================================== (Warnings are advisory. Fix before final commit.) === Asset Validation: ERRORS (Blocking) === FORMAT: xxx is not valid JSON — fix syntax errors before continuing =========================================== Fix these errors before proceeding.

Warnings（建议级）：命名规范类问题，打印提示、exit 0，不阻断；
ERRORS（阻断级）：JSON 语法错误，输出到 stderr 并exit 1，直接阻断后续操作。

第三道防线：权限与人工复验。settings.json 将python -m json.tool、python -m pytest等加入允许列表，同时禁止rm -rf、git push --force等危险操作，保证校验命令可执行而破坏性操作被拦截；开发者也随时可以用python -m json.tool assets/data/your_file.json手动复验。

五、与测试、设计文档规则的协同

数据文件的正确性最终要靠测试兜底，CCGS 的 test-standards.md 与之形成了互补契约：

测试命名：test_[system]_[scenario]_[expected_result]模式与数据文件[system]_[name].json模式同构，例如test_combat_enemies_goblin_base_health_is_50可以精确锚定到combat_enemies.json中的goblin.baseHealth；
测试数据："Test data must be defined in the test or in dedicated fixtures, never shared mutable state"——数据文件的数值在测试中应作为断言输入而非共享可变状态，这保证了数据变更时测试结果可预期；
回归保障：数据 Schema 变更必须配套回归测试，防止"改一个数值、炸一片系统"。

从设计层看，design-docs.md 要求平衡数值必须链接到其来源公式或依据，这与本规则的"数值必须附带含义说明"直接呼应：设计文档提供公式，数据文件提供实例值，两者互相锚定，任何一侧的漂移都会被另一侧暴露。

六、实战检查清单

将本文规则整合为落地清单，可在每次新增或修改assets/data/**文件时逐项核对：

语法：文件能否通过python -m json.tool <file>严格解析（阻断级，钩子已自动执行）；
文件名：是否为[system]_[name].json，全小写、仅下划线、无空格与连字符；
键名：文件内所有键是否 camelCase 且全文件一致；
Schema：是否有配套 JSON Schema，或在对应 design/gdd 文档中完整记录了每个字段的类型、必填性与范围；
数值：每个数值是否能在 Schema/设计文档中找到业务含义、单位与取值依据；
引用完整性：每个条目是否被代码或其他数据文件引用，lootTable等交叉引用指向的文件是否真实存在；
版本：若发生破坏性 Schema 变更，是否对数据文件进行了版本化并同步迁移逻辑；
默认值：所有可选字段是否声明了合理默认值；
测试：关键数值是否有命名规范的测试断言锚定（参考 test-standards.md）。

七、小结

CCGS 的数据文件规则看似只是九条短句，实则构成了一套完整的数据治理哲学：文件名是导航（让人和 AI 一眼定位），键名是契约（让反序列化零成本），Schema 是文档（让字段可解释），钩子是执行（让规则成为机制而非口号）。而 validate-assets.sh 的分级校验设计——"风格警告不阻断、语法错误必阻断"——为所有将 AI 代理引入内容生产的团队提供了可复制的自动化范式：规则文本负责定义标准，Hook 脚本负责守住底线，设计文档与测试负责提供可追溯的依据。对于任何正在用数据驱动方式组织游戏内容的开发者，这套规范都值得直接移植进自己的项目管线。

进一步阅读：规则总览见 .claude/docs/rules-reference.md，钩子注册配置见 .claude/settings.json，配套的设计文档与测试标准分别见 .claude/rules/design-docs.md 与 .claude/rules/test-standards.md，数据文件的消费端示例可参考资产规格技能 .claude/skills/asset-spec/SKILL.md 中的命名与引用规范。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Claude Code Game Studios 数据文件规范：assets/data 下 JSON 数据资产的结构、命名与校验机制全解析