How I use Claude Code in Unity

対象読者: Claude Codeは使ったことがある、Unityでどう活用するか知りたい方
筆者環境: macOS and Windows / Unity 6 / Claude Code (Sonnet 4.6) / Unity MCP (CoplayDev)

はじめに

研究室の先生に勧められて、自分がUnity開発でClaude Codeをどう使っているかをまとめることにしました。

Claude Code自体の基本的な使い方は公式ドキュメントや他の記事に任せて、この記事では 「UnityプロジェクトでClaude Codeをどう活用するか に絞って書きます。セットアップ・設計・MCP連携・注意点まで、自分が実際にやっていることを包み隠さず紹介します。

1. 開発環境のセットアップ

ターミナルエミュレータの選択

Claude Codeはターミナルで動かすツールなので、ターミナル環境への投資は直接体験に影響します。自分が試した中でおすすめなのは以下の2つです。

Ghostty

• ネイティブGPUレンダリングで非常に高速
• 設定がシンプルなテキストファイル1枚で完結
• macOS / Linux対応
• Claude Codeの長い出力がスムーズにスクロールするのが快適

WezTerm

• Lua設定で高度なカスタマイズが可能
• タブ・ペイン分割が強力
• macOS / Linux / Windows対応
• マルチプレキサ不要でペインをClaude Code専用に分割できる

どちらもVS Codeのターミナルより遥かに快適なので、まず試してみてください。tmuxやzellij等のマルチプレキサと組み合わせるのもおすすめです。

Claude Codeのインストール

npm install -g @anthropic-ai/claude-code

Node.js 18以上が必要です。インストール後はプロジェクトルートで claude を実行するだけです。

Unityプロジェクトへの初回導入

Unityプロジェクトのルート（Assets/やPackages/があるディレクトリ）でClaude Codeを起動します。最初にやることはいくつかあります。

プロジェクトのフォルダ構成を確認して、Unityプロジェクトであることを把握してください。
使用しているUnityバージョン、主なアーキテクチャ、依存パッケージを教えてください。

このように「まず把握してから動いてもらう」ことが大切です。

2. CLAUDE.md / Skills / Hook

CLAUDE.md — AIへのルールブック

CLAUDE.md はプロジェクトルートに置くマークダウンファイルで、Claude Codeが会話のたびに読み込むプロジェクト内でのルールです。ここに書いたルールはすべての指示に自動的に適用されます。

自分がUnityプロジェクトで書いている内容の一例（毎回必ずこうしているわけではない）：

# CLAUDE.md — [プロジェクト名]

## プロジェクト概要
- ゲームジャンルや技術スタックを1〜3行で説明する
- 使用しているUnityバージョンと主要ライブラリ（VContainer, R3, UniTask等）を列挙する

---

## アーキテクチャ（MVP + DDDライク）

| レイヤー | 名前空間 | 役割 |
|---------|---------|------|
| Domain (Model) | `YourGame.Domain` | 純粋C#。MonoBehaviour禁止。計算ロジックのみ |
| View | `YourGame.View` | MonoBehaviour。UI更新・入力検知のみ |
| Presenter | — | VContainer IStartable。Model ↔ View を接続 |

- DI: VContainerを使用。`Start/Awake`依存禁止、`Inject` / `Initialize(...)` を使う
- Reactive: `ReactiveProperty<T>` でModel変化をPresenterが購読 → Viewへ伝達

---

## コーディング規則


定数/static readonly : UPPER_SNAKE_CASE
クラス名・publicメソッド : PascalCase
private フィールド   : _camelCase
[SerializeField]     : private _camelCase


**禁止事項:**
- Domain層で `MonoBehaviour` を継承しない
- Domain層で `using UnityEngine;` しない
- `Start/Awake` でのDI依存初期化
- コルーチン（UniTaskを使う）

---

## ディレクトリ構成


