機能仕様書: Unity Addressablesコマンドサポート

[akiojin]

Spec

機能仕様書: Unity Addressablesコマンドサポート

機能ID: SPEC-a108b8a3
作成日: 2025-11-07
ステータス: 下書き
入力: ユーザー説明: "Unity Addressablesの完全なMCPツールサポートを追加。アセットの動的登録、グループ整理、ビルド自動化、依存関係分析のすべてをLLMエージェントから操作可能にする。"

ユーザーシナリオ＆テスト (必須)

ユーザーストーリー1 - アセットのAddressables登録 (優先度: P1)

LLMエージェントが、Unityプロジェクト内のアセット（プレハブ、マテリアル、テクスチャ等）をAddressablesシステムに登録できる。エージェントは「このプレハブをAddressableとして登録して」と指示されると、該当アセットをAddressablesに追加し、アドレス名やラベルを設定できる。

この優先度の理由: Addressablesの最も基本的な機能であり、他のすべての機能の前提となる。この機能だけでも、手動作業の自動化という価値を提供できる。

独立テスト: 「特定のアセットパスを指定してAddressable登録を実行」することで完全にテストでき、「アセット管理の自動化」という価値を提供する。

受け入れシナリオ:

1. 前提 Unityプロジェクトに未登録のプレハブが存在する、実行 LLMエージェントがそのプレハブをAddressableとして登録する、結果 プレハブがAddressablesシステムに登録され、指定されたアドレス名でアクセス可能になる
2. 前提 Addressableとして登録済みのアセットが存在する、実行 LLMエージェントがそのアセットのアドレス名を変更する、結果 アセットのアドレス名が更新され、新しい名前でアクセス可能になる
3. 前提 Addressableとして登録済みのアセットが存在する、実行 LLMエージェントがそのアセットにラベルを追加する、結果 アセットに指定されたラベルが付与され、ラベル検索で見つけられるようになる
4. 前提 Addressableとして登録済みのアセットが存在する、実行 LLMエージェントがそのアセットをAddressablesから削除する、結果 アセットがAddressablesシステムから削除され、通常のアセットとして扱われる
5. 前提 プロジェクトにAddressableアセットが複数存在する、実行 LLMエージェントが登録済みアセット一覧を取得する、結果 すべての登録済みアセットの情報（パス、アドレス名、ラベル、所属グループ）が返される

---

ユーザーストーリー2 - グループ管理と整理 (優先度: P2)

LLMエージェントが、Addressablesグループを作成・削除し、アセットを適切なグループに整理できる。エージェントは「UI関連のアセットを『UIGroup』にまとめて」と指示されると、新規グループを作成し、該当アセットを移動できる。

この優先度の理由: 複数のアセットを管理する際に不可欠な機能。グループ単位での操作により、大規模プロジェクトでの管理効率が向上する。

独立テスト: 「グループ作成とアセット移動の一連の操作」を実行することで完全にテストでき、「アセット整理の効率化」という価値を提供する。

受け入れシナリオ:

1. 前提 Unityプロジェクトが存在する、実行 LLMエージェントが新しいAddressablesグループを作成する、結果 指定された名前のグループが作成され、グループ一覧に表示される
2. 前提 複数のAddressablesグループが存在する、実行 LLMエージェントがグループ一覧を取得する、結果 すべてのグループ名とその設定情報が返される
3. 前提 Addressableアセットとグループが存在する、実行 LLMエージェントがアセットを別のグループに移動する、結果 アセットの所属グループが変更され、新しいグループ内に表示される
4. 前提 空のAddressablesグループが存在する、実行 LLMエージェントがそのグループを削除する、結果 グループが削除され、グループ一覧から消える

---

ユーザーストーリー3 - ビルドの自動実行 (優先度: P3)

LLMエージェントが、Addressablesのビルドを実行できる。エージェントは「Addressablesをビルドして」と指示されると、すべてのAddressableアセットをパッケージ化し、ビルド結果を報告できる。

この優先度の理由: 開発ワークフローの自動化に貢献する。手動でのビルド操作が不要になり、CI/CD統合の基盤となる。

独立テスト: 「ビルドコマンドを実行し、ビルド結果を確認」することで完全にテストでき、「ビルド作業の自動化」という価値を提供する。

受け入れシナリオ:

1. 前提 Addressableアセットが登録されている、実行 LLMエージェントがAddressablesビルドを実行する、結果 すべてのAddressableアセットがビルドされ、ビルド成功が報告される
2. 前提 Addressablesのビルドキャッシュが存在する、実行 LLMエージェントがビルドキャッシュをクリアする、結果 キャッシュが削除され、次回ビルドがクリーンビルドになる
3. 前提 Addressablesビルドが失敗する可能性がある状態、実行 LLMエージェントがビルドを実行する、結果 エラー内容が詳細に報告され、問題箇所が特定できる

---

ユーザーストーリー4 - 依存関係の分析 (優先度: P4)

LLMエージェントが、Addressablesの依存関係を分析し、重複アセットや未使用アセットを検出できる。エージェントは「重複しているアセットを見つけて」と指示されると、複数のグループに含まれている同じアセットを特定し、最適化の提案ができる。

この優先度の理由: プロジェクトの最適化に役立つが、基本機能が動作していれば後から追加可能。パフォーマンス改善やファイルサイズ削減に貢献する。

独立テスト: 「分析コマンドを実行し、検出された問題を確認」することで完全にテストでき、「アセット最適化の支援」という価値を提供する。

受け入れシナリオ:

1. 前提 複数のグループに同じアセットが含まれている、実行 LLMエージェントが依存関係分析を実行する、結果 重複アセットがリストアップされ、影響範囲が報告される
2. 前提 Addressableアセット間に依存関係が存在する、実行 LLMエージェントが特定アセットの依存関係を解析する、結果 そのアセットが依存している他のアセット一覧が返される
3. 前提 どのAddressableエントリからも参照されていないアセットが存在する、実行 LLMエージェントが未使用アセットを検出する、結果 未使用アセットがリストアップされ、削除候補として提示される

---

エッジケース

• 存在しないアセットパスを指定した場合: エラーメッセージで「指定されたパスのアセットが見つかりません」と明確に通知される
• 既に登録済みのアセットを再度登録しようとした場合: 既存エントリの情報が返され、重複登録は行われない（または、上書き確認のメッセージが表示される）
• 使用中のグループを削除しようとした場合: エラーメッセージで「グループ内にアセットが存在するため削除できません」と通知される
• ビルド中に別のビルドを開始しようとした場合: 「ビルドが既に実行中です」とエラーが返される
• Addressablesパッケージがインストールされていない場合: 「Addressablesパッケージがインストールされていません」と明確なエラーが返される
• アセットのアドレス名が重複した場合: 警告が表示され、一意な名前を提案する

要件 (必須)

機能要件

• FR-001: システムは、LLMエージェントがUnityプロジェクト内の任意のアセットをAddressablesシステムに登録できる必要がある
• FR-002: システムは、登録済みアセットのアドレス名を変更できる必要がある
• FR-003: システムは、アセットにラベルを追加・削除できる必要がある
• FR-004: システムは、Addressableアセットを登録解除できる必要がある
• FR-005: システムは、登録済みAddressableアセットの一覧を取得できる必要がある
• FR-006: システムは、Addressablesグループを作成・削除できる必要がある
• FR-007: システムは、アセットを別のグループに移動できる必要がある
• FR-008: システムは、すべてのAddressablesグループの一覧を取得できる必要がある
• FR-009: システムは、Addressablesのビルドを実行できる必要がある
• FR-010: システムは、Addressablesビルドのキャッシュをクリアできる必要がある
• FR-011: システムは、Addressablesの依存関係を分析できる必要がある
• FR-012: システムは、重複アセットを検出できる必要がある
• FR-013: システムは、未使用アセットを検出できる必要がある
• FR-014: システムは、すべての操作結果をLLMエージェントが理解しやすい形式で返す必要がある
• FR-015: システムは、エラーが発生した場合に詳細なエラー情報を返す必要がある

主要エンティティ

