Cocos 游戏项目的 Claude Code 配置实践(2)：CLAUDE.md

朋友们大家好，我是 bit老宫 呀，一个拥有12年一线开发经验的CocosCreator游戏开发者，代表作 《比特小队》 《宫爆老奶奶家族篇》

系列文章目录：总览 → [CLAUDE.md] → Rules → Skills → MCP → Hooks → Agents

上一篇聊了为什么游戏开发需要深度定制 Claude Code。这篇从最基础也最重要的一层开始聊：CLAUDE.md。

它是什么

CLAUDE.md 是一个放在项目根目录的 Markdown 文件。每次 Claude Code 启动时自动读取，相当于 AI 永久记住的项目背景。你不用每次对话都重新解释「我用的是 Cocos 3.8.8」「UI用FairyGUI」「核心战斗部分使用ECS架构」——写一次，永久生效。

你可以把它理解为给 AI 写的「入职手册」。新员工入职第一天会收到一份项目文档，告诉他项目用什么技术栈、遵循什么规范、有哪些约定。CLAUDE.md 干的就是这件事。

游戏项目里写什么

经过大半年的迭代，我目前觉得三类内容最关键，分享一下我的做法。

一、引擎版本约束

这是最容易被忽略、却最重要的一条。

AI 的训练数据混杂了各版本的 API。Cocos Creator 经历了 2.x 到 3.x 的大版本跨越，API 变化巨大。不明确告诉 AI 你用哪个版本，它很可能写出这样的代码：

// 错误：Cocos 2.x 的写法，3.8.8 里早就不存在了
cc.loader.loadRes("hero", cc.SpriteFrame, (err, asset) => { ... });

// 正确：Cocos 3.x 的写法
resources.load("hero", SpriteFrame, (err, asset) => { ... });

所以我的 CLAUDE.md 里第一条就是：

## 项目概述
基于 Cocos Creator 3.8.8 的 2D 射击游戏，使用 [bit-framework](https://github.com/gongxh0901/bit-framework) 框架开发。
核心架构：ECS（实体组件系统）处理游戏战斗逻辑 + FGUI（FairyGUI）构建 UI 界面。
- 严格使用 Cocos Creator 3.8.8 API
- 禁止使用废弃 API：cc.loader、cc.Class、cc.director.getScheduler 旧写法

短短三行，效果立竿见影。加上之后，AI 再也没写出过废弃 API。

二、框架模块映射表

游戏项目往往有自己的框架层。我用的是自研的 bit-framework，包含 UI 管理、ECS 架构、事件通信、资源加载等模块。这些东西 Claude 的训练数据里压根没有。

不告诉它你封装了什么，AI 就会「自由发挥」——自己发明一套事件系统、自己写一个资源管理器，和你项目里的代码完全对不上。

解决方案是一张映射表：

框架模块

| 需求 | 使用模块 | 规则文件 | |———|———|———| | UI 窗口 | bit-ui → Window 基类 + @uiclass 装饰器 | .claude/rules/ui-module.md | | FGUI 工作流 | FairyGUI 节点结构读取和代码生成 | .claude/rules/fgui-workflow.md | | ECS 工作流 | 组件/系统开发流程 | .claude/rules/ecs-workflow.md | | 事件通信 | bit-event → GlobalEvent | .claude/rules/event-module.md | | 定时器/平台 | bit-core → GlobalTimer / Platform / Screen | .claude/rules/core-module.md | | 资源加载 | bit-assets → AssetLoader / AssetPool | .claude/rules/assets-module.md | | 网络请求 | bit-net → HttpManager / Socket | .claude/rules/net-module.md | | 行为树AI | bit-behaviortree → BehaviorTree | .claude/rules/behaviortree-module.md | | 碰撞检测 | bit-quadtree → QuadTree | .claude/rules/quadtree-module.md |

这张表的价值不只是告诉 AI 「有哪些模块」，更重要的是第三列——指向对应的 Rules 文件。AI 知道写 ECS 代码时去读 ecs-workflow.md，写 UI 时去读 ui-module.md，不用你每次提醒。

三、工作流约束和代码规范

这部分告诉 AI「怎么干活」。我的项目里有几条核心约束：

## 代码规范
- 禁止跨模块直接调用，事件通信必须通过 GlobalEvent
- 禁止 `any` 类型，必须定义明确类型
- UI 窗口必须继承 Window 基类，使用 @uiclass 装饰器注册
- 新建窗口/组件/系统时，使用对应的 Skill 命令

## 工作流执行标准
处理任何中大型需求时，强制遵循以下步骤：
1. Plan (计划): 输出修改文件列表和核心思路
2. Wait (等待): 询问用户确认
3. Execute (执行): 获得批准后执行

工作流约束尤其重要。不加这条，AI 接到需求就直接开写，写完你发现思路不对，改起来代价更大。强制它「先计划后执行」，相当于给每个任务加了一道 code review。

四、项目关键路径

最后别忘了告诉 AI 项目的目录结构：

项目关键路径

| 路径 | 说明 | |——|——| | assets/script/ | 游戏脚本代码 | | assets/script/header.ts | 统一导出：ASSETS, CORE, ecs, FGUI, QT, UI | | assets/script/ecs/ | ECS 组件和系统 | | FguiCreator3.8/assets/ | FGUI 工程（按包分目录，含 XML 节点定义） | | extensions-config/entity/ | 实体配置 JSON |

这张表让 AI 知道代码在哪、配置在哪、FGUI 工程在哪——不用每次都 ls 半天找文件。

效果对比

配置前的对话：

我：帮我写一个加载英雄资源的函数 AI：好的，我来用 cc.loader 加载…… 我：不对，我们用的是 3.8.8 AI：抱歉，用 resources.load…… 我：不对，我们项目有 AssetLoader AI：请问 AssetLoader 的 API 是什么样的？ 我：（贴一大段文档……）

配置后的对话：

我：帮我写一个加载英雄资源的函数 AI：（直接用 AssetLoader，API 正确，代码规范符合项目约定）

从「每次解释 10 分钟」到「一句话搞定」，这就是 CLAUDE.md 的价值。

常见误区

误区一：写太多

CLAUDE.md 不是百科全书。我见过有人把整个框架的 API 文档都贴进去，结果文件几千行，AI 反而因为信息过载表现更差。CLAUDE.md 应该只写「全局性」的规范和约定，细分领域的规则拆到 Rules 里（下一篇详细讲）。

误区二：写太少

只写一行「使用 Cocos Creator 3.8.8」远远不够。引擎版本只是最基础的约束，框架模块、代码规范、目录结构这些信息 AI 同样需要。

误区三：写完不维护

项目在演进，CLAUDE.md 也要跟着更新。新增了一个框架模块、改了目录结构、加了新的 Skill——及时同步到 CLAUDE.md 里。过期的信息比没有信息更糟糕。

CLAUDE.MD

控制在 50-100 行以内，超过这个范围就该考虑把一些内容拆到 Rules 文件里 或者 精简描述

可以使用 /context 命令查看 Claude Code 当前的上下文

下一篇

CLAUDE.md 解决了「AI 不懂项目」的问题，但随着规范越写越多，一个文件装不下了。下一篇聊 Rules——按文件路径动态注入规则，让 AI 在不同场景自动加载不同的规范。