用 AI 生成 Cocos 场景说明文档：让代码助手真正理解你的游戏

你让 Claude 写一个新组件，它生成的代码引用了不存在的节点名。你让 Cursor 添加一个功能，它不知道你已经有现成的预制体可以复用。每次解释完项目结构，过两天又得重新说一遍。

说实话，我用 AI 辅助开发游戏的时候，这种事儿太常见了。AI 写普通 Web 项目还挺溜，一到 Cocos Creator 就各种”不对劲”。不是它笨，是它压根看不见你的场景层级、节点结构、组件配置。

这背后有个根本问题：AI 和游戏引擎是两套独立的工具。AI 只能读代码文件，但 Cocos 的核心内容都在场景文件里，那些 .scene 和 .prefab 的 JSON 结构，AI 根本没法直接理解。

这篇文章我会分享一个实用的解决方案：用 CLAUDE.md 文件 + 场景说明文档，让 AI 真正理解你的游戏项目。还会给出一套可复制的 Prompt 模板，你照着用就能生成自己的场景文档。

1. 为什么 AI 无法理解你的游戏项目

1.1 AI 与引擎的”隔离墙”问题

Summer Engine 有一篇博客讲得很透：AI 和引擎是分离的工具。AI 对场景层级、现有脚本、项目结构完全没感知。你让它写代码，它只能基于你给的上下文推断。问题是你给的上下文往往不够。

这跟 Web 开发不一样。Web 项目的代码结构基本都在文件里，AI 读一遍就能理解。游戏项目呢？大量关键信息藏在编辑器里——场景层级、节点位置、组件参数，这些都不是代码文件能表达的内容。

1.2 Cocos Creator 项目的特殊性

Cocos Creator 的场景（Scene）是逻辑组织结构，不是代码文件。你打开一个 .scene 文件，看到的可能是一堆 JSON，但 AI 不会去解析这玩意儿。节点层级（Hierarchy）是你在编辑器里拖拽出来的产物，预制体（Prefab）更特殊，它本质是个资源文件。

这就导致一个很尴尬的局面：你问 AI”帮我修改 GameRoot 下面的 ScoreLabel”，AI 根本不知道 GameRoot 是什么，ScoreLabel 又在哪个节点上。你得手动把整个场景结构描述一遍，累死。

1.3 现有方案的局限

CLAUDE.md 文件是个思路，但需要手动写，维护成本高。每次改场景结构都得同步更新，不然信息就过时了。MCP Server 方案门槛更高，需要额外开发 WebSocket 服务，配置一堆东西。Unity 有 Bezi 这种实时索引工具，能自动把脚本、资源、场景都喂给 AI，但 Cocos 暂时没有类似的东西。

所以最现实的方案还是文档化——把 AI 看不见的东西写下来，让它能读。

2. CLAUDE.md 文件：让 AI 记住你的项目

2.1 什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 的项目级上下文文件，放在项目根目录。类似的还有 Cursor 的 .cursorrules、GitHub Copilot 的 .github/copilot-instructions.md。作用很简单：给 AI 提供它无法从代码推断的上下文。

比如你有个组件叫 ScoreManager，AI 读代码能知道它干什么。但 AI 不知道这个组件挂载在哪个节点上，跟哪些节点有交互。这些信息就是 CLAUDE.md 要写的。

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

2.2 游戏项目的 CLAUDE.md 应该写什么

Mr. Phil Games 的博客建议写这几类信息：

项目基本信息：引擎版本、目标平台、游戏类型。这能让 AI 知道你用的是 Cocos 3.8 还是 2.x，是微信小游戏还是 App。

场景结构概述：Boot 场景、Game 场景、结算页分别干什么。AI 知道这个才能理解你说的”在 Boot 场景加载资源”是什么意思。

核心节点命名规范：Canvas、GameRoot、UIRoot 这些顶级节点。AI 生成代码时会自动用这些名称。

组件清单：已实现的核心组件及其职责。避免 AI 重复发明轮子。

2.3 Cocos Creator 项目 CLAUDE.md 示例

这是我一个休闲小游戏项目的 CLAUDE.md，你可以参考：

# 项目上下文 - 小游戏 Demo

## 基本信息
- 引擎：Cocos Creator 3.8
- 类型：休闲小游戏
- 平台：微信小游戏

