Claude CodeでUnityのAddressablesグループを整理する — ビルドレイアウトの差分で確かめる

整理の効果は「ビルドレイアウトの前後差」で測る

Addressablesのグループ整理は、Claude Codeに任せる部分と、Unity Editorで人が触る部分がはっきり分かれます。グループの移動やBundle Modeの変更はGroupsウィンドウの操作です。現状の読み取り、重複の洗い出し、C#側の参照確認、再ビルド後の比較は、Claude Codeが得意とする読む作業です。

整理の前後を比べる物差しは、Addressablesのビルドレイアウトレポートです。レポートにはバンドルごとのサイズ、明示的に含めたアセット、依存で暗黙に入ったアセットが出ます。整理前と整理後に同じ手順でレポートを取り、2つを突き合わせれば「減った」「変わらなかった」を数字で言えます。

整理の前にレポートを取って退避する

最初にやるのは、整理前のレポートを手元に残すことです。Unity PreferencesのAddressablesでDebug Build Layoutを有効にし、Addressablesコンテンツのフルビルドを実行します。レポートはLibrary/com.unity.addressables/buildlayoutに出力されます。レポートを作るとビルド時間が延びるので、普段は切っておき、整理の前後だけ有効にする使い方が現実的です。

出力先は固定のパスです。次のビルドの前に、日付と目的を付けて別の場所へ退避します。

mkdir -p .audit/addressables
cp Library/com.unity.addressables/buildlayout \
  .audit/addressables/buildlayout-before.txt

.audit/のように、リポジトリの管理対象外にしたいフォルダを選びます。レポートにはプロジェクト内のアセットパスが並ぶので、共有するときはパスに含まれる社内名称に注意が必要です。

読み取り専用のサブエージェントに現状を読ませる

レポートは項目が多く、メインの会話に丸ごと流すと文脈を圧迫します。サブエージェントは自分のコンテキストで作業して要約だけを返すので、この種の「長い資料を読んで要点を返す」作業に向きます。ツールをRead, Grep, Globに絞れば、読み取り専用の担当者になります。

サブエージェントは.claude/agents/addressables-auditor.mdとして置きます。

---
name: addressables-auditor
description: Addressablesのbuildlayoutレポートを読み、グループ構成の問題候補を一覧にする
tools: Read, Grep, Glob
model: sonnet
---
 
あなたはUnityのAddressablesグループ構成を点検する担当です。
渡されたbuildlayoutレポートだけを根拠に、次の順で報告してください。
 
1. SummaryのAddressable Groups、Total Bundle、Total Build Size
2. グループごとのバンドル数と合計サイズ(大きい順)
3. 複数のバンドルに暗黙で含まれているアセットの候補
4. Bundle Modeと、バンドル数の過不足の疑い
 
レポートに書かれていない項目は「記載なし」とし、推測で数値を埋めないでください。
ファイルの編集はしません。

サブエージェントのファイルはYAMLフロントマターとシステムプロンプトで構成され、toolsで使えるツールを制限できます。ファイルを置いてすぐ使える場合が多く、新しいagentsディレクトリを初めて作ったときだけ再起動が必要です。

呼び出しは、メインの会話から次のように頼みます。

addressables-auditorを使って、.audit/addressables/buildlayout-before.txt を点検して。
サイズの大きいグループ上位5つと、複数バンドルに重複して入っているアセットの候補を表にして。

返ってきた表は、そのまま信用せずレポートの該当箇所と照らします。サブエージェントの要約が、レポートにない数字を足していないかを見る習慣が、この手順の安全装置です。

洗い出す観点は5つに絞る

何を探すかを決めておくと、Claude Codeの報告が散らばりません。観点はAddressablesのマニュアルが挙げる、バンドルの詰め方と依存の扱いに沿って決めます。

暗黙アセットの重複は、整理で最も効果が出やすい観点です。たとえば2つのPrefabが同じマテリアルを参照し、Prefabだけが別々のグループにあると、マテリアルは両方のバンドルにコピーされます。マニュアルは、ランタイムで同じアセットのインスタンスが複数できうる点にも触れています。解消するには、そのマテリアルをAddressableにして、どちらかのバンドルか専用のグループに置きます。

