【ITニュース解説】Context Engineering for Unity: How to Make AI Useful on Real Projects

AIを活用したプログラミングツールは、デモンストレーション環境では非常に高性能に見えるが、数年間稼働している実際のUnityプロジェクトに導入すると、その性能が大きく低下することがしばしばある。この違いの主な原因は、AIへの指示であるプロンプトの出し方にあるのではなく、プロンプトを取り巻く「コンテキスト」、つまりプロジェクト全体の背景情報や目に見えないルール、設定が不足している点にある。長年ゲーム開発に携わってきた経験から、実際の開発では、シーン、プレハブ、パッケージ、ビルド設定、命名規則、プラットフォーム要件など、プロジェクトの隅々に散らばった前提知識の上に成り立っていることを学んだ。AIアシスタントは、それらの目に見えない情報を理解できなければ、役に立つコードを生成することはできないのだ。

AIコーディングツールの失敗は、多くの場合、文法的な間違いではなく、AIがプロジェクトのコンテキストを誤解していることによる。たとえば、本来テンプレートとして扱うべきプレハブを直接変更したり、インストールされているパッケージバージョンでは利用できないAPIを呼び出したり、既存のアーキテクチャとは異なる新しい設計を勝手に導入したりする。これらは「実装の失敗」に見えるが、その本質は「コンテキストの失敗」なのである。

Unityプロジェクトでは特にこの問題が顕著である。なぜなら、プロジェクトの重要な振る舞いは、スクリプトだけでなく、シーン、プレハブ、スクリプタブルオブジェクト、アニメーションコントローラー、物理レイヤー、タグ、パッケージマニフェスト、品質設定、プラットフォーム固有の構成など、多岐にわたる場所に存在するためだ。AIがたった数個のC#ファイルしか見ていない場合、それらのファイルに対してはもっともらしい回答を生成するかもしれないが、実際にはそのAIが名前を変更しようとしているメソッドが、プレハブ内のシリアライズされたイベントに依存している、といった隠れた依存関係を全く認識できない。

この問題を解決し、AIを実際のプロジェクトで有用なツールにするためには、「コンテキストエンジニアリング」という考え方が重要になる。これは、AIが有用でレビュー可能な変更を安全に行えるよう、実際のUnityプロジェクトを整理し、AIアシスタントに十分な「証拠」を提供することである。AIへの最初の問いは、コードが書けるかではなく、AIがその仕事を理解するための十分な証拠を持っているかである。証拠が不足していれば、プロンプトを洗練させる前に、関連するファイルパス、Unityおよびパッケージのバージョン、アーキテクチャの境界、期待される振る舞い、既知のリスクなど、より多くのコンテキストを提供するべきだ。プロジェクトの目に見えない部分をAIに「見える」ようにすることが、コンテキストエンジニアリングの始まりである。

AIが理解しやすいUnityプロジェクトのブリーフを作成することは、プロジェクトに新しく参加した開発者に特定のタスクを説明するように、リポジトリをAIに説明するようなものだ。このブリーフは、全てのクラスを文書化する必要はないが、AIが勝手に再設計してはならない重要な決定事項を明確にする必要がある。具体的には、Unityエディターのバージョン、レンダリングパイプライン、サポートするプラットフォーム、入力ソリューション、主要なパッケージ、アセンブリのレイアウト、テストのアプローチ、ランタイムコード、エディターコード、サンプル、サードパーティの依存関係のディレクトリ境界などを記述する。

さらに、プロジェクトのアーキテクチャを平易な言葉で説明する。例えば、ゲームの状態をどのシステムが管理しているか、シーンの遷移方法、サービスの検索方法（依存性注入、明示的な参照、静的アクセスなど）、スクリプタブルオブジェクトが設定資産なのかランタイム状態を保持するのか、非同期操作がコルーチン、タスク、またはプロジェクト固有の抽象化に基づいているのか、といった点である。これらはAIに設計変更を促すものではなく、既に存在する選択肢をAIに伝える「契約」となる。