• AddressableEntry: Addressablesに登録されたアセット。アセットパス、アドレス名、ラベル、所属グループの情報を持つ
• AddressablesGroup: アセットをまとめる論理的なグループ。グループ名、ビルド設定、含まれるエントリの情報を持つ
• BuildResult: Addressablesビルドの実行結果。成功/失敗ステータス、ビルド時間、エラー情報を持つ
• AnalysisReport: 依存関係分析の結果。重複アセット、未使用アセット、依存関係グラフの情報を持つ

---

スコープ外 (オプション)

以下の機能は本仕様のスコープ外とし、将来のバージョンで対応予定:

• Addressablesの高度なビルド設定（圧縮方式、プラットフォーム別設定等）のカスタマイズ
• リモートカタログの設定と管理
• Addressablesプロファイルの作成と切り替え
• Content Update Workflowの自動化
• Addressablesのランタイムロード/アンロード操作（これはエディタツールではなくランタイム機能のため）

---

技術制約 (該当する場合)

• Unity Addressablesパッケージ（com.unity.addressables）がプロジェクトにインストールされている必要がある
• Unity Editorが起動している状態でのみ操作可能（PlayMode中は一部操作が制限される可能性がある）
• Addressablesのビルドは、プロジェクトサイズに応じて数秒から数分かかる場合がある

---

前提条件 (該当する場合)

この機能は以下を前提とします:

• Unity Addressablesパッケージがプロジェクトに正しくインストールされている
• AddressableAssetSettingsが初期化されている（初回使用時に自動生成される）
• 既存のMCPサーバーとUnity Editor間の通信機能が正常に動作している

---

依存関係 (該当する場合)

この機能は以下に依存します:

• Unity CLI Bridgeサーバー（既存）
• Unity Editorとの双方向通信機能（既存）
• Unity Addressablesパッケージ（com.unity.addressables）

---

成功基準 (必須)

以下の成功基準を満たす必要があります:

1. LLMエージェントが、5秒以内にアセットのAddressables登録を完了できる
2. LLMエージェントが、100個のアセットを含むグループ一覧を3秒以内に取得できる
3. LLMエージェントが、すべてのAddressables操作を自然言語の指示で実行でき、手動操作が不要になる
4. 依存関係分析が、1000個のアセットを含むプロジェクトで30秒以内に完了する
5. すべてのエラー状況で、エージェントが問題を理解し対処できる詳細なエラーメッセージが返される

---

⚡ クイックガイドライン

• ✅ ユーザーが「何を」必要とし「なぜ」必要なのかに焦点を当てる
• ❌ 「どのように」実装するかを避ける (技術スタック、API、コード構造なし)
• 👥 ビジネス関係者向けに記述 (開発者向けではない)

Plan

実装計画: Unity Addressablesコマンドサポート

機能ID: SPEC-a108b8a3 | 日付: 2025-11-07 | 仕様: ../SPEC-a108b8a3/spec.md
入力: /specs/SPEC-a108b8a3/spec.mdの機能仕様

実行フロー (/speckit.plan コマンドのスコープ)

1. 入力パスから機能仕様を読み込み ✅
2. 技術コンテキストを記入 ✅
3. 憲章チェックセクションを評価 → 進行中
4. Phase 0 を実行 → research.md → 進行中
5. Phase 1 を実行 → contracts, data-model.md, quickstart.md → 進行中
6. 憲章チェックセクションを再評価
7. Phase 2 を計画 → タスク生成アプローチを記述
8. 停止 - /speckit.tasks コマンドの準備完了

概要

Unity AddressablesのフルサポートをMCPツールとして実装。LLMエージェントがUnity Editor経由でAddressables操作を完全に制御可能にする。以下の4つのユーザーストーリーを優先度順に実装：

1. P1: アセット登録管理 - 登録、削除、アドレス名変更、ラベル付与、一覧取得
2. P2: グループ管理 - グループ作成、削除、アセット移動、一覧取得
3. P3: ビルド自動化 - ビルド実行、キャッシュクリア、エラー報告
4. P4: 依存関係分析 - 重複アセット検出、依存関係解析、未使用アセット検出

技術アプローチ: 既存のMCPハンドラーアーキテクチャ（Node.js + Unity Editor C#）を拡張し、Unity Addressables APIをラップして公開。

技術コンテキスト

言語/バージョン: JavaScript (Node.js v18+) + C# (Unity 2021.3+)
主要依存関係:

• Node側: 既存MCPサーバーフレームワーク (BaseToolHandler.js)
• Unity側: Unity Addressablesパッケージ (com.unity.addressables v2.7.4)、Newtonsoft.Json
  ストレージ: N/A (Addressablesの設定はUnityが管理)
  テスト: Jest (Node側 integration tests) + Unity Test Framework (Unity側 contract tests)
  対象プラットフォーム: Unity Editor (Windows/macOS/Linux)
  プロジェクトタイプ: single (MCPサーバー拡張)
  パフォーマンス目標:
• アセット登録: <5秒
• グループ一覧取得(100個): <3秒
• 依存関係分析(1000個): <30秒
  制約:
• Unity Editorが起動している必要がある
• Addressablesパッケージがインストール済み
• TCP JSON-RPC通信経由でのみ操作可能
  スケール/スコープ:
• 単一Unityプロジェクト内のAddressables操作
• 数千個のアセット管理をサポート
• LLMエージェント向けに最適化されたレスポンス

憲章チェック

ゲート: Phase 0 research前に合格必須。Phase 1 design後に再チェック。

シンプルさ:

• プロジェクト数: 1 (MCPサーバー拡張) ✅
• フレームワークを直接使用? Yes - 既存のBaseToolHandler、Unity Addressables APIを直接使用 ✅
• 単一データモデル? Yes - エンティティはJSON-RPCレスポンス形式のみ（DTOなし）✅
• パターン回避? Yes - Repository/UoW不使用、ハンドラーがAddressables APIを直接呼び出し ✅

アーキテクチャ:

• すべての機能をライブラリとして? N/A - これはMCPツール（ハンドラー）であり、ライブラリではない
• ライブラリリスト: N/A
• ライブラリごとのCLI: N/A
• ライブラリドキュメント: N/A

テスト (妥協不可):

• RED-GREEN-Refactorサイクルを強制? Yes - TDD厳守、テストが実装より先 ✅
• Gitコミットはテストが実装より先に表示? Yes - コミット順序: テスト → 実装 ✅
• 順序: Contract→Integration→E2E→Unitを厳密に遵守? Yes ✅
  • Contract tests: Node-Unity間のJSON-RPCインターフェース
  • Integration tests: 実Unity Editor接続
  • Unit tests: Node側のvalidation/formatting
• 実依存関係を使用? Yes - Integration testsは実Unity Editor接続 ✅
• Integration testの対象: 新しいAddressablesハンドラー（新ライブラリ相当）✅
• 禁止: テスト前の実装、REDフェーズのスキップ ✅

可観測性:

• 構造化ロギング含む? Yes - Node側はlogger経由、Unity側はDebug.Log経由 ✅
• フロントエンドログ → バックエンド? N/A - これはUnity Editor拡張
• エラーコンテキスト十分? Yes - エラー時に詳細メッセージ、推奨解決策を返す ✅

バージョニング:

• バージョン番号割り当て済み? Yes - package.jsonで管理（semantic-release自動化）✅
• 変更ごとにBUILDインクリメント? Yes - semantic-releaseが自動実行 ✅
• 破壊的変更を処理? Yes - 新規ツール追加のため破壊的変更なし ✅

プロジェクト構造

ドキュメント (この機能)

specs/SPEC-a108b8a3/
├── spec.md              # 機能仕様書 (完了)
├── plan.md              # このファイル (/speckit.plan コマンド出力)
├── research.md          # Phase 0 出力 (/speckit.plan コマンド) → 作成予定
├── data-model.md        # Phase 1 出力 (/speckit.plan コマンド) → 作成予定
├── quickstart.md        # Phase 1 出力 (/speckit.plan コマンド) → 作成予定
├── contracts/           # Phase 1 出力 (/speckit.plan コマンド) → 作成予定
│   ├── addressables-manage.json  # アセット・グループ管理コマンド契約
│   ├── addressables-build.json   # ビルド関連コマンド契約
│   └── addressables-analyze.json # 依存関係分析コマンド契約
└── tasks.md             # Phase 2 出力 (/speckit.tasks コマンド - /speckit.planでは作成しない)

