AI で Cocos シーン説明書を生成：コードアシスタントにゲームを理解させる方法

Claude に新しいコンポーネントを書いてもらうと、存在しないノード名を参照するコードが生成されます。Cursor に機能を追加してもらうと、再利用可能なプレハブがあることを知りません。プロジェクト構造を説明しても、数日後にはまた最初から言い直しになります。

正直に言うと、AI を使ってゲーム開発を支援してもらうとき、こういうことは日常茶飯事です。AI は一般的な Web プロジェクトではそこそこ上手くやりますが、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 というコンポーネントがあるとします。AI はコードを読めば何をするか分かります。しかし、このコンポーネントがどのノードにマウントされているか、どのノードと対話するかは分かりません。こうした情報が CLAUDE.md に書くべき内容です。

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

価格を見る →広告

2.2 ゲームプロジェクトの CLAUDE.md に書くべきこと

Mr. Phil Games のブログでは、以下の情報を書くことを推奨しています。

プロジェクト基本情報：エンジンバージョン、ターゲットプラットフォーム、ゲームタイプ。これで AI は Cocos 3.8 なのか 2.x なのか、WeChat ミニゲームなのかアプリなのかを把握できます。

シーン構造の概要：Boot シーン、Game シーン、決済ページがそれぞれ何をするか。AI はこれを知って初めて「Boot シーンでリソースをロード」の意味を理解できます。

コアノード命名規則：Canvas、GameRoot、UIRoot などのトップレベルノード。AI はコード生成時にこれらの名前を自動的に使用します。

コンポーネント一覧：実装済みのコアコンポーネントとその役割。AI が車輪の再発明をするのを防ぎます。

2.3 Cocos Creator プロジェクトの CLAUDE.md 例

これが私のカジュアルゲームプロジェクトの CLAUDE.md です。参考にしてください。

# プロジェクトコンテキスト - ミニゲーム Demo

## 基本情報
- エンジン：Cocos Creator 3.8
- タイプ：カジュアルゲーム
- プラットフォーム：WeChat ミニゲーム

## シーン構造
- 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 は以下の機能をサポートしています。

• AI がツール呼び出しでシーン情報を取得
• AI がエディタで直接ノードを作成
• AI がプレハブコンテンツを読み取り
• AI がコンポーネント設定をクエリ

これは 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 の併用

実は、この2つのソリューションは代替関係ではなく、補完関係です。

• CLAUDE.md は静的コンテキスト：プロジェクト概要、命名規則、設計理念
• MCP は動的対話：リアルタイムでシーン情報を取得、ノードを作成

MCP を設定しても、CLAUDE.md は依然として有用です。MCP は「今、何があるか」しか答えられず、「なぜこう設計したか」「命名規則は何か」を AI に教えられません。これらはやはり CLAUDE.md に書く必要があります。

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

5.1 最小限の実用的ソリューション（今日から始められる）

AI にプロジェクトを理解させたいだけなら、高度な設定は不要です。3ステップで完了します。

ステップ1：CLAUDE.md ファイルを作成し、プロジェクト基本情報を書く。エンジンバージョン、ゲームタイプ、シーン構造の概要。

ステップ2：本記事第3章のプロンプトテンプレートを使って、3つの主要シーンの説明書を生成する。Boot、Game、Result、これで十分。

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

15%割引を入手 →広告

ステップ3：シーン文書を docs/ ディレクトリに配置し、CLAUDE.md に参照を追加。

30分以内で完了します。その後、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 ファイルを作成し、本記事のプロンプトで最初のシーン文書を生成してください。他にも実践的なノウハウがあれば、コメント欄で共有してください。