バンドルの多さと少なさにも、それぞれ代償があります。多すぎるとバンドルごとのメモリオーバーヘッドが増え、カタログも膨らみます。少なすぎると、大きなバンドルのダウンロードが途中で切れたときにやり直しになり、個別にロードしたアセットを個別にアンロードできない問題が出ます。この両極の間で、同時に使うアセットを同じグループにまとめる「同時使用」の考え方が、長期的には効果的だとマニュアルは説明しています。

Analyzeツールの結果を併用する

EditorのWindow > Asset Management > Addressables > Analyzeには、重複を調べるルールが用意されています。Check Duplicate Bundle DependenciesはFixできるルールで、Check Resources to Addressable Duplicate DependenciesとCheck Scene to Addressable Duplicate Dependenciesは情報提供のみのルールです。

この3つのルールは、Claude Codeの洗い出しの答え合わせに使えます。レポートから推定した重複候補が、Analyzeの結果と食い違うなら、どちらかの読み違いです。ただしAnalyzeの重複チェックは、ビルドを実際に走らせるのに近い処理を伴い、時間がかかります。

C#側の参照を先に洗い出す

グループはEditorにだけ存在する概念で、ランタイムのコードにはグループという単位がありません。グループ名で読み込むコードは存在せず、実行時にアセットを探すキーは、アドレス・ラベル・AssetReferenceのどれかです。したがってグループ間でアセットを移すだけなら、通常はC#の読み込み側は変わりません。一方、アドレスやラベルを書き換える整理は、コード側の文字列も合わせて直す必要があります。

整理の前に、アドレスやラベルを文字列で直接指定している箇所を洗い出しておきます。

grep -rnE "Addressables\.[A-Za-z]+Async" Assets --include=*.cs
grep -rnE "AssetReference(T|Label)?" Assets --include=*.cs

Claude Codeへ頼むときは、結果の数え上げより「文字列リテラルでキーを渡している箇所」を別表にするよう指示します。定数やAssetReference経由の箇所は、アドレスの変更に強いからです。

Assets配下のC#から、Addressablesのキーを文字列リテラルで直接渡している箇所を
ファイル名と行番号つきで表にして。AssetReference経由と定数経由は別の表に分けて。
今回は編集しないで、読むだけにして。

AssetReferenceでアセットを参照している場合、GUIDで引くため、グループ設定のInclude GUIDs in Catalogが有効である必要があります。逆に、アドレス文字列でしか読み込まない構成なら、カタログに入れるGUID文字列を外してカタログを小さくする選択肢もあります。こうした設定の差は、グループのContent Packing & Loadingに並んでいます。

グループの付け替えは人が行い、移動表をClaude Codeが作る

グループの移動をClaude Codeに直接やらせるより、「どのアセットをどのグループへ動かすか」の移動表を作らせ、人がGroupsウィンドウで適用するほうが事故を避けられます。Addressablesのグループ設定はスキーマと呼ばれるScriptableObjectで持たれており、設定ファイルを直接書き換えるより、Editorの操作に任せるほうが壊れにくいためです。

移動表の形は、次のように決めておきます。

理由の欄を、マニュアルが挙げる整理の方針に紐づけておくと、レビューで説明しやすくなります。方針は、同時に読み込むものをまとめる「同時使用」、同じ論理単位でまとめる「論理的なまとまり」、種類でまとめる「型」の3つです。リモート配信するコンテンツは、ローカルのものと分ける必要があります。更新頻度が高いアセットも、ほとんど変わらないものとは別のグループに置くほうが扱いやすくなります。

付け替えで気をつけること

Internal Asset Naming ModeとInternal Bundle Id Modeは、変更するとバンドルのCRCとハッシュが変わります。コンテンツ更新ビルドでは、これらを変えるとコンテンツステートファイルのデータが無効になるとマニュアルが警告しています。整理のついでに触る設定ではありません。

Blankテンプレートで作ったグループには、スキーマが付きません。既定のビルドスクリプトは、スキーマのないグループを処理できません。新しいグループはPacked Assetsテンプレートで作ります。

再ビルドして、前後のレポートを比べる

人がグループを付け替えたら、もう一度フルビルドしてレポートを取ります。Groupsウィンドウから手で回してもよく、同じ手順を繰り返したい場合は、コマンドラインから実行できるメソッドを用意します。ビルドをスクリプトから始めるにはAddressableAssetSettings.BuildPlayerContentを呼びます。次のメソッドは、既定のプロファイルとビルドスクリプトでコンテンツだけをビルドする最小の例です。

