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 StudiosCCGS中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.mdassets/data/**JSON 有效性、命名约定、Schema 规则gameplay-code.mdsrc/gameplay/**数据驱动数值、delta time、无 UI 引用test-standards.mdtests/**测试命名、覆盖率要求、fixture 模式可以看到数据文件规则与代码规则、设计文档规则design-docs.md作用于design/gdd/**共同构成 CCGS 的三层治理体系设计层定义做什么数据层定义数值是什么代码层定义怎么读数据。本规则的作用域assets/data/**是三者之间的承重墙——一旦 JSON 损坏或命名混乱设计文档、代码与运行时数据之间的契约就会断裂。规则的 front matter 声明方式如下摘自>--- paths: - assets/data/** ---该路径声明同时被 validate-assets.sh 钩子脚本读取参考脚本中对应为(^|/)assets/data/.*\.json$的匹配逻辑实现规则声明与机器校验的同一路径口径。二、九大核心规则逐条解读规则一所有 JSON 文件必须是合法 JSONAll 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 21; then PYTHON_CMD$cmd break fi done if [ -n $PYTHON_CMD ]; then if ! $PYTHON_CMD -m json.tool $FILE_PATH /dev/null 21; 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].jsonFile 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 语法错误则是阻断级。这个设计体现了规则文档与钩子实现的分层意图——命名是风格契约语法是生存底线。规则三每个数据文件必须有文档化的 SchemaEvery 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 内键名统一使用 camelCaseUse 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 中的命名与引用规范。【免费下载链接】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），仅供参考