また、AIに「禁止されている変更」も明記することが重要だ。例えば、アセットパッケージが新しい依存関係をサイレントに追加すること、グローバルなプロジェクト設定を変更すること、顧客にシーンの再構築を要求することなどが考えられる。これは、再利用可能なアセットストアのコードを扱う上で特に重要となる。AIがこれを推測するのを期待するのではなく、プロジェクトブリーフで直接その要件を述べるべきである。

最終的に、「完了の定義」も観察可能な形で含める。コードが新しい警告なしにコンパイルされること、既存の公開APIが互換性を保つこと（明示的に破壊的変更が許可されない限り）、編集モードとプレイモードのテストが全てパスすること、新しいシリアライズフィールドに安全なデフォルト値があり、既存のアセットに影響がある場合は移行計画があること、承認された範囲外のファイルは変更されないことなどだ。このブリーフはリポジトリに保存し、コードとしてレビューし、アーキテクチャが変更された際には更新する。これにより、人間とAIアシスタントが常に同じベースラインを共有し、会話ごとにプロジェクトの異なるバージョンが生まれることを防ぐ。

AIに作業を依頼する際には、広範なリクエストは避け、AIが理解しやすい小さなタスクに分割することが重要だ。例えば、「カメラシステムを改善してほしい」といった漠然とした要求は、AIにインプット、スムージング、衝突判定、フレーミング、シリアライズ、公開APIなどを同時に解釈し直す自由を与えてしまう。これではAIは広範な推測をするしかなくなる。代わりに、「あるコンポーネントに任意の最大ズーム制限を追加し、既存のデフォルト設定を維持し、一つのテストファイルを更新し、フレームごとのパスでのメモリ割り当てを避ける」といった、より具体的で、レビュー可能なタスクに分割するべきだ。後者のリクエストは一見小さいが、より有用なエンジニアリング情報を含んでいる。

タスクの分割は、検証しやすい境界に基づいて行う。良いタスクには、一つの行動目標、限られたファイルセット、既知の制約、そして他の機能が完成していなくてもテストできる結果があるべきだ。調査と実装は別々のタスクとして扱う。まずAIに値の発生源をトレースさせたり、メソッドへのシリアライズされた参照をリストアップさせたり、二つの可能な拡張ポイントを比較させたりする。この「マップ」を検証してから、初めてコードの生成を依頼する。これにより、不確実な分析が大規模なコード変更の中に埋もれてしまうのを防ぐことができる。

複数のシステムにまたがるタスクの場合、コードを生成する前に「計画」を要求することも有効だ。計画には、変更するファイルの名前、各ファイルが関与する理由、互換性リスクの特定、提案されるテストなどが含まれるべきである。AIアシスタントは曖昧さを解決するために抽象化を作成しがちだが、成熟したプロジェクトでは、既に存在する抽象化を尊重する狭い変更が必要な場合が多い。不必要なマネージャー、ラッパー、サービスロケーター、汎用フレームワークを導入する計画は却下する。

最後の要求には「停止条件」を含めるべきだ。もし必要なクラスが欠落していたり、パッケージのAPIが不確実だったり、シーンの参照が検査できなかったりする場合、AIアシスタントは答えをでっち上げるのではなく、その不確実性を報告するように指示する。現在のAIモデルは、リポジトリの証拠が不完全であっても、タスクのような会話を完了する能力が高まっているため、この点は非常に重要だ。流暢さが不確実性を隠してしまうことがあるため、小さなタスクに分割することで、それを露呈させることができる。また、小さなタスクはコミットのレビュー、ロールバック、ベンチマーク、割り当てを容易にする。AIによる作業の望ましい単位は、完全な機能ではなく、「自身の正しさを証明できる最小限の一貫した変更」である。

AIモデルが絶対に推測してはならないUnityの詳細はいくつかある。まず「Unityのバージョン」は明示的に指定すべきである。API、パッケージの互換性、シリアライズの振る舞い、ビルドツールは時間の経過とともに変化する。何年ものUnityの例で訓練されたモデルは、古いチュートリアル、新しいパッケージAPI、非推奨のワークフローを組み合わせて、一見もっともらしいコードを生成するかもしれない。そのため、正確なエディターバージョンと関連するパッケージバージョンを提供し、その環境に対して検証できないAPIがあれば、AIにフラグを立てるよう要求する。