Assets/_Project/Scripts/
├── Domain/     # 純粋C#。Unityへの依存ゼロ
├── View/       # MonoBehaviour
├── Presenter/  # VContainer IStartable
└── Infrastructure/


---

## タスク管理
- タスク一覧: `Assets/Docs/ToDo.md`
- 進捗ログ: `Assets/Docs/ProgressLog.md`（作業完了後に日付形式で記録）

---

## Do NOT
- 既存のアーキテクチャを無断で変更しない
- ScriptableObjectをランタイムデータのストアに使わない
- Domain層でUnityの型（Vector3等）を直接操作しない

CLAUDE.mdは育てるものです。AIが同じ間違いを繰り返したらここに追記する、という運用をしています。基本的にCLAUDE.mdもAIに作成させ、プロジェクトがある程度進むたびに見直しています。

Skills — 繰り返し使う知識の外部化

Skillsは .claude/commands/ 以下に置くMarkdownファイルで、スラッシュコマンドとして呼び出せます。

例えば /project:new-presenter というSkillを作っておくと：

# new-presenter

新しいPresenterクラスを作成する際のテンプレートを生成します。

1. 対応するIModelインターフェースを確認する
2. VContainerでのDI登録コードを生成する
3. UniTaskを使った非同期初期化メソッドを含める
4. 対応するEditorTestのスケルトンも生成する

毎回同じ説明をしなくて済むため、繰り返し発生する作業はどんどんSkillsに落とし込むと効率的です。

Hook — 自動化の入口

Hookは特定のイベント（ファイル保存後、コマンド実行後など）にスクリプトを自動実行する仕組みです。

Hookの例：

• PostToolUse (Write): .cs ファイルが書かれた直後に dotnet format を走らせてフォーマットを統一
• PostToolUse (Bash): テストを実行した後、結果をログファイルに追記して振り返りやすくする

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "dotnet format [プロジェクトパス] --include $CLAUDE_TOOL_OUTPUT_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Hookは「AIが書いたコードを自動的に整える」用途に向いています。

3. SDD × TDD

2つのアプローチを組み合わせる

自分の開発フローは**SDD（Spec-Driven Development / 仕様駆動開発）とTDD（Test-Driven Development / テスト駆動開発）**を組み合わせたものです。

• SDD: コードを書く前に仕様書を書き、AIにはその仕様書に従って実装させる
• TDD: テストを先に書き、それをパスする最小実装を作る（RED → GREEN → REFACTOR）

イメージとしては、仕様書で「何を作るか」を決め、テストで「正しく動くか」を確認する感じです。

なぜこの組み合わせを使うか

AIコーディングツールの最大の問題は「指示が曖昧なまま実装が行われること」です。AIは曖昧な部分を自分で補完しますが、その補完が意図と全く異なる実装になることも少なくありません。

• SDD：仕様書が「実装の土台」になる。レビューをコードレベルではなく仕様レベルで行えるため、大きな手戻りを防げる。仕様書がそのままドキュメントになる。
• TDD：テストが「完了の定義」になる。AIが書いたコードの正しさをテストで自動検証できる。Modelを純粋C#にしているので、単体テストがしやすい。

実践フロー

1. SPEC      → 仕様書を書く（何を作るかを言語化する）
2. RED       → テストを先に書く（仕様をコードで表現する）
3. GREEN     → テストが通る最小実装を書く
4. REFACTOR  → コードを整理する（テストがGREENのまま）
5. INTEGRATE → PresenterでModelを組み込む
6. VIEW      → ViewとPresenterを接続する
7. MANUAL    → Unity上で動作確認する

ステップ1〜4はModel層だけで完結するので、Unityを一切起動せずにAIと高速にサイクルを回せます。

実践例

あるシステムを実装する場合：

Step 1: 仕様書を書く（SPEC.md）

# XxxSystem 仕様

## 概要
（1〜2行でシステムの目的を説明）

## 状態
- どんなデータを持つか
- 初期値は何か

