AIエージェント向けCLI: Unity、Unreal、Godotでトークン最大83%削減

私たちの3つのエンジン向けコマンドラインツール、unity-mcp-cli、unreal-mcp-cli、godot-cli は、AIエージェントにとってはるかに低コストで使えるようになりました。同じエディタ作業で、コールドスタートのエージェントが消費するトークンは60%から83%減り、ツール呼び出しの回数も以前のバージョンより明らかに少なくなっています。そこに至った方法はシンプルで、少しばかり身が引き締まるものでした。小さなAIエージェントにCLIだけを与えて観察し、どこで詰まるかを見つけ、それを直し、また測る、ということを繰り返したのです。

この記事では、その作業の3つのラウンド、数字（思わぬ方向に動いたものも含めて）、そしてAIエージェント向けにCLIを構築するすべての人に当てはまる教訓を順に紹介します。Unity、Unreal Engine、Godot で Claude Code や Codex などのエージェントを使っているなら、これらの変更はセッションの短縮、リトライの減少、そして請求額の削減につながります。

AIエージェント向けCLIをどうテストしたか

各ラウンドのすべての実行は同じ厳格な条件で行ったので、結果は実際のエージェントが実際のマシンで遭遇する状況を反映しています。

• エージェントには小さく高速なLLM（DeepSeek Flash）を使いました。小さなモデルは、大きなモデルなら黙って回避してしまうような粗さを露呈させます。
• 与えられるのはCLIと基本的なファイルツールだけです。MCP接続もドキュメントも、プロンプト内のヒントもありません。
• コールドスタートです。新しいプロジェクト、エンジンは閉じた状態、キャッシュは一切なし。
• 実行が合格となるのは、実際の最終状態が正しい場合だけです。ディスク上のシーンやレベルファイル、あるいはコンパイル結果です。エージェントが「やった」と言ったことはカウントしません。

エージェントが読み書きしたトークン数、ターン数またはツール呼び出し数、ツールエラー、合格したタスクを数えました。そしてトランスクリプトを読みました。数字は何かが遅いことを教えてくれますが、なぜなのかはトランスクリプトが教えてくれるからです。

ラウンド1: エージェントは道を見つけられるか

最初のトランスクリプトはひどいものでした。エージェントはエディタのAIツールにまったくたどり着けませんでした。CLIが「not logged in」と表示すると、エージェントは設定ファイルを手で編集して突破しようとしました。存在しないコマンド名を推測することもありました。これはエージェントのせいではありません。CLIが、必要な情報を伝えていなかっただけです。

そこで最初のラウンドの修正はディスカバリー、つまり見つけやすさがテーマでした。

• 新しい tools コマンドは、エンジンが閉じていてもエディタのAIツールを一覧表示します。ヘッドレスエディタを一度起動してリストをキャッシュし、以降はキャッシュから応答します。
• --help の出力は、日常ワークフローの短いフッターで終わるようになりました。エージェントが実際に必要とする少数のコマンドを、必要な順番で示します。
• ai-game.dev に一度もサインインしたことのないマシンは、行き止まりではなくローカルサーバーを使えるようになりました。サインイン済みのマシンは常にクラウドのままです。
• ヘッドレスエディタはコンパイルエラーを生き延び、何も言わずに失敗するのではなく、ログの場所をエージェントに伝えます。
• 新しい test と compile コマンド（godot-cli では check と呼びます）、さらに Unity と Unreal 向けの dialog コマンド。エディタをブロックしているモーダルダイアログを一覧し、そのうちの1つのボタンを押せます。
• 終了コードは3つのCLIで共通で、エージェント向けコマンドはスクリプトがパースできる出力のために --format json を受け付けます。

このフェーズの最初のラウンドと最終ラウンドを比較します（タスクごとに1回の実行）。

• Unity: 入力トークン 275k → 104k（−62%）、ターン 46 → 30。
• Godot: 入力トークン 598k → 203k（−66%）、ターン 71 → 40、合格タスク 3/4 → 4/4、ツールエラー 27 → 6。
• Unreal: 入力トークン 383k → 414k（+8%）、ターン 66 → 60、ツールエラー 13 → 8。

3エンジン全体では、解決済みタスクあたりの入力トークンが1.9分の1（114k → 60k）になり、12タスク中11ではなく12タスクすべてに合格しました。

そう、Unrealは増えました。エージェントのエラーは減り、少ないターンで終えましたが、その過程でより多くを読んでいました。ラウンド1はエージェントが何を見つけられるかを直しました。どれだけ読まなければならないかはまだ直っておらず、それが次のラウンドのテーマでした。

ラウンド2: 早い段階のバイトは毎ターン支払い直される

このラウンドの重要な洞察は、一度気づけばシンプルです。エージェントの会話は各ステップで成長し、早い段階で読んだものすべてが、以降のすべてのターンで再びモデルに送られます。1ターン目に読んだ大きなヘルプページは、2ターン目、10ターン目、30ターン目にも支払い直されるのです。

ベースラインでは、ルートの --help（4.8 KB、常にエージェントが最初に読むもの）が全ツール出力のトークン量の43%を占めていました。RQLスキーマがさらに24%。早い段階の2回の読み取りがコストの3分の2だったのです。

修正内容は次のとおりです。

• すぐ使えるRQLレシピ付きの短い --help。リファレンスを勉強する代わりに、動くクエリをコピーできます。
• 完全なスキーマの代わりに、コンパクトなスキーマ概要。
• 正しいソース名やメンバー名のヒントを含むRQLエラー。
• クエリをプレーンな引数として受け取る一級の rql コマンド。JSONクォートを間違える心配がありません。
• ディスクに書き込んだファイルを出力する保存操作。以前はエージェントが保存が本当に行われたか確認するために4〜9回の余分な呼び出しをしていました。