## 场景结构
- Boot.scene：启动加载场景，挂载 GameManager
- Game.scene：主游戏场景，包含 GameRoot + UIRoot
- Result.scene：结算页，显示分数和按钮

## 核心节点
- Canvas：UI 根节点
- GameRoot：游戏内容节点，挂载 GameLogic 组件
- UIRoot：UI 层节点，包含 ScoreLabel、PauseButton

## 已实现组件
- GameManager：游戏生命周期管理
- ScoreManager：分数计算与存储
- AudioManager：音效播放

## 代码规范
- 所有 UI 节点放在 Canvas 下
- 游戏逻辑节点放在 GameRoot 下
- 组件命名用 Manager 结尾表示管理类

有了这个文件，AI 就不会再问你”GameManager 是什么”、“GameRoot 在哪里”了。

3. 场景说明文档：自动生成的实践方法

3.1 为什么需要场景说明文档

CLAUDE.md 是项目级概览，不够细。每个场景的节点层级、组件配置需要单独文档化。让 AI 知道”这个场景有什么节点，每个节点挂载什么组件”。

我之前踩过一个坑：让 AI 写个暂停功能，它生成的代码去查找 PauseButton 节点。但我这个节点其实在 UIRoot/PauseLayer/PauseButton，层级差了两层。AI 不知道，我也忘了说，结果代码跑起来报错。

场景文档就是为了避免这种事儿。把每个场景的结构写清楚，AI 查代码时就能准确定位。

3.2 用 Prompt 自动生成场景文档

手动写文档太累，我用 AI 来生成。下面是 Prompt 模板，你可以直接复制用：

我有一个 Cocos Creator 3.8 的游戏项目，请帮我生成场景说明文档。

项目信息：
- 游戏类型：休闲小游戏
- 引擎版本：Cocos Creator 3.8

请根据以下信息生成文档：
1. 场景名称：{scene_name}
2. 场景用途：{scene_purpose}
3. 主要节点层级（请描述）：
   - {node_structure}

输出格式要求：
- 场景概述（一句话说明场景用途）
- 节点层级树（用树形结构展示，标注组件）
- 组件职责说明（每个组件干什么）
- 代码引用注意事项（容易踩坑的地方）

使用时把 {scene_name}、{scene_purpose}、{node_structure} 替换成你的实际内容就行。

3.3 实战示例：生成 Game.scene 文档

我用这个 Prompt 生成了一个 Game.scene 的文档。输入如下：

1. 场景名称：Game.scene
2. 场景用途：主游戏场景，包含游戏逻辑层和 UI 层
3. 主要节点层级：
   - Canvas（UI根节点）
     - UIRoot（UI层容器）
       - ScoreLabel（分数显示，挂载 Label 组件）
       - PauseButton（暂停按钮，挂载 Button 组件）
   - GameRoot（游戏逻辑层）
     - PlayerNode（玩家角色，挂载 PlayerController）
     - EnemyRoot（敌人容器）

AI 输出的文档：

# Game.scene 场景说明文档

## 场景概述
主游戏场景，承载游戏核心逻辑与 UI 展示。

## 节点层级树
Canvas (UI根节点)
├── UIRoot (UI层容器)
│   ├── ScoreLabel [Label] - 分数显示
│   └── PauseButton [Button] - 暂停按钮
└── GameRoot (游戏逻辑层)
    ├── PlayerNode [PlayerController] - 玩家角色
    └── EnemyRoot - 敌人容器

## 组件职责说明
| 组件 | 挂载节点 | 职责 |
|------|---------|------|
| PlayerController | PlayerNode | 处理玩家输入、移动逻辑 |
| Label | ScoreLabel | 显示分数文本 |
| Button | PauseButton | 暂停按钮交互 |