## 操作
- どんなメソッドを公開するか
- 各メソッドの事前条件・事後条件

## イベント
- 外部に通知するイベント（C# event / IObservable）

## 制約
- アーキテクチャ上の制約（どのレイヤーに属するか等）

Step 2: テストを書いてもらう（RED）

SPEC.mdを読んで、XxxSystemのテストを先に書いてください。
実装はまだ不要です。テストだけ書いてください。

AIが仕様をテストコードに翻訳します。この段階でテストを読んで仕様の解釈がずれていないか確認します。

Step 3: 実装してもらう（GREEN）

テストが通る最小実装を書いてください。
過剰な実装は不要です。

ここでも実装したコードを確認して不備がないかチェックします。

Step 4: テストを実行して確認

Unity MCPの run_tests ツールを使うと、Claude Codeが直接テストを実行して結果を確認できます。

EditModeテストを実行して、全部GREENになっているか確認してください。

Step 5: レビューしてPresenterへ

テストがGREENになったModelをレビューし、問題なければPresenterへの組み込みに進みます。Presenter・View層の接続はアーキテクチャや実装に依存するため、本記事では詳細を割愛します。

4. アーキテクチャ設計 ＋ MVPとModelテスト

なぜアーキテクチャが重要か

Claude Codeに丸投げすると、何の制約もなければMonoBehaviourにすべてのロジックを書いたコードが生成されることがあります（それ自体は間違いではないですが、テストが難しく、AIによる修正も複雑になります）。

アーキテクチャを明示的に定義してCLAUDE.mdに書いておくことで、AIは一貫した設計でコードを生成してくれます。

MVPパターンとテスタビリティ

自分がUnityで使っているのは**MVP（Model-View-Presenter）**パターンです。

