AI で Cocos シーン説明ドキュメントを生成：コードアシスタントにゲームを正しく理解させる

Claude に新しいコンポーネントを書かせると、存在しないノード名を参照するコードが出てくる。Cursor に機能追加を頼むと、再利用できる Prefab があることすら知らない。プロジェクト構造を説明しても、数日後にはまた一から説明し直し。

AI でゲーム開発を支援すると、こうしたことがよく起きる。Web プロジェクトなら AI は得意だが、Cocos Creator になるとどこか「ズレる」。AI が愚かというより、シーン階層・ノード構造・コンポーネント設定をそもそも見えていないからだ。

根本的な問題は、AI とゲームエンジンが別ツールであること。AI が読めるのはコードファイルだけ。Cocos の中核はシーン内にあり、.scene や .prefab の JSON 構造を AI が直接理解するのは難しい。

本記事では、CLAUDE.md + シーン説明ドキュメントで AI にゲームプロジェクトを正しく理解させる実践的な方法を紹介する。コピーして使えるプロンプトテンプレートも用意した。

1. AI がゲームプロジェクトを理解できない理由

1.1 AI とエンジンの「隔離壁」

Summer Engine のブログが明快に述べている。AI とエンジンは分離されたツールだ。AI はシーン階層、既存スクリプト、プロジェクト構造を感知できない。コードを書かせるとき、与えたコンテキストから推測するしかない。問題は、そのコンテキストが足りないこと。

Web 開発とは違う。Web なら構造の多くがファイルに載っている。AI が読めば把握できる。ゲームでは、シーン階層、ノード位置、コンポーネントパラメータなど、エディタ内の情報がコードでは表現できない。

1.2 Cocos Creator プロジェクトの特殊性

Cocos Creator のシーン（Scene）は論理構造であり、コードファイルではない。.scene を開いても JSON の羅列に見えるだけで、AI は積極的に解析しない。ノード階層（Hierarchy）はエディタでドラッグして作ったもの。Prefab はさらに特殊で、本質的にリソースファイルだ。

結果として、「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 というコンポーネントなら、コードから役割は分かる。しかしどのノードにアタッチされているか、どのノードとやり取りするかは分からない。そうした情報が CLAUDE.md に書く内容だ。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

2.2 ゲーム向け CLAUDE.md に書くこと

Mr. Phil Games のブログでは、次のカテゴリを推奨している。

プロジェクト基本情報：エンジンバージョン、ターゲットプラットフォーム、ゲームタイプ。Cocos 3.8 か 2.x か、微信ミニゲームか App かを AI が把握できる。

シーン構造の概要：Boot、Game、結果画面がそれぞれ何をするか。「Boot シーンでリソースを読み込む」の意味を理解できる。

コアノードの命名規則：Canvas、GameRoot、UIRoot などのトップレベルノード。AI がコード生成時にこれらの名称を使う。

コンポーネント一覧：実装済みコアコンポーネントと役割。車輪の再発明を防ぐ。

2.3 Cocos Creator 向け CLAUDE.md の例

カジュアルミニゲーム Demo の 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 で、階層が 2 段違った。AI も自分も言い忘れ、実行時エラーになった。

シーン説明ドキュメントはこうした事故を防ぐ。構造を明文化すれば、AI がコードを書くとき正確にノードを特定できる。

3.2 プロンプトでシーン説明ドキュメントを自動生成

手書きは大変なので、AI に生成させる。以下のプロンプトテンプレートをそのまま使える。

我有一个 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 ドキュメントの生成

このプロンプトで 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 に再説明するより楽。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

大きなチームは 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 は次をサポートする。

• ツール呼び出しでシーン情報を取得
• エディタ内でノードを直接作成
• Prefab 内容の読み取り
• コンポーネント設定の照会

CLAUDE.md より強力なのは、情報がリアルタイムである点。シーンを変更すれば AI もすぐ把握でき、ドキュメント同期が不要になる。

4.3 MCP Server のハードルと限界

ただし MCP Server にもコストがある。

設定が複雑：WebSocket サービスの起動、ポート・権限の設定。環境によっては半日かかることも。

AI 対応が限定的：現状 MCP をフルサポートするのは Claude Code が中心。Cursor や Copilot は未対応。

ドキュメントが少ない：Cocos MCP Server の資料やコミュニティが薄く、トラブル時の調査が大変。

個人開発者が素早く解決したいなら、CLAUDE.md + シーン説明ドキュメントが適切。MCP は開発力のあるチームの長期投資向けだ。

4.4 MCP と CLAUDE.md の併用

両者は置き換えではなく補完関係だ。

• CLAUDE.md：静的コンテキスト（プロジェクト概要、命名規則、設計思想）
• MCP：動的インタラクション（リアルタイムのシーン情報、ノード作成）

MCP を入れても CLAUDE.md は有用。MCP は「今何があるか」は答えられるが、「なぜそう設計したか」「命名規則は何か」までは伝えられない。それらは CLAUDE.md に書く。

5. 実践まとめとアクション

5.1 最小構成（今日から始められる）

AI にプロジェクトを理解させたいだけなら、3 ステップで十分。

ステップ 1：CLAUDE.md を作成。エンジンバージョン、ゲームタイプ、シーン構造の概要を書く。

ステップ 2：第 3 章のプロンプトで Boot、Game、Result の 3 コアシーンの説明を生成。

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

ステップ 3：説明ドキュメントを docs/ に置き、CLAUDE.md から参照する。

30 分以内で完了できる。その後はプロジェクト構造を聞かれたら、ドキュメントを渡せばよい。

5.2 発展構成（開発力のあるチーム）

さらに投資するなら、次も検討できる。

Cocos MCP Server の設定：Skywork AI の OSS 実装。ドキュメントも比較的明確。設定後は AI がシーン情報をリアルタイム取得できる。

シーンエクスポートスクリプト：Cocos 拡張でシーン構造を JSON や Markdown に自動出力。手入力より正確。

更新の自動化：エクスポートスクリプトをビルドフローに組み込み、ビルドのたびに CLAUDE.md を更新。

一定の開発工数が必要。中〜大規模チーム向けだ。

5.3 長期的な目標

理想は、AI が Web プロジェクトと同程度にゲームプロジェクトを理解すること。エディタと AI が深く融合し、ゲーム開発のドキュメント化が業界標準になること。

Unity には Bezi のようなリアルタイムインデックスツールがある。Cocos も追随するだろう。それまでは、ドキュメント化が最も確実な手段だ。

結論

AI 支援ゲーム開発の根本的な障壁は、AI がエディタ内の内容を見えないこと。シーン階層、ノード構造、コンポーネント設定は AI の外側にある。解決策はドキュメント化。見えないものを書き、読めるようにする。

CLAUDE.md はプロジェクト単位のコンテキスト。シーン説明ドキュメントは細粒度の補完。両方で AI はノードを正確に特定し、コンポーネントの役割を理解できる。開発力があれば MCP Server でリアルタイム取得も可能。

今日から試してほしい。CLAUDE.md を 1 つ作り、本文のプロンプトで最初のシーン説明を生成する。他の実践知見があれば、コメントで共有してほしい。