「シーンとプレハブの所有権」も明確にする必要がある。AIアシスタントに、プレハブインスタンスの編集がそのソースの編集と同じであると仮定させたり、シーンオブジェクトが常に実行時に存在すると仮定させたりしてはならない。タスクは、参照がどのように割り当てられるか、オブジェクトが追加的にロードされるか、シーン遷移後も何が残るか、プレハブがプロジェクトに属するものか、インポートされたパッケージの一部なのかを明記すべきだ。もしAIアシスタントがシリアライズされたYAMLを安全に検査できない場合は、スクリプトファイルだけが全てを語ると仮定するのではなく、人間が読める要約を提供する。

「実行順序」も危険な推測領域である。Unityのライフサイクルメソッド、スクリプト実行設定、ドメインリロードオプション、Playモードへの入り方、非同期ロードは全て、初期化のタイミングを変更し得る。AIアシスタントは、Updateメソッドに便利な参照ルックアップを追加することでヌル参照エラーを修正するかもしれないが、それは目に見えるライフサイクルバグを永続的なパフォーマンスコストに置き換えてしまう可能性がある。初期化の契約は説明され、テストされるべきであり、繰り返し検索してパッチを当てるべきではない。

「プラットフォームの挙動」も同様に明確にすべき事項だ。タッチ、マウス、コントローラー、VR入力、セーフエリア、ファイルパーミッション、グラフィック機能は相互に交換可能ではない。どのプラットフォームが重要で、どれが範囲外かをモデルに伝える必要がある。また、どのコードがフレームごと、物理ステップ、エディターコールバック、ビルド中に実行されるかを特定する。これらの詳細によって、メモリ割り当て、リフレクション呼び出し、アセットルックアップ、条件付きコンパイルシンボルが許容されるかどうかが決まる。コンテキストが利用できない場合、AIの正しい応答は自信に満ちた推測ではなく、質問であるべきだ。

AIが生成したコードは、人間が書いたコードと同じ「証拠のパイプライン」を通じてリポジトリに導入されるべきである。コンパイルは最初の関門に過ぎない。特にAIがリファクタリングを提案する場合、実装を受け入れる前に、意図された振る舞いを記述するテストが必要である。もしメソッドがズームをクランプし、古いデフォルト設定を維持し、無効な設定を拒否するはずであれば、それらの期待は実行可能なテストとして表現されるべきだ。そうでなければ、レビューはコードが合理的かどうかについての議論になってしまう。

テストは、コンテキストを伝える簡潔な形式でもある。適切に命名されたテストは、AIアシスタントにシステムが何を約束しているか、どのエッジケースが重要か、そして互換性が何を意味するかを伝える。Unityの作業では、純粋なC#ロジックをエンジンに依存する振る舞いから、可能であれば分離する。純粋な計算は、多くの場合、エディターモードテストで迅速にカバーできる。フレームタイミング、コルーチン、シーンローディング、コンポーネントのライフサイクル挙動は、プレイモードテストを必要とするかもしれない。全てをエンジンから独立したレイヤーに強制するわけではないが、単純なルールをテスト不可能にすることは避ける。

時には、小さなタスクのブリーフをスクリプタブルオブジェクトとしてバージョン管理することで、制約と受け入れチェックがチーム内で検査可能になる。これは、AIツールにコピーしたり、エディターユーティリティによってエクスポートしたりできる一貫した要約を作成する。

Copy
1using System;
2using System.Text;
3using UnityEngine;
4
5[CreateAssetMenu(menuName = "AI/Task Context")]
6public sealed class AiTaskContext : ScriptableObject
7{
8    [SerializeField] private string objective;
9    [TextArea(3, 8)]
10    [SerializeField] private string constraints;
11    [SerializeField] private string unityVersion;
12    [SerializeField] private string[] packageVersions = Array.Empty<string>();
13    [SerializeField] private string[] acceptanceChecks = Array.Empty<string>();
14
15    public string BuildBrief()
16    {
17        var builder = new StringBuilder();
18        builder.AppendLine($"Objective: {objective}");
19        builder.AppendLine($"Unity: {unityVersion}");
20        builder.AppendLine($"Packages: {string.Join(", ", packageVersions)}");
21        builder.AppendLine("Constraints:");
22        builder.AppendLine(constraints);
23        builder.AppendLine("Acceptance checks:");
24
25        foreach (string check in acceptanceChecks)
26            builder.AppendLine($"- {check}");
27
28        return builder.ToString();
29    }
30}