ソースコード (リポジトリルート)

# Node.js MCPサーバー側
unity-cli/src/handlers/addressables/
├── AddressablesManageToolHandler.js    # アセット・グループ管理ツール (新規)
├── AddressablesBuildToolHandler.js     # ビルド実行ツール (新規)
└── AddressablesAnalyzeToolHandler.js   # 依存関係分析ツール (新規)

unity-cli/src/handlers/index.js        # ハンドラーエクスポート (更新)

# Unity Editor C#側
UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/
└── AddressablesHandler.cs              # Addressables操作の実装 (新規)

# テスト
tests/integration/addressables/
├── addressables-manage.test.js         # アセット・グループ管理テスト (新規)
├── addressables-build.test.js          # ビルドテスト (新規)
└── addressables-analyze.test.js        # 分析テスト (新規)

構造決定: 単一プロジェクト構造 (MCPサーバー拡張)

Phase 0: アウトライン＆リサーチ

リサーチタスク

すべての技術コンテキストは既知であり、事前調査により以下が確認済み：

1. Unity Addressables API: v2.7.4がインストール済み、AddressableAssetSettings APIが利用可能
2. 既存ハンドラーパターン: BaseToolHandler、JSON-RPCプロトコル、Unity CommandHandler統合
3. テストフレームワーク: Jest (Node側)、Unity Test Framework (Unity側)

リサーチ結果

技術選択の理由:

1. ハンドラー分割戦略: 3つのハンドラー

   • 決定: AddressablesManageToolHandler, AddressablesBuildToolHandler, AddressablesAnalyzeToolHandler
   • 理由: 責任分離 - 管理操作、ビルド操作、分析操作は異なるユースケース。各ハンドラーが独立してテスト可能
   • 代替案: 単一のAddressablesToolHandler - 却下理由: 単一ハンドラーが大きくなりすぎる（15+ actions）

2. Unity側の実装: 単一Handler

   • 決定: AddressablesHandler.cs 一つで全操作を実装
   • 理由: Unity側は実装詳細、Node側が責任分離を担う。Unity側はHandleCommand(action, parameters)パターンで統一
   • 代替案: Unity側も分割 - 却下理由: 不要な複雑化、既存パターン（AssetDatabaseHandler等）は単一ファイル

3. JSON-RPCコマンド形式

   • 決定: addressables_manage, addressables_build, addressables_analyze
   • 理由: 既存のコマンド命名規則（manage_asset_database, package_managerr）に準拠
   • 代替案: addressables:manage, addressables/manage - 却下理由: 既存プロトコルとの一貫性

4. エラーハンドリング戦略

   • 決定: Unity側でtry-catchし、{error, message, solution}形式で返す
   • 理由: LLMエージェントが理解しやすく、自己修復可能な形式
   • 代替案: エラーコードのみ - 却下理由: LLM最適化の原則に反する

5. レスポンスページング

   • 決定: 一覧取得系はpageSize, offsetパラメータをサポート
   • 理由: 大規模プロジェクト（1000+ アセット）でのトークン節約
   • 代替案: すべて一括返却 - 却下理由: LLM最適化の原則（憲章VI）に反する

出力: research.md (下記で作成)

Phase 1: 設計＆契約

1. データモデル

主要エンティティ（仕様書から抽出）:

• AddressableEntry: Addressablesに登録されたアセット

  • フィールド: guid, assetPath, address, labels[], groupName
  • 検証: assetPathは存在する必要がある、addressは一意

• AddressablesGroup: アセットをまとめる論理的なグループ

  • フィールド: groupName, buildPath, loadPath, entriesCount
  • 検証: groupNameは一意

• BuildResult: Addressablesビルドの実行結果

  • フィールド: success, duration, outputPath, errors[]
  • 状態遷移: N/A（ステートレス）

• AnalysisReport: 依存関係分析の結果

  • フィールド: duplicates[], unused[], dependencies{}
  • 検証: N/A

詳細はdata-model.mdに記述（下記で作成）。

2. API契約

機能要件（FR-001〜FR-015）から以下のJSON-RPCコマンドを生成：

addressables_manage コマンド

Action	説明	FR
add_entry	アセットをAddressableとして登録	FR-001
remove_entry	Addressableエントリを削除	FR-004
set_address	アドレス名を変更	FR-002
add_label / remove_label	ラベル追加/削除	FR-003
list_entries	登録済みアセット一覧取得	FR-005
list_groups	グループ一覧取得	FR-008
create_group	新規グループ作成	FR-006
remove_group	グループ削除	FR-006
move_entry	エントリを別グループに移動	FR-007

addressables_build コマンド

Action	説明	FR
build	Addressablesビルド実行	FR-009
clean_build	ビルドキャッシュクリア	FR-010

addressables_analyze コマンド

Action	説明	FR
analyze_duplicates	重複アセット検出	FR-012
analyze_dependencies	依存関係解析	FR-011
analyze_unused	未使用アセット検出	FR-013

OpenAPI相当のスキーマは/contracts/に出力（下記で作成）。

3. 契約テスト生成

各コマンドに対して契約テストを作成：

• tests/integration/addressables/addressables-manage.test.js
• tests/integration/addressables/addressables-build.test.js
• tests/integration/addressables/addressables-analyze.test.js

重要: これらのテストは最初に失敗する必要がある（RED）。

4. テストシナリオ抽出

ユーザーストーリーから統合テストシナリオを生成：

• P1 (アセット登録): "プレハブをAddressableとして登録 → アドレス名変更 → ラベル追加 → 一覧取得で確認"
• P2 (グループ管理): "新規グループ作成 → アセット移動 → グループ一覧確認 → グループ削除"
• P3 (ビルド): "アセット登録 → ビルド実行 → 成功確認 → キャッシュクリア"
• P4 (分析): "重複アセット作成 → 分析実行 → 重複検出確認"

詳細はquickstart.mdに記述（下記で作成）。

5. エージェントファイル更新

該当なし（本プロジェクトではCLAUDE.mdが既に存在し、十分に更新されている）。