Model (Pure C#)
  ↕ IObservable / UniTask
Presenter (Pure C# / minimal MonoBehaviour)
  ↕ インターフェース
View (MonoBehaviour)

Modelを純粋なC#クラスにする最大のメリット：Unityを起動せずにテストできます。

// Model — MonoBehaviour一切なし
public class StageSelectModel : IStageSelectModel
{
    private readonly ReactiveProperty<StageId?> _selectedStage = new();
    public IReadOnlyReactiveProperty<StageId?> SelectedStage => _selectedStage;

    public void SelectStage(StageId id)
    {
        if (!_unlockedStages.Contains(id))
            throw new InvalidOperationException($"Stage {id} is not unlocked.");
        _selectedStage.Value = id;
    }
}

// テスト — Unity Editor不要、dotnet testで動く
[Test]
public void SelectStage_WhenLocked_ThrowsException()
{
    var model = new StageSelectModel(unlockedStages: new[] { StageId.Stage1 });
    Assert.Throws<InvalidOperationException>(() => model.SelectStage(StageId.Stage2));
}

Claude Codeに「Modelはテスト可能な純粋C#クラスにして」と言うだけで、この構造を守って実装してくれます。

Claude Codeにアーキテクチャを伝える方法

CLAUDE.mdに書くのが基本ですが、それに加えて最初の会話でアーキテクチャをどうするかを渡すと精度が上がります（テキストでもいいですが図だともっと良い）：

このプロジェクトのアーキテクチャは以下の通りです。
実装時は必ずこの構造に従ってください。

[Model] → IObservable<T> → [Presenter] → Update View
[View] → User Input → [Presenter] → Call Model Method
[Model] はMonoBehaviourを一切継承しない
[View] はModelを直接参照しない

5. MCP — Unity MCP (CoplayDev)

MCPとは

MCP（Model Context Protocol）は、Claude Codeに外部ツールを接続するための仕組みです。UnityのEditorに接続するMCPを使うと、Claude CodeからUnity Editorを操作したり情報を取得したりできます。

Unity MCP以外にもGitHub MCPなど様々なものがありますが、MCPはTokenを消費するため今のところ自分はそこまで積極的には使っていません。便利な使い方をしている記事をよく見かけるので、そのうち試してみたいと思っています。

Unity MCP (CoplayDev) のセットアップ

自分が使っているのは現在GitHubで最もStarが多いUnity MCPです。MCPごとに特徴があるので、色々試してみると良いと思います。

unity-mcp をUnityプロジェクトにインストールします。

Package Managerから追加:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

最新beta版を使いたい場合は #main を #beta に変えます。

サーバーの起動:

Unity Editor上で Window > MCP for Unity を開いて Start Server をクリックします。localhost:8080 でHTTPサーバーが立ち上がります。

Claude Codeの設定 (.claude/settings.json):

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

設定後、Unity Editor側のウィンドウに🟢 "Connected ✓" が表示されれば接続完了です。

何ができるか

Unity MCPを使うと以下のことがClaude Code経由でできるようになります：

• Hierarchyの確認・操作: シーン内のGameObjectの構造を取得・編集
• コンポーネント情報の取得: 特定のGameObjectにアタッチされているコンポーネントの情報
• コンソールログの取得 (read_console): UnityのConsoleに出ているエラーや警告を取得
• メニュー操作の実行 (execute_menu_item): Assets > Reimport All などのメニュー項目を実行
• テストの実行 (run_tests): Unity Test Runnerのテストを実行して結果を取得
• スクリプト作成・編集 (create_script, manage_script): C#ファイルの作成・検証
• 一括実行 (batch_execute): 複数のMCP操作をまとめて実行（10〜100倍高速）

実際の使い方

コンソールにエラーが出たとき：

Unity Editorのコンソールにあるエラーを確認して、原因と修正方法を提案してください。

これだけで、エラー内容をMCP経由で取得→分析→修正案の提示、という流れが一度の指示で完結します。

注意点

• Unity EditorがPlayモードに入っている間はMCP操作が不安定になることがある
• MCPのセッションはUnity Editorを再起動すると切れる
• SceneファイルのYAMLを直接触らせるのは危険（後述）

6. AIへの指示のコツ

「作って」より「提案して」

❌ PlayerのHPシステムを実装してください
✅ PlayerのHPシステムをどう設計するか、3つの選択肢を提案してください。それぞれのトレードオフも説明してください

まずPlan modeで設計を議論してから実装に移ることで、大きな手戻りを防げます。実装案を考えるときはいくつか案を出してもらい、それぞれのメリット・デメリットも出させると良いと思います。

範囲を明示する

❌ バグを直してください
✅ Assets/Scripts/Model/PlayerModel.cs の SelectStage メソッドのみを修正してください。他のファイルは変更しないでください

Claude Codeは指示された範囲以上のことをしようとすることがあります。「このファイルだけ」「このメソッドだけ」と明示するのが大事です。

ステップを分割する

大きな機能を一度に作らせるより、小さなステップに分割した方が品質が上がります。

1. まずIStageSelectModelインターフェースだけ作ってください
2. 次にStageSelectModelの実装クラスを作ってください（テストも）
3. StageSelectPresenterを作ってください
4. 最後にStageSelectViewを作ってください

既存コードを渡す

以下のコードのスタイルに合わせて実装してください：

[既存コードを貼り付け]

プロジェクト固有のスタイルを習得させる最速の方法です。

「なぜ」を聞く

実装されたコードの設計意図を聞くと、AIが何を考えているか分かります：

このコードでDictionaryを使った理由を教えてください。Listではダメでしたか？

疑問に思ったらすぐ聞く。AIは必ず答えてくれます。これはかなり勉強になるのでおすすめです。

最低限、曖昧な指示を避けることがClaude Codeと付き合う上では重要です。

7. 使用上の注意 ＋ 限界・苦手なこと

⚠️ Gitは自分で管理する

Claude Codeはgit操作もできますが、自分はgit操作をClaude Codeに任せていません。コードの変更をAIに任せるのと、履歴の管理までAIに任せるのは別の話です。

コードを書いてもらったら、差分を確認して、自分でコミットする。これを守っています。

Claude Codeにコードをぐちゃぐちゃにされたときに備えて、GitHubでバージョン管理を必ずしましょう。気をつけていてももしもの時があります。

⚠️ SceneファイルとPrefabのYAMLを直接触らせない

UnityのSceneファイル（.unity）やPrefab（.prefab）はYAML形式ですが、AIがこれを直接編集しようとするとほぼ確実に壊れます。

# ❌ これはやらない
Assets/Scenes/Main.unity を編集して、PlayerオブジェクトのHPを100に変えてください

# ✅ こうする
PlayerオブジェクトのHPを設定するコードを書いてください（SceneやPrefabは自分で編集します）

Scene・Prefabの変更はUnity Editor上で自分が行います。MCPを使えばHierarchyの確認はできますが、変更は慎重に。

⚠️ 出力を必ず確認する

AIが書いたコードは必ずレビューします。特に注意しているのは：

• 存在しないメソッドの呼び出し（ハルシネーション）
• 削除すべきでないコードの削除
• アーキテクチャ違反（ロジックがViewに入っているなど）
• パッケージのバージョン違い（R3 / UniTask / VContainerのAPIが変わっていることがある）

Claude Codeの出力を信頼しすぎないことが、長期的に安全に使い続けるコツです。

⚠️ コンテキストウィンドウの管理

長い会話はコンテキストが積み上がり、古い情報を「忘れる」ことがあります。機能単位でセッションをリセットする（/clearコマンド）のが有効です。

限界・苦手なこと

1. UnityのシリアライズされたデータとEditor統合

SceneファイルやPrefabのYAML、AssetBundleのマニフェスト等、Unityが管理するファイルの直接操作は苦手です。

2. ShaderとGraphicsの最適化

ShaderLabやURPのShaderGraphのコードは書けますが、パフォーマンスチューニングの判断はAIには難しい部分があります。実際に動かして計測する作業は人間が担う必要があります。

3. AnimatorControllerの複雑な遷移

AnimatorControllerの遷移条件やState MachineをコードだけでBuildするのは難しく、大抵はUnity Editorで作業した方が早いです。

4. プラットフォーム固有のビルド設定

iOS/Androidのビルド設定、プラグイン依存関係、Xcodeプロジェクトの設定変更などはAIが最新情報を持っていないことが多いです。公式ドキュメントを参照しながら自分でやる方が確実です。

5. 長期的な「空気を読む」能力

会話が長くなると、最初に決めたアーキテクチャや制約を忘れてしまうことがあります。CLAUDE.mdにルールを書いておくこと、定期的にセッションをリセットすることで対処しています。

---

8. 参考リソース

公式

• Claude Code 公式ドキュメント
• CLAUDE.md リファレンス
• MCP 公式ドキュメント

Unity MCP

• CoplayDev/unity-mcp — 今回紹介したUnity MCP

アーキテクチャ

• VContainer — Unity向けDIコンテナ
• UniTask — UniTask GitHub
• R3 — UniRxの後継、モダンなリアクティブ拡張

ターミナル

• Ghostty
• WezTerm

おわりに

Claude CodeをUnityで使い始めて、「ロジックを書く時間」より「設計を考える時間」が増えたと感じています。これは悪いことではなく、むしろ開発の質が上がっている感覚があります。

AIに実装を任せられるということは、その分だけ「何を作るか・どう設計するか」に集中できるということです。

CLAUDE.md・SDD × TDD・MVPアーキテクチャという組み合わせは、今のところゲーム開発をしている自分にとって一番うまく機能しているやり方です。参考になれば幸いです。

---

この記事は筆者の個人的な研究・開発経験に基づいています。Claude CodeおよびUnityのバージョンアップにより、一部の情報が変更される場合があります。