このオブジェクトはセキュリティ境界ではなく、リポジトリのドキュメントに取って代わるものでもない。その価値は一貫性にある。目的、環境、チェックは、プライベートなチャット履歴の中に消えてしまうことなく、作業と共にレビューできる。AIが支援した変更ごとに、会話の外でテストを実行する。実際の変更差分を検査し、影響を受けるシーンやプレハブを開き、関連するプラットフォームパスをテストする。もしモデルがテストと実装を一緒に書いた場合でも、意図的にエッジケースを自分で追加または変更する。モデルは自身の仮定を単に確認するだけのテストを生成する可能性があるため、独立したチェックこそが、もっともらしいパッチを信頼できる証拠に変える。

AIが生成したコードは、人間が書いたコードよりも懐疑的にレビューするべきだ。これはAIコードが自動的に劣っているからではなく、作者からの情報伝達方法が異なるためである。人間のチームメイトは、プロジェクトの歴史からどのような仮定が生まれたかを説明できるが、モデルは不完全な証拠から組み立てられた洗練された説明を提供するかもしれない。レビューは、外部から内部へ、まずスコープ、次に振る舞い、三番目にアーキテクチャ、最後にスタイルという順序で行う。もしパッチが目的と無関係なファイルを触っている場合、命名規則を議論する前にレビューを停止する。

最初のレビューでは、メンテナンスの表面積を拡大する追加要素をチェックする。変更によって新しいパッケージ、静的シングルトン、リフレクションヘルパー、エディター設定、スクリプティング定義、または新しい公開APIが導入されていないか。既存のロジックがコピーされていないか。単一のユースケースのために汎用的な抽象化が作成されていないか。これらのパターンは専門的に見えるかもしれないが、プロジェクトの理解を難しくする可能性がある。余分な機構を受け入れる前に、削除や簡素化を求める。

二番目のレビューでは、Unity固有の失敗パスを追跡する。シリアライズフィールドのリネーム、デフォルト値、参照欠落の振る舞い、イベント購読、シーンアンロード、破棄されたオブジェクト、ドメインリロード、エディター専用APIなどを検査する。ライフサイクルメソッドが誤って基底実装を隠していないか、繰り返し呼び出しがメモリ割り当てやリスナーの重複を引き起こしていないかを確認する。再利用可能なコード（例えばTouch Camera PROのような製品）の場合は、名前空間の衝突、オプションの統合、サンプルの分離、顧客が既存のシーンを修正せずにアップグレードできるかどうかも考慮する。

最後のレビューでは、AIアシスタントの説明を検証すべき「主張」として扱い、証明として受け取らない。説明を実際の変更差分と比較し、テストを実行し、エディターで機能を実際に試す。たとえAIアシスタントが数秒で大規模なパッチを生成できたとしても、コミットごとに一つの概念的な変更に限定することを推奨する。小さなコミットは説明責任を維持し、回帰バグの特定を容易にする。また、クライアントのポリシーに従い、AIの関与を記録する。特にリポジトリへのアクセス、機密性、ライセンスが関係する場合である。レビューは、パッチを生成した同じモデルに委ねることはできない。開発者は、受け入れた全ての行を理解し、チームが自信を持って保守できないコードを削除する責任を負う。

AIを成熟した製品に導入する際には、いきなり製品の核心部分をリファクタリングさせることから始めるべきではない。結果の比較が容易で、ロールバックが安価な「端っこ」から始めるのが良い。既存の振る舞いに関するテストの草案作成、なじみのないサブシステムの要約、重複する検証の特定、エディター診断の改善、限定的なドキュメント更新などが、良い初期タスクとなる。これらの作業は、大規模な移行のリスクを冒すことなく、提供されたコンテキストが正確かどうかを明らかにする。