RQLは、私たちのエディタツールがシーン、オブジェクト、コンポーネント、アセットを読み取り変更するために使うクエリ言語です。詳しくは ai-game.dev/docs/rql で読めます。

次の案を積み重ねる前に、各アイデアを単独で測定しました。Unrealでタスクごとに3回実行した場合の階段はこうなりました。

1. ベースライン: 403kトークン、ツール呼び出し60回。
2. レシピ付きの短いヘルプ、コンパクトなスキーマ、RQLヒント: 123kトークン（−69%）。
3. さらに一級の rql コマンド: 106kトークン（−74%）。
4. さらに書き込んだファイルを出力する保存: 68kトークン（−83%）、ツール呼び出し31回（−48%）。

同じ変更を3つのCLIすべてに適用し、毎回コールドスタートから測定しました（Unrealはタスクごとに3回、UnityとGodotは2回）。

• Unreal: トークン 403k → 68k（−83%）、ツール呼び出し 60 → 31。
• Unity: トークン 248k → 82k（−67%）、ツール呼び出し 33.5 → 26、合格タスク 4/4。
• Godot: トークン 131k → 53k（−60%）、ツール呼び出し 34 → 28.5、合格タスク 4/4。

ラウンド3: CLI自身が書く小さなスキル

多くのエージェントはスキルをサポートしています。タスクが合致したときにエージェントが読み込む短い指示ファイルです。各CLIの setup-skills コマンドは、エディタを起動せずオフラインで約2.2 KBのスキルを書き出すようになりました。スキルは --help と同じソースから生成されるので、両者がずれることはありません。

スキルなしのエージェントとスキルありのエージェントを、どちらも最適化済みCLIで、3つのエディタタスク、207回の分離実行で比較しました。

• Unity: トークン 160k → 60k（−63%）、ツール呼び出し 42 → 23、18/18合格。
• Unreal: トークン 87k → 53k（−39%）、ツール呼び出し 37 → 24、9/9合格。
• Godot: トークン 117k → 81k（−31%）、ツール呼び出し 49 → 39、18/18合格。

スキルを調整する中で3つの驚きがありました。

• 短いスキルのほうが長いスキルに勝ちました。スキルの各行はヘルプと同じく毎ターン読み直されます。
• 警告として書かれたルールは、エージェントに余分なチェックをさせました。警告するより事実を淡々と述べるほうがうまくいきました。
• コードだけのタスクでは、スキルはあまり役立ちません。その価値はエディタ作業、つまりシーン、レベル、オブジェクト、アセットにあります。

AIエージェント向けCLIを作るすべての人への教訓

これらはゲームエンジンに固有の話ではありません。AIエージェントが使うコマンドラインツールを作るなら、これが私たちが伝えたい教訓です。

• ワークフローとレシピを --help に入れる。エージェントはまずヘルプを読みます。重要な5つのコマンドと、それぞれの動く例を渡しましょう。完全なリファレンスは不要です。
• 早い段階の出力を小さく保つ。エージェントが最初の数ターンで読むものは、以降のすべてのターンで支払い直されます。最初の画面は徹底的に削りましょう。
• 結果を自己検証可能にする。保存がファイルパス付きで「Saved to disk」と出力すれば、エージェントは確認のための呼び出しをやめます。
• すべてのエラーに次の一手を。有効な選択肢を示すエラーは、行き止まりをあと1回の呼び出しに変えます。
• コールドスタートの評価で測る。小さなモデル、新しいプロジェクト、実際の最終状態のチェックを使いましょう。トランスクリプトを読み、1つ変えて、また測るのです。

試してみる

新しいコマンドは各エンジンプラグインの最新リリースで公開されています。unity-mcp-cli 1.11.1、unreal-mcp-cli 0.31.1、godot-cli 0.39.1 です。unity-mcp-cli --help（またはUnrealやGodotの同等のもの）に rql と tools が表示されない場合は以前のバージョンなので、update コマンドで最新にできます。

npx unity-mcp-cli tools
npx unity-mcp-cli rql 'objects | where name starts-with "Tree" | count'
npx unity-mcp-cli compile
npx unity-mcp-cli setup-skills claude-code

npx unreal-mcp-cli tools --filter rql
npx unreal-mcp-cli rql 'actors | where Label starts-with "Rock" | set Scale = Scale * 1.5'
npx unreal-mcp-cli rql 'editor | call SaveLevel()'

npx godot-cli rql 'nodes | where name contains "Enemy" | count'
npx godot-cli check
npx godot-cli setup-skills claude-code

最初のエディタコマンドがヘッドレスエディタを起動してウォームな状態に保つので、先にエンジンを開く必要はありません。rql で行った変更は、何が変わったか、どのファイルが書き込まれたかを出力するので、エージェントはそのまま次のステップに進めます。

はじめに

• Unity: ai-game.dev/engines/unity
• Unreal Engine: ai-game.dev/engines/unreal
• Godot: ai-game.dev/engines/godot
• RQLクエリ言語: ai-game.dev/docs/rql
• クイックスタートガイド: ai-game.dev/docs/quickstart
• Discordコミュニティ: https://discord.gg/cfbdMZX99G

CLIが成長するにつれて、これらのコールドスタート評価は続けていきます。エージェントがどこかで詰まったら、Discordで教えてください。どこで失敗したかのトランスクリプトこそ、私たちが必要としているものです。