// Assets/Editor/AddressablesBatch.cs
#if UNITY_EDITOR
using System;
using UnityEditor;
using UnityEditor.AddressableAssets;
using UnityEditor.AddressableAssets.Build;
using UnityEditor.AddressableAssets.Settings;
using UnityEngine;
 
internal class AddressablesBatch
{
    const string BuildScript =
        "Assets/AddressableAssetsData/DataBuilders/BuildScriptPackedMode.asset";
 
    public static void BuildContent()
    {
        var settings = AddressableAssetSettingsDefaultObject.Settings;
        var builder = AssetDatabase.LoadAssetAtPath<ScriptableObject>(BuildScript)
            as IDataBuilder;
        settings.ActivePlayerDataBuilderIndex =
            settings.DataBuilders.IndexOf((ScriptableObject)builder);
 
        AddressableAssetSettings.BuildPlayerContent(
            out AddressablesPlayerBuildResult result);
        if (!string.IsNullOrEmpty(result.Error))
            throw new Exception(result.Error);
    }
}
#endif

このコードは、マニュアルの継続的インテグレーション向けの例を、コンテンツのビルドだけに縮めたものです。マニュアルの例では、プロファイル名を指定してactiveProfileIdを設定する処理も入っています。プロファイルを切り替えて運用している案件は、その処理も足します。

メソッドの呼び出しは、Unityのコマンドライン引数で行います。

"/Applications/Unity/Hub/Editor/<Version>/Unity.app/Contents/MacOS/Unity" \
  -quit -batchMode -projectPath . -buildTarget Android \
  -executeMethod AddressablesBatch.BuildContent \
  -logFile .audit/addressables/build-after.log
cp Library/com.unity.addressables/buildlayout \
  .audit/addressables/buildlayout-after.txt

マニュアルは、コマンドラインやCIでビルドするときは、ターゲットプラットフォームごとにEditorを起動し直すよう勧めています。スクリプトのコンパイルが終わる前に-executeMethodが呼ばれるのを避けるためです。プラットフォームを切り替える処理と、Addressablesのビルドを同じメソッドに入れないのも、同じ理由です。

2つのレポートが揃ったら、メインの会話で比較を頼みます。

.audit/addressables/ のbuildlayout-before.txt と buildlayout-after.txt を比べて。
SummaryのAddressable Groups、Total Bundle、Total Build Size の前後を表にして。
サイズが増えたグループがあれば、そのバンドルを挙げて。

見るのはSummaryの3項目です。Addressable Groupsはグループ数、Total Bundleは作られたバンドル数、Total Build Sizeは全バンドルの合計サイズです。重複を解消できていれば合計サイズが下がり、バンドル数は専用グループを足した分だけ増えます。合計サイズが下がらずバンドル数だけ増えたなら、整理がバンドルを細かくしただけで、重複は減っていない可能性があります。

規約はCLAUDE.mdに置く

毎回同じ指示を打たなくて済むように、Addressablesの点検に関する規約をCLAUDE.mdに置いておきます。

## Addressables
 
- グループの設定ファイルは直接編集しない。移動はGroupsウィンドウで人が行う
- 点検はbuildlayoutレポートを根拠にする。レポートにない数値は書かない
- 整理の前後で `.audit/addressables/` にレポートを退避し、Summaryの
  Total Bundle と Total Build Size を比較表にする
- アドレスやラベルを変更する提案には、C#側の使用箇所の一覧を必ず付ける
- Analyzeの自動修正(Fix)は、Claude Codeからは実行しない

こうしておくと、「編集しない」「根拠はレポート」といった制約を、依頼のたびに書かなくて済みます。

まとめ

Addressablesのグループ整理は、先に前後を測れる形にしてから手を付けるほうが、結果の説明がしやすくなります。Claude Codeは、レポートの読み取りと、C#側の参照確認、再ビルド後の比較に使います。グループの付け替えは、人がGroupsウィンドウで行います。

この分担の利点は、判断を人に残したまま、読む量だけをClaude Codeに肩代わりさせられる点です。Unityの別の作業で同じ分担を試すなら、ローカライズのString Table移行が参考になります。Unity Editorを直接操作させたい場合は、Unity MCPの接続手順で別の道筋を説明しています。ゲーム開発全体でのClaude Codeの使い方は、C#とCLIで検証する手順にまとめています。