このアプローチは、長年にわたり使用されているUnityアセットにとって特に重要である。これらの製品はそれぞれ異なる役割を持つが、既存のユーザーが、最新のコードからは明らかでない振る舞いに依存している可能性があるという、パブリッシャーとしての制約を共有している。よりクリーンな実装であっても、デフォルト値、シリアライズ、名前空間、またはセットアップ手順を変更してしまうと、それは誤った実装となる可能性がある。成熟したパッケージでAIを使用する前に、互換性の約束を特定し、代表的なプロジェクトセットアップをテストまたはサンプルシーンとしてキャプチャする。

クライアントワークには、さらなる規律が必要である。フリーランスの経験を通じて、様々なプロジェクトや契約に携わってきたが、それぞれの契約で同じAIポリシー、リポジトリアクセスルール、ツール選択が適用されるわけではない。外部サービスに資料を送る前に、クライアントのポリシー、データ境界、契約要件、承認ツールを確認する。承認が不明確な場合、ソースコードやプロジェクトデータはモデルに入れない。

その後、可逆的なタスクで限定的な試行を行い、通常のワークフローと比較して、AIを導入した際の全体的なワークフローを評価する。これには、コンテキストの準備、生成、修正、レビュー、テスト、ドキュメント化が含まれる。もしAIがタイピング時間を10分節約できても、レビューの不確実性を1時間生み出すのであれば、プロセスを改善したとは言えない。もしAIが未文書化の依存関係を明らかにするのに役立ったり、レビューに耐えうる有用なテストケースを生成したりするなら、そのパターンを維持する。AIの採用は、熱意ではなく、実証された価値を通じて拡大すべきだ。成熟したプロジェクトは知識をゆっくりと蓄積するため、AIへのアクセスもゆっくりと拡大すべきである。

2026年において、AIによる作業の成功指標は、生成されたコード行数であってはならない。コードの量が増えれば、多くの場合、レビューが増え、欠陥の発生する表面積が増え、将来のメンテナンスも増える。プロンプトの数やモデルの使用量もあまり良い指標ではない。これらは成果ではなく活動を測るものだからだ。コーディングアシスタントが短時間で実質的なパッチを生成できるようになった現在、生成速度がボトルネックになることは稀である。ボトルネックは、そのパッチが製品に属するかどうかを決定することにある。

推奨される測定指標は「承認されたタスクのサイクルタイム」だ。これは、開発者が作業を開始するのに十分な情報を得た時点から、変更がレビューされ、テストされ、文書化され、マージの準備が整うまでの時間を測る。可能であれば、同様のAIを使用しないタスクと比較する。また、修正ラウンド数、レビュー時間、見過ごされた欠陥、元に戻された変更、意味のある人間によるレビューを生き残った生成コードの割合も追跡する。これらは監視のための指標である必要はなく、ワークフローが摩擦を生み出しているのか、それとも摩擦を減らしているのかを明らかにするためのものだ。

ドキュメントの品質も有用なシグナルとなる。もしAIアシスタントが初期化順序、サポートされるプラットフォーム、パッケージのバージョンについて繰り返し質問してくる場合、リポジトリに重要なコンテキストが欠けている可能性がある。そのコンテキストを改善することは、人間の開発者にも利益をもたらす。この意味で、AIはプロジェクトの明確さを診断するツールとして機能する。モデルに説明するのが難しいコードベースは、フリーランスに引き渡したり、新しいチームメイトをオンボーディングしたり、数ヶ月後に再訪したりするのも難しいことが多い。

最も強力な指標は退屈だが、「その変更が製品の出荷をより安全または容易にしたか」である。有用なAIの仕事は、リスクの高い手動ステップを減らしたり、回帰テストのカバレッジを追加したり、未文書化の境界を明確にしたり、開発者が実装オプションを比較するのを助けたりするかもしれない。必ずしも完全な機能を生成する必要はない。ツールの価値は、デモンストレーションではなく、承認された成果によって判断される。モデル、コンテキストの制限、統合、価格設定は変化し続けるため、特定のベンダーの個性に基づいてワークフローを構築することは避けるべきである。永続的な投資となるのは、明確なアーキテクチャ、狭いタスク、自動化されたチェック、そして規律あるレビューを持つリポジトリだ。この基盤が現在のAIツールをより有用にし、次世代のAIツールが登場した際にも価値を持ち続けるだろう。