TesujiConnections into possibilities
People, AI and services, connected in one network

Connect knowledge and work to discover your next move.

Published

Claude Code × Unity × GitHub：既存ゲームを壊しにくい「AI実装契約」の作り方

Revision history

Claude CodeへUnityの実装を任せる前に、調査・変更範囲・禁止事項・検証・PRを明示し、既存プロジェクトを壊しにくくする実践手順を理解する。

Share this article

Share on X

AIコーディングで本当に怖いのは「書けない」ことではない

Claude CodeのようなAIコーディングツールは、既存コードを読んで修正する作業に向いています。

一方、Unityプロジェクトではコードだけ見ても全体像が分かりません。

  • Scene
  • Prefab
  • Inspector参照
  • ScriptableObject
  • Animator
  • Input設定
  • Addressables
  • Project Settings
  • 外部Package

などが、コードの外側で挙動を決めています。

そのため危険なのは「AIがコードを書けないこと」ではなく、局所的には正しい変更を、広い範囲へ一気に書きすぎることです。

先に「実装契約」を作る

AIへ作業を渡す前に、タスクごとに短い契約を作ります。

最低限、次の6項目です。

  1. 目的
  2. 変更してよい範囲
  3. 変更してはいけない範囲
  4. 既存パターン
  5. 完了条件
  6. 検証方法

たとえば、

目的

リトライ時にスコアが初期化されない不具合を直す。

変更してよい範囲

ScoreManager、関連テスト。

変更禁止

Scene構造、セーブ形式、Package追加、Public API名変更。

既存パターン

ゲーム状態は既存GameStateを正本とする。

完了条件

Retry後にスコアが0。通常Restartでも既存挙動を維持。

検証

EditModeテスト、PlayMode確認、対象Sceneで2回連続Retry。

この程度でも、AIが勝手に大規模リファクタリングへ走る確率をかなり下げられます。

Step 1：最初のターンは「調査だけ」にする

いきなり編集させず、まず既存構造を読ませます。

確認させるのは、

  • 関連クラス
  • 状態の正本
  • 似た実装
  • テスト
  • Scene / Prefabとの接点
  • 保存データとの関係

です。

ここでAIが「新しいManagerを追加しましょう」と言っても、既存に似た責務があるなら増やさない方がよい場合があります。

AIに新設させる前に、既存の置き場所を探させる。

これは既存プロジェクトではかなり重要です。

Step 2：差分の上限を決める

変更が広がるほどレビューコストが増えます。

たとえば最初から、

  • 原則1〜4ファイル
  • 新規依存追加なし
  • unrelated refactor禁止
  • フォーマットだけの大量差分禁止

のような制約を置きます。

もちろん必要なら超えて構いません。

重要なのは、超えるなら理由を説明させることです。

AIは作業を終えるために変更範囲を広げることがありますが、人間側はそのコストを後で払います。

Step 3：Unity特有の「見えない依存」を確認する

C#コード上では参照がなくても、UnityではInspectorから参照されていることがあります。

フィールド名を変えただけで、既存Prefabの設定が壊れるケースもあります。

そのためAIに、変更前に次を確認させます。

  • SerializeFieldの変更
  • MonoBehaviour名の変更
  • ScriptableObjectのフィールド変更
  • Prefab参照
  • Scene内コンポーネント
  • Animation Event

特に「整理のために名前を変える」は、UnityではWebアプリより高くつくことがあります。

Step 4：テストを3層に分ける

1. 静的・コンパイル

  • C#コンパイル
  • lint / analyzer
  • 型エラーなし

2. 自動テスト

  • EditMode
  • PlayMode
  • 既存回帰テスト

3. 実際のプレイ確認

  • 対象Sceneを開く
  • 操作する
  • Retryする
  • Scene再読込
  • 必要ならBuild確認

この3層を分ける理由は、Unityでは「テストが通る」と「ゲーム内で正しく動く」が一致しないことがあるからです。

Step 5：最後にdiffだけをレビューさせる

実装後、同じAIへもう一度コードを書かせるのではなく、diffだけを見せて批判させます。

観点は固定します。

  • 依頼外の変更がないか
  • 既存仕様を壊していないか
  • null / lifecycle問題がないか
  • 既存パターンから逸脱していないか
  • テスト不足がないか
  • 削除できる余計なコードがないか

この「実装モード」と「批判モード」の分離は効きます。

GitHubではPRを検証カードとして使う

PRは変更を見せる場所だけではありません。

AI開発では、人間が最短で確認するための検証カードにした方がよいです。

PR本文に最低限、

  • 目的
  • 変更ファイル
  • 変更しなかった領域
  • 自動テスト結果
  • 手動確認手順
  • 残るリスク

を残します。

これで会話ログを全部読み返さなくても、merge判断できます。

失敗例：AIに「きれいにして」と頼む

特に危険なのは、

この周辺コードをきれいにリファクタリングして

という依頼です。

AIにとって「きれい」は、

  • クラス分割
  • 新しいinterface
  • dependency injection
  • 命名変更
  • 共通化

などを意味するかもしれません。

しかし、ゲームが今動いているなら、その変更にはすべて回帰リスクがあります。

既存ゲームでは、まず

このバグだけ直す。既存アーキテクチャは維持する。

の方が安全です。

AIに向いているUnity作業

Claude Codeへ任せやすいのは、

  • 再現条件が明確なバグ修正
  • 既存パターンに沿った小機能
  • テスト追加
  • ログ追加
  • 重複処理の局所整理
  • 仕様のコード逆引き
  • migration前の影響範囲調査

です。

逆に、

  • 操作感
  • 難易度
  • 演出テンポ
  • 「気持ちいいか」
  • アート方向性

は、実際に遊んで人間が判断する必要があります。

KPIは「AIが何％書いたか」ではない

AI活用の品質を見るなら、

  • PRあたりの手戻り回数
  • 依頼外変更率
  • merge後の回帰不具合
  • 人間レビュー時間
  • タスク開始 → Play確認までの時間

を見る方が有用です。

特に依頼外変更率は、AIコーディング運用の健康状態を見る良い指標です。

次の一手

次にClaude CodeへUnityタスクを渡すとき、依頼文の先頭に以下を付けます。

  • まず調査。編集前に既存構造を説明
  • 既存パターンを優先
  • unrelated refactor禁止
  • Scene / Prefab / SerializeField影響を確認
  • 自動テスト + 手動確認手順を残す
  • 最後にdiffを批判レビュー

これだけで、AIを単なるコード生成器ではなく、既存プロジェクトに参加する開発者として扱うための境界線ができます。