## 代码引用注意事项
1. 查找 UI 节点要从 Canvas 开始：`this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel 在 UIRoot 下，不是直接在 Canvas 下
3. PlayerNode 在 GameRoot 下，跟 Canvas 是同级关系

这个文档放在项目的 docs/ 目录，CLAUDE.md 里加一行引用：详细场景结构见 docs/Game.scene.md。

3.4 文档更新与维护策略

文档写完不是一劳永逸。场景结构变了，文档也得跟着改。我目前的做法是：

每次改完场景结构，顺手更新文档。大概 5 分钟的事，比重新解释给 AI 省事多了。

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

有些团队把文档生成加到 CI/CD 流程里，自动触发。但我觉得对于小团队，手动更新更实际——毕竟场景结构不会天天大改。

4. MCP Server 方案：让 AI 直接与引擎交互

4.1 什么是 MCP Server

MCP（Model Context Protocol）是一种协议，让 AI 通过 JSON-RPC 接口跟外部工具交互。Skywork AI 做了一个 Cocos Creator MCP Server，AI 可以直接跟编辑器通信。

说白了就是：AI 不用你手动告诉它场景结构，它可以自己去问编辑器。

4.2 MCP Server 能做什么

根据 Skywork AI 的博客，Cocos MCP Server 支持这些功能：

• AI 通过工具调用获取场景信息
• AI 直接在编辑器中创建节点
• AI 读取预制体内容
• AI 查询组件配置

这比 CLAUDE.md 强多了，因为信息是实时的。你改了场景，AI 马上就能知道，不用同步文档。

4.3 MCP Server 的门槛与局限

但 MCP Server 也不是没门槛：

配置复杂：需要启动 WebSocket 服务，配置端口、权限。搞不好要折腾半天。

AI 支持有限：目前只有 Claude Code 支持 MCP 协议，Cursor、Copilot 还不支持。

文档稀少：Cocos MCP Server 的文档和社区资源不多，遇到问题不太好查。

所以如果你只是个人开发者，想快速解决问题，CLAUDE.md + 场景文档方案更合适。MCP 更适合有技术能力的团队长期投入。

4.4 MCP 与 CLAUDE.md 的配合使用

其实这两套方案不是替代关系，是互补关系：

• CLAUDE.md 提供静态上下文：项目概况、命名规范、设计理念
• MCP 提供动态交互：实时获取场景信息、创建节点

如果你配置了 MCP，CLAUDE.md 依然有用。MCP 只能回答”现在有什么”，没法告诉 AI “为什么这么设计”、“命名规范是什么”。这些还得写在 CLAUDE.md 里。

5. 实战总结与行动建议

5.1 最小可行方案（今天就能开始）

如果你只是想让 AI 理解项目，不需要什么高级配置，三步搞定：

第一步：创建 CLAUDE.md 文件，写上项目基本信息。引擎版本、游戏类型、场景结构概述。

第二步：用本文第 3 章的 Prompt 模板，生成 3 个核心场景的说明文档。Boot、Game、Result，够用了。

KiloClaw - 企业级 OpenClaw 托管服务，赋能 AI Agent 自动化编排与智能模型路由

立即开始 →推广

第三步：把场景文档放在 docs/ 目录，CLAUDE.md 里加引用。

半小时内就能完成。之后 AI 问你项目结构，直接把文档甩给它。

5.2 进阶方案（有开发能力的团队）

如果你愿意投入更多，可以这样做：

配置 Cocos MCP Server：Skywork AI 的开源实现，文档还算清晰。配置好后 AI 能实时获取场景信息。

开发场景导出脚本：写个 Cocos 扩展，自动导出场景结构到 JSON 或 Markdown。比手动描述更准确。

自动化更新：把导出脚本加到构建流程，每次构建自动更新 CLAUDE.md。

这套方案需要一定的开发工作量，适合中大型团队。

5.3 长期目标

理想状态是：AI 真正理解游戏项目，像理解 Web 项目一样。编辑器与 AI 深度融合，游戏开发文档化成为行业标准。

Unity 已经有了 Bezi 这种实时索引工具，Cocos 估计也会跟进。但在那之前，文档化是最靠谱的方案。

结论

AI 辅助游戏开发有个根本障碍：AI 看不见编辑器里的内容。场景层级、节点结构、组件配置，这些 AI 都不知道。解决办法是文档化——把 AI 看不见的东西写下来。

CLAUDE.md 是项目级上下文，场景说明文档是细粒度补充。两者配合，AI 就能准确定位节点、理解组件职责。如果你有开发能力，还可以配置 MCP Server，让 AI 实时获取场景信息。

今天就试试：创建一个 CLAUDE.md 文件，用本文的 Prompt 生成第一个场景文档。如果你有其他实践心得，欢迎在评论区分享。