出力: data-model.md, /contracts/*, 失敗するテスト, quickstart.md

Phase 2: タスク計画アプローチ

このセクションは/speckit.tasksコマンドが実行することを記述 - /speckit.plan中は実行しない

タスク生成戦略:

1. Setup Tasks (環境準備):

   • Addressablesパッケージインストール確認
   • テスト用Unityプロジェクトセットアップ
   • CI環境でのUnity Editor起動確認

2. Contract Test Tasks (TDD: RED):

   • addressables-manage.test.js 作成 [P]
   • addressables-build.test.js 作成 [P]
   • addressables-analyze.test.js 作成 [P]
   • テスト実行 → 失敗確認

3. Core Implementation Tasks (TDD: GREEN):

   • Unity側: AddressablesHandler.cs 実装
     • add_entry, remove_entry, set_address 実装
     • add_label, remove_label, list_entries 実装
     • list_groups, create_group, remove_group 実装
     • move_entry 実装
     • build, clean_build 実装
     • analyze_duplicates, analyze_dependencies, analyze_unused 実装
   • Node側: Handler実装
     • AddressablesManageToolHandler.js 実装 [P]
     • AddressablesBuildToolHandler.js 実装 [P]
     • AddressablesAnalyzeToolHandler.js 実装 [P]
   • unity-cli/src/handlers/index.js 更新 (ハンドラーエクスポート)

4. Integration Test Tasks (TDD: GREEN):

   • Contract tests実行 → 合格確認
   • 各ユーザーストーリーのE2Eシナリオ実行

5. Polish Tasks:

   • エラーメッセージ改善
   • レスポンスページング実装
   • ドキュメント更新 (README.md, README.ja.md)

順序戦略:

• TDD順序: Contract test → Unity実装 → Node実装 → Integration test
• 依存関係順序: Unity側実装が完了してからNode側実装
• 並列実行: Node側の3つのハンドラーは並列実装可能 [P]

推定出力: tasks.mdに35-40個の番号付き、順序付きタスク

重要: このフェーズは/speckit.tasksコマンドで実行、/speckit.planではない

Phase 3+: 今後の実装

これらのフェーズは/planコマンドのスコープ外

Phase 3: タスク実行 (/speckit.tasksコマンドがtasks.mdを作成)
Phase 4: 実装 (憲章原則に従ってtasks.mdを実行)
Phase 5: 検証 (テスト実行、quickstart.md実行、パフォーマンス検証)

複雑さトラッキング

憲章チェックに正当化が必要な違反がある場合のみ記入

違反	必要な理由	より単純な代替案が却下された理由
なし	-	-

すべての憲章要件を満たしており、複雑さの逸脱はありません。

進捗トラッキング

このチェックリストは実行フロー中に更新される

フェーズステータス:

• Phase 0: Research完了 (/speckit.plan コマンド)
• Phase 1: Design完了 (/speckit.plan コマンド)
• Phase 2: Task planning完了 (/speckit.plan コマンド - アプローチのみ記述)
• Phase 3: Tasks生成済み (/speckit.tasks コマンド)
• Phase 4: 実装完了
• Phase 5: 検証合格

ゲートステータス:

• 初期憲章チェック: 合格
• 設計後憲章チェック: 合格
• すべての要明確化解決済み
• 複雑さの逸脱を文書化済み (逸脱なし)

---

憲章 v1.0.0 に基づく - docs/constitution.md 参照

Tasks

タスク: Unity Addressablesコマンドサポート

入力: /specs/SPEC-a108b8a3/の設計ドキュメント
前提条件: plan.md (✅), research.md (✅), data-model.md (✅), contracts/ (✅), quickstart.md (✅)

Phase 3.1: セットアップ

• T001 [P] Addressablesパッケージインストール確認とテスト環境セットアップ

  • ファイル: なし（確認作業）
  • Unity Editorで com.unity.addressables v2.7.4 がインストールされていることを確認
  • UnityCliBridgeプロジェクトの Packages/manifest.json に依存関係が記載されていることを確認
  • UnityCliBridgeプロジェクトを開いてAddressables Windowが表示されることを確認

• T002 [P] Integration testsディレクトリ構造作成

  • ファイル: tests/integration/addressables/ (新規ディレクトリ)
  • tests/integration/addressables/ ディレクトリを作成
  • .gitkeep または README.md を配置

• T003 [P] Node側ハンドラーディレクトリ構造作成

  • ファイル: unity-cli/src/handlers/addressables/ (新規ディレクトリ)
  • unity-cli/src/handlers/addressables/ ディレクトリを作成

Phase 3.2: テストファースト (TDD) ⚠️ 3.3の前に完了必須

重要: これらのテストは記述され、実装前に失敗する必要がある (RED)

• T004 [P] tests/integration/addressables/addressables-manage.test.js に addressables_manage コマンドの contract test

  • ファイル: tests/integration/addressables/addressables-manage.test.js (新規)
  • 10個のアクションをテスト: add_entry, remove_entry, set_address, add_label, remove_label, list_entries, list_groups, create_group, remove_group, move_entry
  • 各アクションで成功ケースとエラーケース（存在しないアセットパス等）をテスト
  • テスト実行 → FAIL (実装がないため)

• T005 [P] tests/integration/addressables/addressables-build.test.js に addressables_build コマンドの contract test

  • ファイル: tests/integration/addressables/addressables-build.test.js (新規)
  • 2個のアクションをテスト: build, clean_build
  • ビルド成功ケース、ビルドキャッシュクリアをテスト
  • テスト実行 → FAIL (実装がないため)

• T006 [P] tests/integration/addressables/addressables-analyze.test.js に addressables_analyze コマンドの contract test

  • ファイル: tests/integration/addressables/addressables-analyze.test.js (新規)
  • 3個のアクションをテスト: analyze_duplicates, analyze_dependencies, analyze_unused
  • 重複検出、依存関係解析、未使用アセット検出をテスト
  • テスト実行 → FAIL (実装がないため)

• T007 すべてのContract testsが失敗することを確認 (RED確認)

  • ファイル: なし（確認作業）
  • npm test tests/integration/addressables/ を実行
  • すべてのテストが FAIL することを確認
  • 失敗ログをスクリーンショット/記録

Phase 3.3: Unity側実装 (テストが失敗した後のみ)

• T008 UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs を作成（スケルトン）

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (新規)
  • using UnityEditor.AddressableAssets; 追加
  • public static class AddressablesHandler クラス定義
  • public static object HandleCommand(string action, JObject parameters) メソッド定義
  • switchステートメントで全actionを列挙（未実装）

• T009 AddressablesHandler: add_entry, remove_entry, set_address 実装

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • AddressableAssetSettings.GetDefault() で設定取得
  • CreateOrMoveEntry() でエントリ追加
  • RemoveAssetEntry() でエントリ削除
  • SetAddress() でアドレス名変更
  • エラーハンドリング（存在しないアセットパス等）

• T010 AddressablesHandler: add_label, remove_label, list_entries 実装

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • SetLabel() でラベル追加/削除
  • 全エントリを列挙してJSON配列で返却
  • ページング実装 (pageSize, offset)

• T011 AddressablesHandler: list_groups, create_group, remove_group, move_entry 実装

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • CreateGroup() でグループ作成
  • RemoveGroup() でグループ削除（空グループのみ）
  • MoveEntry() でエントリを別グループに移動
  • グループ一覧を列挙してJSON配列で返却

• T012 AddressablesHandler: build, clean_build 実装

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • AddressableAssetSettings.BuildPlayerContent() でビルド実行
  • AddressableAssetSettings.CleanPlayerContent() でキャッシュクリア
  • ビルド結果（success, duration, outputPath, errors）を返却

• T013 AddressablesHandler: analyze_duplicates, analyze_dependencies, analyze_unused 実装

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • 重複アセット検出ロジック実装
  • 依存関係解析（AssetDatabase.GetDependencies使用）
  • 未使用アセット検出ロジック実装

• T014 Unity側でUnityCliBridgeにAddressablesHandlerをルーティング

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Core/UnityCliBridge.cs (更新)
  • addressables_manage, addressables_build, addressables_analyze コマンドを AddressablesHandler にルーティング
  • switchステートメントまたはディスパッチャーに追加

Phase 3.4: Node側実装 (Unity側実装完了後)

• T015 [P] unity-cli/src/handlers/addressables/AddressablesManageToolHandler.js 実装

  • ファイル: unity-cli/src/handlers/addressables/AddressablesManageToolHandler.js (新規)
  • BaseToolHandlerを継承
  • ツール名: addressables_manage
  • JSON Schemaでリクエストパラメータを定義（contracts/addressables-manage.jsonに準拠）
  • validate()メソッドでパラメータ検証
  • execute()メソッドでUnity接続経由でコマンド送信
  • formatResponse()メソッドでレスポンス整形

• T016 [P] unity-cli/src/handlers/addressables/AddressablesBuildToolHandler.js 実装

  • ファイル: unity-cli/src/handlers/addressables/AddressablesBuildToolHandler.js (新規)
  • BaseToolHandlerを継承
  • ツール名: addressables_build
  • JSON Schemaでリクエストパラメータを定義（contracts/addressables-build.jsonに準拠）
  • タイムアウトを5分に設定（ビルドは時間がかかる）
  • validate(), execute(), formatResponse() 実装

• T017 [P] unity-cli/src/handlers/addressables/AddressablesAnalyzeToolHandler.js 実装

  • ファイル: unity-cli/src/handlers/addressables/AddressablesAnalyzeToolHandler.js (新規)
  • BaseToolHandlerを継承
  • ツール名: addressables_analyze
  • JSON Schemaでリクエストパラメータを定義（contracts/addressables-analyze.jsonに準拠）
  • validate(), execute(), formatResponse() 実装

• T018 unity-cli/src/handlers/index.js で新規ハンドラーをエクスポート

  • ファイル: unity-cli/src/handlers/index.js (更新)
  • AddressablesManageToolHandler, AddressablesBuildToolHandler, AddressablesAnalyzeToolHandler をimport
  • exportリストに追加

• T019 MCPサーバーで新規ツールを登録

  • ファイル: unity-cli/src/core/server.js または該当する登録箇所 (更新)
  • 新規ハンドラーをツールリストに登録
  • MCPサーバー再起動で3つの新規ツールが利用可能になることを確認

Phase 3.5: Integration Tests実行 (GREEN確認)

• T020 すべてのContract testsが合格することを確認 (GREEN確認)

  • ファイル: なし（確認作業）
  • Unity Editorが起動していることを確認
  • MCPサーバーが起動していることを確認
  • npm test tests/integration/addressables/ を実行
  • すべてのテストが PASS することを確認
  • 1つでも失敗した場合は実装に戻る

• T021 quickstart.mdのP1シナリオ（アセット登録管理）を手動実行

  • ファイル: specs/SPEC-a108b8a3/quickstart.md (参照)
  • プレハブをAddressableとして登録
  • アドレス名変更
  • ラベル追加
  • 一覧取得で確認

• T022 quickstart.mdのP2シナリオ（グループ管理）を手動実行

  • ファイル: specs/SPEC-a108b8a3/quickstart.md (参照)
  • 新規グループ作成
  • アセット移動
  • グループ一覧確認
  • グループ削除

• T023 quickstart.mdのP3シナリオ（ビルド自動化）を手動実行

  • ファイル: specs/SPEC-a108b8a3/quickstart.md (参照)
  • Addressablesビルド実行
  • 成功確認
  • キャッシュクリア

• T024 quickstart.mdのP4シナリオ（依存関係分析）を手動実行

  • ファイル: specs/SPEC-a108b8a3/quickstart.md (参照)
  • 重複アセット作成
  • 分析実行
  • 重複検出確認

Phase 3.6: 仕上げ

• T025 [P] エラーハンドリング強化とLLM最適化

  • ファイル: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AddressablesHandler.cs (更新)
  • すべてのエラーケースで {error, message, solution, context} 形式で返却
  • エラーメッセージを日本語化
  • 推奨解決策を明示

• T026 [P] ページング機能の検証とトークン最適化

  • ファイル: unity-cli/src/handlers/addressables/*.js (更新)
  • list_entries, list_groups, analyze_duplicates, analyze_unused のページングが正しく動作することを確認
  • デフォルトpageSize=20を確認
  • 大規模プロジェクト（100+アセット）でテスト

• T027 [P] 構造化ロギング追加

  • ファイル: unity-cli/src/handlers/addressables/*.js (更新)
  • Node側で logger を使用してコマンド実行ログを記録
  • Unity側で Debug.Log を使用してAddressables操作ログを記録
  • エラー時のスタックトレース記録

• T028 [P] README.md更新（新規ツール追加の記載）

  • ファイル: README.md (更新)
  • "Available Tools" セクションに addressables_manage, addressables_build, addressables_analyze を追加
  • 簡単な使用例を記載

• T029 [P] README.ja.md更新（新規ツール追加の記載）

  • ファイル: README.ja.md (更新)
  • "利用可能なツール" セクションに addressables_manage, addressables_build, addressables_analyze を追加
  • 簡単な使用例を記載（日本語）

• T030 リファクタリング: 重複コード削除とクリーンアップ

  • ファイル: すべての実装ファイル (更新)
  • DRY原則に従って重複コードを削除
  • コメント追加
  • 不要なデバッグコード削除

• T031 パフォーマンス検証

  • ファイル: なし（検証作業）
  • アセット登録: <5秒を確認
  • グループ一覧取得(100個): <3秒を確認
  • 依存関係分析(1000個): <30秒を確認
  • 不合格の場合は最適化を実施

依存関係

• Setup (T001-T003) が Tests (T004-T007) をブロック
• Tests (T004-T007) が Implementation (T008-T019) より先（TDD必須）
• T007 (RED確認) が T008 (実装開始) をブロック
• Unity側実装 (T008-T014) が Node側実装 (T015-T019) をブロック
• Implementation (T008-T019) が Integration Tests実行 (T020-T024) より先
• T020 (GREEN確認) が Polish (T025-T031) をブロック

並列実行例

Phase 3.1: Setup (すべて並列実行可能)

T001, T002, T003

Phase 3.2: Tests (すべて並列実行可能)

T004, T005, T006

Phase 3.4: Node側実装 (すべて並列実行可能)

T015, T016, T017

Phase 3.6: Polish (一部並列実行可能)

T025, T026, T027 (並列)
T028, T029 (並列)

注意事項

• [P] タスク = 異なるファイル、依存関係なし、並列実行可能
• TDD厳守: T007でREDを確認してからT008以降の実装を開始
• T020でGREEN確認: すべてのテストが合格するまで実装を繰り返す
• 各タスク完了後に日本語でコミット（Conventional Commits準拠）
• エラーが発生している状態で完了としない

タスク完全性検証

• すべてのcontracts (3ファイル) に対応するテストがある → T004, T005, T006
• すべてのactions (15個) にUnity側実装がある → T009-T013
• すべてのhandlers (3個) にNode側実装がある → T015-T017
• すべてのテストが実装より先にある → T004-T007 → T008-T019
• 並列タスクは本当に独立している → T001-T003, T004-T006, T015-T017等
• 各タスクは正確なファイルパスを指定 → すべてのタスクにファイルパス記載
• 同じファイルを変更する[P]タスクがない → 確認済み

TDD

TODO

Research

リサーチ結果: Unity Addressablesコマンドサポート

機能ID: SPEC-a108b8a3 | 日付: 2025-11-07

技術決定

1. ハンドラー分割戦略: 3つのハンドラー

決定: Node側で3つの独立したハンドラーを実装

• AddressablesManageToolHandler.js - アセット・グループ管理
• AddressablesBuildToolHandler.js - ビルド操作
• AddressablesAnalyzeToolHandler.js - 依存関係分析

理由:

• 責任分離: 各ハンドラーが明確な責任を持つ（管理/ビルド/分析）
• 独立テスト: 各ハンドラーを独立してテスト可能
• 保守性: 小さなファイルで管理が容易
• 既存パターン準拠: 既存のAsset*ToolHandlerパターンと一貫性

検討した代替案:

1. 単一AddressablesToolHandler
   • 却下理由: 15+ actionsを持つ大きなファイルになる。保守性が低下
2. 5つ以上のハンドラー（操作ごと）
   • 却下理由: 過度な分割、ファイル数の増加

2. Unity側の実装: 単一Handler

決定: AddressablesHandler.cs 一つで全操作を実装

理由:

• 既存パターン準拠: AssetDatabaseHandler.cs, PackageManagerHandler.cs等と同じパターン
• Unity側は実装詳細: Node側が責任分離を担い、Unity側は実行のみ
• シンプルさ: HandleCommand(action, parameters)パターンで統一
• Addressables APIの凝集性: すべてUnityEditor.AddressableAssets名前空間内

検討した代替案:

1. Unity側も3つのハンドラーに分割
   • 却下理由: 不要な複雑化、Unity側は既存パターンで単一ファイル

3. JSON-RPCコマンド形式

決定: 以下の3つのコマンド

• addressables_manage
• addressables_build
• addressables_analyze

理由:

• 既存命名規則準拠: manage_asset_database, package_managerr, load_scene等と一貫性
• スネークケース: MCPサーバーの標準
• 動詞_名詞パターン: 操作が明確

検討した代替案:

1. addressables:manage (コロン区切り)
   • 却下理由: 既存プロトコルと非一貫
2. addressables/manage (スラッシュ区切り)
   • 却下理由: コマンド名ではなくパスのように見える

4. エラーハンドリング戦略

決定: 構造化エラーレスポンス

{
  "error": true,
  "message": "指定されたパスのアセットが見つかりません",
  "solution": "Assets/Prefabs/Player.prefab が存在するか確認してください",
  "assetPath": "Assets/Prefabs/Player.prefab"
}

理由:

• LLM最適化: エージェントが自己修復可能な詳細情報
• 憲章VI準拠: エラーメッセージは解決策を明示
• デバッグ容易性: コンテキスト情報を含む

検討した代替案:

1. エラーコードのみ
   • 却下理由: LLMが理解しにくい、憲章違反
2. 例外スローのみ
   • 却下理由: Unity側でクラッシュする可能性

5. レスポンスページング

決定: 一覧取得系APIにpageSize, offsetパラメータを追加

理由:

• トークン節約: 大規模プロジェクトで1000+ アセットがある場合
• 憲章VI準拠: "大きな出力は常にページング可能"
• デフォルト制限: pageSize=20 (憲章推奨値)

実装対象:

• list_entries (アセット一覧)
• list_groups (グループ一覧)
• analyze_duplicates (重複アセット一覧)
• analyze_unused (未使用アセット一覧)

検討した代替案:

1. すべて一括返却
   • 却下理由: 大規模プロジェクトでトークン浪費、憲章違反

Unity Addressables API調査

使用するAPIクラス

クラス	用途	主要メソッド
AddressableAssetSettings	設定取得	GetDefault(), CreateGroup(), CreateOrMoveEntry()
AddressableAssetGroup	グループ管理	AddAssetEntry(), RemoveAssetEntry()
AddressableAssetEntry	エントリ管理	SetAddress(), SetLabel()
AddressableAssetSettingsDefaultObject	デフォルト設定	Settings (singleton)
AddressablesPlayerBuildResult	ビルド結果	Error, Duration, OutputPath

API制約

1. Unity Editorのみ: ランタイムでは使用不可
2. PlayMode制限: 一部の操作はPlayMode中に制限される可能性
3. 非同期操作: ビルドは非同期で実行される（進捗監視が必要）

テストフレームワーク

Node側: Jest

選定理由:

• 既存テストで使用済み
• 非同期テスト、モック、スナップショットテストをサポート

Unity側: Unity Test Framework

選定理由:

• Unity公式テストフレームワーク
• EditModeテストでAddressables APIをテスト可能

依存関係

依存	バージョン	必須/任意	備考
com.unity.addressables	2.7.4	必須	Unity Package Manager経由でインストール済み
com.unity.nuget.newtonsoft-json	3.2.1	必須	JSON処理（既存依存）
@modelcontextprotocol/sdk	latest	必須	MCPサーバーSDK（既存依存）
jest	latest	必須	テストフレームワーク（既存依存）

パフォーマンス検証計画

操作	目標	測定方法
アセット登録	<5秒	Unity Profiler + Node側タイムスタンプ
グループ一覧取得(100個)	<3秒	Node側レスポンスタイム測定
依存関係分析(1000個)	<30秒	Unity Addressables AnalyzeRule実行時間

リスクと緩和策

リスク	影響	緩和策
Addressablesパッケージ未インストール	高	初回コマンド実行時に明確なエラーメッセージ
PlayMode中の操作制限	中	PlayMode検出とエラーメッセージ
ビルドの長時間実行	中	タイムアウト設定（デフォルト30秒→ビルドは5分）
大量アセットでのメモリ不足	低	ページング実装で緩和

参考資料

• Unity Addressables 公式ドキュメント: https://docs.unity3d.com/Packages/com.unity.addressables@2.7/manual/
• AddressableAssetSettings API: https://docs.unity3d.com/Packages/com.unity.addressables@2.7/api/UnityEditor.AddressableAssets.Settings.AddressableAssetSettings.html
• 既存MCPハンドラー実装: unity-cli/src/handlers/asset/AssetDatabaseManageToolHandler.js
• 既存Unity Handler実装: UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/AssetDatabaseHandler.cs

Data Model

データモデル: Unity Addressablesコマンドサポート

機能ID: SPEC-a108b8a3 | 日付: 2025-11-07

エンティティ定義

すべてのエンティティはJSON-RPCレスポンスとして返却される。DTOクラスは作成せず、JSON形式で直接返却。

1. AddressableEntry

Addressablesに登録されたアセットを表す。

フィールド:

フィールド	型	必須	説明	制約
guid	string	✅	アセットのGUID	Unity内で一意
assetPath	string	✅	Assets/から始まるパス	実在するアセット
address	string	✅	Addressable名	プロジェクト内で一意
labels	string[]	✅	ラベル一覧	空配列可
groupName	string	✅	所属グループ名	既存グループ

例:

{
  "guid": "a1b2c3d4e5f6",
  "assetPath": "Assets/Prefabs/Player.prefab",
  "address": "Prefabs/Player",
  "labels": ["Essential", "Character"],
  "groupName": "Default Local Group"
}

検証ルール:

• assetPathはAssetDatabase.AssetPathToGUID()で解決可能
• addressはプロジェクト内で一意（重複時は警告）
• groupNameは既存のグループに対応

状態遷移: N/A（ステートレス）

---

2. AddressablesGroup

アセットをまとめる論理的なグループを表す。

フィールド:

フィールド	型	必須	説明	制約
groupName	string	✅	グループ名	プロジェクト内で一意
buildPath	string	✅	ビルド出力パス	相対パス
loadPath	string	✅	ロードパス	URL形式またはローカルパス
entriesCount	number	✅	含まれるエントリ数	>= 0

例:

{
  "groupName": "UI Assets",
  "buildPath": "ServerData/[BuildTarget]",
  "loadPath": "{UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]",
  "entriesCount": 42
}

検証ルール:

• groupNameはプロジェクト内で一意
• buildPath, loadPathはAddressables設定で有効なパス

状態遷移: N/A（ステートレス）

---

3. BuildResult

Addressablesビルドの実行結果を表す。

フィールド:

フィールド	型	必須	説明	制約
success	boolean	✅	ビルド成功/失敗	true/false
duration	number	✅	ビルド時間（秒）	>= 0
outputPath	string	✅	出力ディレクトリ	絶対パス
errors	string[]	✅	エラーメッセージ一覧	空配列可

例（成功時）:

{
  "success": true,
  "duration": 12.34,
  "outputPath": "/path/to/ServerData/StandaloneWindows64",
  "errors": []
}

例（失敗時）:

{
  "success": false,
  "duration": 5.67,
  "outputPath": "",
  "errors": [
    "Missing asset reference in group 'UI Assets'",
    "Build script execution failed"
  ]
}

検証ルール: なし（読み取り専用）

状態遷移: N/A（ステートレス、ビルドごとに新規作成）

---

4. AnalysisReport

依存関係分析の結果を表す。

フィールド:

フィールド	型	必須	説明	制約
duplicates	DuplicateEntry[]	✅	重複アセット一覧	空配列可
unused	string[]	✅	未使用アセット一覧	空配列可
dependencies	object	✅	依存関係マップ	key=assetPath, value=依存先paths[]

サブエンティティ: DuplicateEntry:

フィールド	型	必須	説明
assetPath	string	✅	アセットパス
groups	string[]	✅	含まれるグループ名一覧

例:

{
  "duplicates": [
    {
      "assetPath": "Assets/Textures/Icon.png",
      "groups": ["UI Assets", "Character Assets"]
    }
  ],
  "unused": [
    "Assets/Prefabs/Deprecated/OldPlayer.prefab"
  ],
  "dependencies": {
    "Assets/Prefabs/Player.prefab": [
      "Assets/Materials/PlayerMaterial.mat",
      "Assets/Textures/PlayerTexture.png"
    ]
  }
}

検証ルール: なし（読み取り専用）

状態遷移: N/A（ステートレス）

---

エンティティ間の関係

AddressablesGroup (1) ---< (*) AddressableEntry

• 1つのGroupは複数のEntryを持つ
• 1つのEntryは1つのGroupに所属

AddressableEntry ---depends-on---> * Assets (依存関係)

• 1つのEntryは複数のアセットに依存可能（AnalysisReportで解析）

---

JSON-RPCレスポンス形式

成功レスポンス

{
  "success": true,
  "data": <Entity or Entity[]>,
  "message": "Operation completed successfully"
}

エラーレスポンス

{
  "success": false,
  "error": "指定されたパスのアセットが見つかりません",
  "solution": "Assets/Prefabs/Player.prefab が存在するか確認してください",
  "context": {
    "assetPath": "Assets/Prefabs/Player.prefab",
    "action": "add_entry"
  }
}

ページング対応レスポンス

{
  "success": true,
  "data": <Entity[]>,
  "pagination": {
    "offset": 0,
    "pageSize": 20,
    "total": 150,
    "hasMore": true
  }
}

---

バリデーションルール

共通ルール

1. 必須フィールド: すべての必須フィールドはnullまたは空文字列を許可しない
2. 文字列長: アセットパス、アドレス名、グループ名は1文字以上
3. 一意性: GUID、address、groupNameはプロジェクト内で一意

アセットパス検証

bool IsValidAssetPath(string assetPath)
{
    return assetPath.StartsWith("Assets/")
        && AssetDatabase.AssetPathToGUID(assetPath) != "";
}

アドレス名検証

bool IsValidAddress(string address)
{
    return !string.IsNullOrWhiteSpace(address)
        && !address.Contains(" ") // スペース禁止
        && address.Length <= 256;
}

グループ名検証

bool IsValidGroupName(string groupName)
{
    return !string.IsNullOrWhiteSpace(groupName)
        && groupName.Length <= 128;
}

---

LLM最適化

トークン節約

• ページング: デフォルトpageSize=20
• 省略可能フィールド: buildPath, loadPathはverbose=trueの時のみ返却
• 要約モード: 100件以上のエントリは自動的に要約

エラーメッセージ

• 詳細レベル: 常にerror, solution, contextを含む
• 多言語: 日本語優先、英語フォールバック
• LLM理解可能: "次に〜してください"形式

---

実装ノート

• シリアライゼーション: Newtonsoft.Jsonを使用（Unity標準）
• null許容: C#側ではnullチェック必須、JSON側ではnullを許可しない
• enum: Unity側のenumはJSON側では文字列に変換

Quickstart

クイックスタート: Unity Addressablesコマンドサポート

機能ID: SPEC-a108b8a3 | 日付: 2025-11-07

前提条件

1. Unity Editor起動済み
2. Unity Addressablesパッケージ (com.unity.addressables v2.7.4) インストール済み
3. Unity CLI Bridge Server起動済み、Unity Editorと接続済み

テストシナリオ（ユーザーストーリー検証）

P1: アセット登録管理

目的: プレハブをAddressableとして登録し、アドレス名変更、ラベル追加、一覧取得を行う。

ステップ1: プレハブをAddressableとして登録

リクエスト:

{
  "command": "addressables_manage",
  "action": "add_entry",
  "assetPath": "Assets/Prefabs/Player.prefab",
  "address": "Prefabs/Player",
  "groupName": "Default Local Group"
}

期待結果:

{
  "success": true,
  "data": {
    "guid": "a1b2c3d4e5f6",
    "assetPath": "Assets/Prefabs/Player.prefab",
    "address": "Prefabs/Player",
    "labels": [],
    "groupName": "Default Local Group"
  }
}

検証: Unity Addressables Windowでエントリが表示される。

---

ステップ2: アドレス名を変更

リクエスト:

{
  "command": "addressables_manage",
  "action": "set_address",
  "assetPath": "Assets/Prefabs/Player.prefab",
  "newAddress": "Characters/Player"
}

期待結果:

{
  "success": true,
  "data": {
    "guid": "a1b2c3d4e5f6",
    "assetPath": "Assets/Prefabs/Player.prefab",
    "address": "Characters/Player",
    "labels": [],
    "groupName": "Default Local Group"
  }
}

検証: Addressables Windowでアドレス名が変更されている。

---

ステップ3: ラベルを追加

リクエスト:

{
  "command": "addressables_manage",
  "action": "add_label",
  "assetPath": "Assets/Prefabs/Player.prefab",
  "label": "Essential"
}

期待結果:

{
  "success": true,
  "data": {
    "guid": "a1b2c3d4e5f6",
    "assetPath": "Assets/Prefabs/Player.prefab",
    "address": "Characters/Player",
    "labels": ["Essential"],
    "groupName": "Default Local Group"
  }
}

検証: Addressables Windowでラベルが表示される。

---

ステップ4: 登録済みアセット一覧を取得

リクエスト:

{
  "command": "addressables_manage",
  "action": "list_entries",
  "groupName": "Default Local Group",
  "pageSize": 20,
  "offset": 0
}

期待結果:

{
  "success": true,
  "data": [
    {
      "guid": "a1b2c3d4e5f6",
      "assetPath": "Assets/Prefabs/Player.prefab",
      "address": "Characters/Player",
      "labels": ["Essential"],
      "groupName": "Default Local Group"
    }
  ],
  "pagination": {
    "offset": 0,
    "pageSize": 20,
    "total": 1,
    "hasMore": false
  }
}

検証: 登録したエントリが一覧に含まれる。

---

P2: グループ管理

目的: 新規グループを作成し、アセットを移動、グループ一覧確認、グループ削除を行う。

ステップ1: 新規グループを作成

リクエスト:

{
  "command": "addressables_manage",
  "action": "create_group",
  "groupName": "UI Assets"
}

期待結果:

{
  "success": true,
  "data": {
    "groupName": "UI Assets",
    "buildPath": "ServerData/[BuildTarget]",
    "loadPath": "{UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]",
    "entriesCount": 0
  }
}

検証: Addressables Windowで新規グループが表示される。

---

ステップ2: アセットを別グループに移動

リクエスト:

{
  "command": "addressables_manage",
  "action": "move_entry",
  "assetPath": "Assets/Prefabs/Player.prefab",
  "targetGroupName": "UI Assets"
}

期待結果:

{
  "success": true,
  "data": {
    "guid": "a1b2c3d4e5f6",
    "assetPath": "Assets/Prefabs/Player.prefab",
    "address": "Characters/Player",
    "labels": ["Essential"],
    "groupName": "UI Assets"
  }
}

検証: Addressables Windowでアセットが"UI Assets"グループに移動している。

---

ステップ3: グループ一覧を取得

リクエスト:

{
  "command": "addressables_manage",
  "action": "list_groups",
  "pageSize": 20,
  "offset": 0
}

期待結果:

{
  "success": true,
  "data": [
    {
      "groupName": "Default Local Group",
      "buildPath": "ServerData/[BuildTarget]",
      "loadPath": "{UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]",
      "entriesCount": 0
    },
    {
      "groupName": "UI Assets",
      "buildPath": "ServerData/[BuildTarget]",
      "loadPath": "{UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]",
      "entriesCount": 1
    }
  ],
  "pagination": {
    "offset": 0,
    "pageSize": 20,
    "total": 2,
    "hasMore": false
  }
}

検証: 両方のグループが一覧に含まれる。

---

ステップ4: 空のグループを削除

前提: アセットを元のグループに戻す（またはクリーンアップ用の空グループを作成）

リクエスト:

{
  "command": "addressables_manage",
  "action": "remove_group",
  "groupName": "UI Assets"
}

期待結果:

{
  "success": true,
  "message": "グループ 'UI Assets' を削除しました"
}

検証: Addressables Windowでグループが削除されている。

---

P3: ビルド自動化

目的: アセット登録後にAddressablesビルドを実行し、成功確認、キャッシュクリアを行う。

ステップ1: アセットを登録

（P1のステップ1と同じ）

---

ステップ2: Addressablesビルドを実行

リクエスト:

{
  "command": "addressables_build",
  "action": "build"
}

期待結果 (成功時):

{
  "success": true,
  "data": {
    "success": true,
    "duration": 12.34,
    "outputPath": "/path/to/ServerData/StandaloneWindows64",
    "errors": []
  }
}

検証: outputPathディレクトリにビルド成果物（.bundle, catalog.json等）が存在する。

---

ステップ3: ビルドキャッシュをクリア

リクエスト:

{
  "command": "addressables_build",
  "action": "clean_build"
}

期待結果:

{
  "success": true,
  "message": "ビルドキャッシュをクリアしました"
}

検証: Library/com.unity.addressables/ディレクトリが削除されている。

---

P4: 依存関係分析

目的: 重複アセットを作成し、分析実行、重複検出を確認する。

ステップ1: 重複アセット状態を作成

前提: 同じアセットを2つの異なるグループに登録

1. Assets/Textures/Icon.pngを"Default Local Group"に登録
2. Assets/Textures/Icon.pngを"UI Assets"に登録

---

ステップ2: 重複アセットを検出

リクエスト:

{
  "command": "addressables_analyze",
  "action": "analyze_duplicates"
}

期待結果:

{
  "success": true,
  "data": {
    "duplicates": [
      {
        "assetPath": "Assets/Textures/Icon.png",
        "groups": ["Default Local Group", "UI Assets"]
      }
    ],
    "unused": [],
    "dependencies": {}
  }
}

検証: 重複アセットが検出される。

---

ステップ3: 依存関係を解析

リクエスト:

{
  "command": "addressables_analyze",
  "action": "analyze_dependencies",
  "assetPath": "Assets/Prefabs/Player.prefab"
}

期待結果:

{
  "success": true,
  "data": {
    "duplicates": [],
    "unused": [],
    "dependencies": {
      "Assets/Prefabs/Player.prefab": [
        "Assets/Materials/PlayerMaterial.mat",
        "Assets/Textures/PlayerTexture.png"
      ]
    }
  }
}

検証: プレハブが依存しているアセットが一覧表示される。

---

ステップ4: 未使用アセットを検出

リクエスト:

{
  "command": "addressables_analyze",
  "action": "analyze_unused"
}

期待結果:

{
  "success": true,
  "data": {
    "duplicates": [],
    "unused": [
      "Assets/Prefabs/Deprecated/OldPlayer.prefab"
    ],
    "dependencies": {}
  }
}

検証: どのAddressableエントリからも参照されていないアセットが検出される。

---

エラーケーステスト

存在しないアセットパスを指定

リクエスト:

{
  "command": "addressables_manage",
  "action": "add_entry",
  "assetPath": "Assets/Prefabs/NonExistent.prefab",
  "address": "Test/NonExistent",
  "groupName": "Default Local Group"
}

期待結果:

{
  "success": false,
  "error": "指定されたパスのアセットが見つかりません",
  "solution": "Assets/Prefabs/NonExistent.prefab が存在するか確認してください",
  "context": {
    "assetPath": "Assets/Prefabs/NonExistent.prefab",
    "action": "add_entry"
  }
}

---

Addressablesパッケージ未インストール

期待結果:

{
  "success": false,
  "error": "Addressablesパッケージがインストールされていません",
  "solution": "Unity Package Managerから com.unity.addressables をインストールしてください",
  "context": {
    "action": "add_entry"
  }
}

---

自動テスト実行

# Integration testsを実行
cd unity-cli
npm test tests/integration/addressables/

期待: すべてのテストがパス。

---

パフォーマンス検証

操作	目標	実測値	合格/不合格
アセット登録	<5秒	（測定予定）	-
グループ一覧取得(100個)	<3秒	（測定予定）	-
依存関係分析(1000個)	<30秒	（測定予定）	-

---

トラブルシューティング

Q: Unity Editorが応答しない

A: Unity Editorを再起動し、MCPサーバーとの接続を再確立してください。

Q: ビルドが失敗する

A: Unity Console Logを確認し、エラーメッセージを確認してください。ビルドエラーはレスポンスのerrors配列に含まれます。

Q: ページングが動作しない

A: pageSize, offsetパラメータが正しく指定されているか確認してください。デフォルト値はそれぞれ20, 0です。

Contracts

Migrated from local files. See artifact comments below.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

• Add acceptance checklist

[akiojin]

contract:addressables-analyze.json

{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Addressables Analysis Contract",
"description": "JSON-RPC contract for Unity Addressables dependency analysis operations",
"command": "addressables_analyze",
"actions": {
"analyze_duplicates": {
"description": "Analyze and find duplicate assets across groups",
"request": {
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "analyze_duplicates"
},
"pageSize": {
"type": "integer",
"description": "Number of results per page",
"default": 20,
"minimum": 1,
"maximum": 100
},
"offset": {
"type": "integer",
"description": "Offset for pagination",
"default": 0,
"minimum": 0
}
},
"required": ["action"]
},
"response": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"$ref": "#/definitions/AnalysisReport"
},
"pagination": {
"$ref": "#/definitions/Pagination"
}
},
"required": ["success", "data"]
}
},
"analyze_dependencies": {
"description": "Analyze dependencies for a specific asset",
"request": {
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "analyze_dependencies"
},
"assetPath": {
"type": "string",
"description": "Asset path to analyze",
"pattern": "^Assets/.+"
}
},
"required": ["action", "assetPath"]
},
"response": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"$ref": "#/definitions/AnalysisReport"
}
},
"required": ["success", "data"]
}
},
"analyze_unused": {
"description": "Find unused assets (not referenced by any Addressable entry)",
"request": {
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "analyze_unused"
},
"pageSize": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
}
},
"required": ["action"]
},
"response": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"$ref": "#/definitions/AnalysisReport"
},
"pagination": {
"$ref": "#/definitions/Pagination"
}
},
"required": ["success", "data"]
}
}
},
"definitions": {
"AnalysisReport": {
"type": "object",
"properties": {
"duplicates": {
"type": "array",
"items": {
"$ref": "#/definitions/DuplicateEntry"
},
"description": "List of duplicate assets found across groups"
},
"unused": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of unused asset paths"
},
"dependencies": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Dependency map: key=assetPath, value=array of dependent asset paths"
}
},
"required": ["duplicates", "unused", "dependencies"]
},
"DuplicateEntry": {
"type": "object",
"properties": {
"assetPath": {
"type": "string",
"description": "Asset path that is duplicated"
},
"groups": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of group names containing this asset",
"minItems": 2
}
},
"required": ["assetPath", "groups"]
},
"Pagination": {
"type": "object",
"properties": {
"offset": {
"type": "integer",
"minimum": 0
},
"pageSize": {
"type": "integer",
"minimum": 1
},
"total": {
"type": "integer",
"description": "Total number of items",
"minimum": 0
},
"hasMore": {
"type": "boolean",
"description": "Whether there are more items beyond this page"
}
},
"required": ["offset", "pageSize", "total", "hasMore"]
}
}
}

[akiojin]

contract:addressables-build.json

{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Addressables Build Contract",
"description": "JSON-RPC contract for Unity Addressables build operations",
"command": "addressables_build",
"actions": {
"build": {
"description": "Build Addressables content",
"request": {
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "build"
},
"buildTarget": {
"type": "string",
"description": "Optional build target (e.g., StandaloneWindows64)",
"enum": [
"StandaloneWindows64",
"StandaloneWindows",
"StandaloneLinux64",
"StandaloneOSX",
"iOS",
"Android",
"WebGL"
]
}
},
"required": ["action"]
},
"response": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"$ref": "#/definitions/BuildResult"
}
},
"required": ["success", "data"]
},
"timeout": 300000,
"note": "Build operations can take several minutes depending on project size"
},
"clean_build": {
"description": "Clean Addressables build cache",
"request": {
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "clean_build"
}
},
"required": ["action"]
},
"response": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": ["success", "message"]
}
}
},
"definitions": {
"BuildResult": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether the build succeeded"
},
"duration": {
"type": "number",
"description": "Build duration in seconds",
"minimum": 0
},
"outputPath": {
"type": "string",
"description": "Output directory path (absolute)"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Error messages (empty if successful)"
}
},
"required": ["success", "duration", "outputPath", "errors"]
}
}
}

[akiojin]

contract:addressables-manage.json

$(cat /Users/akio-jinsenji/Workbench/unity-cli/develop/specs/SPEC-a108b8a3/contracts/addressables-manage.json)

[akiojin]

gwt-spec ドメイン再編により #151 に統合