第3章　チューニングバイブルをAIコーディングエージェントのスキルにする

3.1　はじめに

本書のようなチューニングナレッジには、ひとつの構造的な弱点があります。読んだ人にしか効かないことです。各章には実測に裏打ちされた知見が詰まっていますが、それがプロジェクトのコードレビューで実際に指摘されるかどうかは、レビュアーが該当の章を読んでいて、レビューの瞬間に思い出せるかにかかっています。チーム全員が全章を暗記することは期待できませんし、運用フェーズで人が入れ替われば知見は薄れていきます。一方で、コードを書く現場にはAIコーディングエージェント（Claude Code、OpenAI Codex、GitHub Copilot など）が常駐するようになりました。レビュー依頼や CI に組み込めば、すべての差分に同じ基準を当てられます。足りないのは、Unity のパフォーマンスに関する体系的な評価基準だけです。そこで本章では、チューニングバイブルの知見を「AIエージェントが実行できる評価項目」に変換し、特定のツールに依存しない汎用スキルとしてパッケージングする方法を紹介します。筆者が実際に、前作で公開済みの知見に基づく77ルールへ、本書（2026年版）の原稿群から抽出した86ルールを統合し、計163の評価ルールとしてスキル化した事例をもとに、変換の設計指針と運用上の注意点をまとめます。

3.2　Agent Skills という共通フォーマット

3.2.1　SKILL.md の仕様

AIエージェントに専門知識を持たせる方法として、2025年末に Agent Skills*1 というオープンな仕様が公開されました。スキルの実体は SKILL.md という Markdown ファイルを中心としたディレクトリで、次のような構成をとります。

1
2
3
4
5

unity-perf-review/
├── SKILL.md          # メタデータ + 実行手順（必須）
├── references/       # ルール集などの参照ドキュメント
├── scripts/          # 実行可能スクリプト（任意）
└── assets/           # テンプレート等（任意）

SKILL.md の先頭にはフロントマターと呼ばれるメタデータを書きます。必須フィールドは name と description の2つだけです。

1
2
3
4
5
6
7
8
9

---
name: unity-perf-review
description: >
  Unity プロジェクトのコード・アセット・設定をパフォーマンス観点で
  レビューする。C# スクリプト、シェーダー、.meta、ProjectSettings を
  163 のルールと照合し、Critical / Warning / Info の指摘を出力する。
  Unity のパフォーマンスレビューや最適化調査を依頼されたときに使う。
license: MIT
---

重要なのは description の書き方です。エージェントはユーザーの依頼内容と description を照合してスキルを自動発動するため、「何をするか」だけでなく「いつ使うか」まで書いておくと発動精度が上がります。

3.2.2　主要エージェントの対応状況

この仕様の価値は、複数のエージェントが同じフォーマットを読めることにあります。2026年8月時点の対応状況を表3.1に示します。

Codex / Copilot / Gemini CLI は共通の .agents/skills/ 配置にも対応しています。また Copilot はプロジェクトの .claude/skills/ も読むため、.claude/skills/ への配置1つで Claude Code と Copilot の両方に届きます（Copilot の個人用配置は ~/.copilot/skills/ または ~/.agents/skills/）。対応状況・配置場所は時点依存のため、導入時に各エージェントの公式ドキュメントで一次情報を確認してください。一度チューニングナレッジを SKILL.md 形式に落とし込めば、どのエージェントを使うメンバーにも同じレビュー基準（ルールと手順）を配布できます。Agent Skills が共通化するのはパッケージ形式と手順であり、モデルやツール権限の差で実行結果までは揃いません。それでも「レビュー基準はリポジトリに、実行はエージェントに」という分業が成立します。

3.3　知見を「評価項目」に変換する

スキル化の本体は、SKILL.md を書くことではなく、章の知見をエージェントが機械的に適用できる粒度まで分解することです。筆者は次のフォーマットに統一しました。

1
2
3
4
5
6
7
8
9
10

### US11 ParticleSystem.Simulateへの大きな秒数指定
- レベル: Warning（Noiseモジュール有効時はCritical）
- 対象: コードレビュー / アセット設定
- 検出パターン: Simulateの第1引数に大きな秒数を渡している。
  特にNoiseModule有効なParticleSystemとの併用
- grep_pattern: \.Simulate\(
- 理由: Simulateは指定時間まで一括シミュレーションする。
  実測で20秒指定によりNoiseJobが約2000回コールされ
  約50msのスパイクが発生
- 対処: Noise有効パーティクルではSimulateの利用を控える

このフォーマットには4つの設計判断が入っています。

3.3.1　検出の機械化可能性を明示する

各ルールには grep_pattern として、C# コードや Unity の YAML（.meta、Prefab、ProjectSettings）に対する機械実行可能な検索仕様を持たせます。多くは1本の正規表現ですが、複数行の突き合わせや「あるべき記述の不在」を検出するものも含みます。エージェントはこの仕様で一次検出し、ヒット箇所だけを精読して判断します。これにより大規模リポジトリでも現実的なコストでレビューできます。正規表現で書けない項目を無理に書かないことも同じくらい重要です。たとえば「Addressables 未登録の共有アセットが複数バンドルから参照されている」は grep では取れません。そうしたルールには (手動確認) と明記し、Addressables Analyze などの確認手段を対処欄に書きます。検出可能性を偽ると、エージェントは誤検出を量産するか、検出できないルールを黙ってスキップするようになります。

3.3.2　実測値を理由欄に残す

「理由: パフォーマンスが悪化するため」というルールは説得力を持ちません。原稿にある実測値をそのまま理由欄に引用します。

• 未圧縮テクスチャ: 2048x2048 で Compressed 2.7MB / Uncompressed 16.0MB（約6倍差）
• 1体1グラフの手動 Playable: 600体で 8.396ms 対 全体1グラフ 4.500ms（1.87倍差）
• Simulate(20f) と Noise の併用: NoiseJob 約2000コール・約50ms のスパイク

数値があると、エージェントの指摘がそのまま「なぜ直すべきか」の説明になります。レビューを受けた開発者が原稿の当該章に立ち返る導線にもなります。なお、いずれも原稿記載の特定環境での実測値です。ルールの理由欄には代表値を引用し、計測条件の詳細は出典章を参照する運用にしています。

3.3.3　レベルと上書きで運用に耐えさせる

ルールには Critical / Warning / Info の3レベル（Critical=劣化の確実な原因で、適用条件の成立を確認できたら修正必須、Warning=条件次第で問題化する潜在リスク、Info=任意の改善推奨）を付け、さらにプロジェクト側で上書きできる仕組み（rules-overrides）を用意します。たとえば「LINQ 使用は Critical」でも、初期化時（init コンテキスト）は Warning に緩和、Editor ツール（tooling）では Skip、のような調整です。チューニングルールは本質的にコンテキスト依存です。上書き機構がないと「うちのプロジェクトでは合わない指摘が多い」となってスキルごと無効化されます。基準は共通、適用はプロジェクト固有、という2層構造が長持ちのコツです。

3.3.4　静的に検出できない知見は診断ナレッジに分ける

原稿の知見には、コードを読んでも分からないものが多くあります。「CPU 処理を削ったのにフレーム時間が変わらず Semaphore.WaitForSignal などの待機マーカーに時間が移った場合は、レンダースレッド側がクリティカルパスにある可能性を疑い、Timeline ビューで待ち先を確認する」のような、プロファイラの読み方に関する知見です。待機マーカー単独では律速要因を断定できない、という限界も知見の一部として残します。これらは評価ルールとは別ファイルに「症状 → 原因 → 対処」の表として分離しました（表3.2）。筆者のリポジトリではプロファイル解析用のエージェント（Claude Code 向け）が診断時にだけ読み込みます。本章で配布するスキルには参照資料として同梱しており、静的レビューで判断できない疑いを「プロファイル計測推奨」として報告する際の根拠になります。

3.4　スキルとして組み立てる

3.4.1　段階的読み込みとチェックリスト方式

163ルールをすべて SKILL.md 本文に書くと、エージェントのコンテキストを圧迫します。Agent Skills の設計思想は段階的読み込み（progressive disclosure）です。

1. エージェントは常時、フロントマターの name と description だけを見ている
2. スキルが発動したら SKILL.md 本文（実行フロー）を読む
3. 必要になった参照ドキュメントだけを references/ から読む

初期に何を読むか（パス等を含むか）はエージェント実装に依存しますが、「本文と参照資料は発動まで読まれない」という原則は共通です。ここで注意したいのが網羅性です。素朴には「対象ファイル種別に応じてカテゴリ別ルールファイルを丸ごと読み込む」構成が考えられますが、この方式ではエージェントがコードより先に読むルールが最大で2万トークンを超える量（文字数からの概算。トークン数はモデル依存です）に達します。数十のルールを「全部覚えて適用する」ことをモデルの注意力に依存させると、一部のルールが黙って読み飛ばされます。そこで、全ルールから「ID / レベル / 適用条件 / grep_pattern / ルール名 / 詳細ファイル名」を1ルール1行に圧縮したチェックリストを自動生成し、レビューを2段階に分けました。

1. 一次スキャン: 同梱スクリプト scan.py がチェックリスト全行の grep_pattern を対象ファイルに機械実行し、ヒット一覧（ファイル:行）と Coverage を出力する（python3 が無い環境ではエージェントが全行の grep を直接実行するフォールバック）
2. 二次精査: ヒットしたルールについてだけ、詳細ファイルから検出条件・理由・対処を読み込んで誤検出を除外する

grep で表現できない一部のルールはチェックリスト上で MANUAL と明記し、対象種別に該当するときだけ精読します。「あるべき記述の不在」が指摘条件になるルールには ABSENT を付し、grep がヒットしなかった場合に詳細を確認します（ヒットの有無と指摘条件の対応を逆転させないための明示です）。一次スキャンをスクリプトにしたのは、LLM に数十本の grep を1本ずつ実行させると読み飛ばしが起きうるうえ、正規表現の方言差（PCRE の先読みは macOS 標準 grep で動かない等）で結果が環境依存になるためです。これで一次スキャンの網羅性はモデルの記憶力から切り離されます。指摘の正しさ（二次精査での誤検出除外）は引き続きエージェントの判断です。事前に読むのはチェックリストだけ（コード用約16KB・アセット用約8KB。トークン数はモデル依存ですが、合計で1万トークン前後の概算）になり、詳細はヒットした分しか読みません。チェックリストはルール本体から自動生成するため、ルールを追加しても手動での同期作業は発生しません。

3.4.2　環境に応じたルール除外

ルールにはUnityバージョンや構成に依存するものがあります。本スキルに収録した RenderGraph 関連ルール（URP 向け）は Unity 6 以降が対象で、LTO 系は IL2CPP 専用、iOS 固有の PSO 問題は Android のみのタイトルには無関係です。該当しないルールの照合はノイズと手間にしかなりません。そこで環境依存ルールには適用条件タグ（unity>=6000.3、urp、il2cpp、ios など）を持たせ、プロジェクトの設定ファイルから生成した環境プロファイルと突き合わせて「明確に条件を満たさないルールだけ」を除外します。タグの突き合わせは一次スキャンスクリプトが決定的に処理し、検出できなかった項目（unknown）は安全側（照合対象のまま）に倒し、スキップしたルール ID はレポートに列挙して監査可能にします。生成手順は導入手順の節で説明します。

3.4.3　出力にルールIDを強制する

出力フォーマットでは、各指摘へのルールID付与を必須にします。

1
2
3
4
5

### Critical
- Assets/Scripts/EffectPlayer.cs:42 -
  Noise有効パーティクルへのSimulate(20f)呼び出し [US11]
  - 根拠: NoiseJobが約2000回コールされ約50msのスパイク（実測）
  - 推奨: Noiseを外すか秒数を最小化する

IDがあると、指摘の根拠をルールファイルまで遡って検証でき、「エージェントがそれっぽく言っているだけ」との区別がつきます。誤検出だった場合も、どのルールの検出パターンを直せばよいかが明確になります。

3.5　配布と各エージェントへの配置

スキルの公開は、ディレクトリごと共有するだけで成立します。GitHub リポジトリでも zip でも構いません。利用者は表3.1の配置場所にコピーすれば、それぞれのエージェントがスキルを発見します。運用上のポイントは、ルールの単一ソースを保つことです。筆者のリポジトリでは、ルール本体は rules/ ディレクトリだけに置き、配布用パッケージはスクリプトで組み立てています（利用者側の導入手順は次節）。

1
2
3
4

./package-skill.sh
cp -r dist/unity-perf-review /path/to/repo/.claude/skills/   # Claude Code
cp -r dist/unity-perf-review /path/to/repo/.agents/skills/   # Codex / Copilot / Gemini CLI
cp -r dist/unity-perf-review /path/to/repo/.github/skills/   # Copilot 固有配置（上2行いずれかで届くため任意）

エージェントごとにルールを二重管理し始めると、更新のたびに基準がズレていきます。「ソースは1か所、配置はスクリプト」を最初に決めておくことを勧めます。

3.6　自分のプロジェクトへ導入する

ここまでの仕組みを読者のプロジェクトで動かす手順です。python3 が導入済みなら、コピーと初期生成は10分程度が目安です。リポジトリに追加されるのはスキルディレクトリと環境プロファイル（tuning-env.md）だけで、Unity の Assets / ProjectSettings には変更を加えません。

3.6.1　スキルの取得と配置

スキル一式（SKILL.md、ルール163件を同梱した references/、環境検出・一次スキャン・チェックリスト再生成の3スクリプト、導入手順の README）は本書のリポジトリの skills/unity-perf-review/ で公開しています*5。取得して、使っているエージェントのスキルディレクトリへコピーするだけです。なおスキルは「エージェントへの指示と実行可能スクリプト」を含む配布物です。信頼できない配布元のスキルは SKILL.md と scripts/ の中身を確認してから導入し、バージョンを固定することを勧めます。

1
2
3
4
5
6
7

git clone https://github.com/CyberAgentGameEntertainment/UnityPerformanceTuningTips2026.git
cd UnityPerformanceTuningTips2026/skills

# 使っているエージェントに応じていずれかへコピー
cp -r unity-perf-review /path/to/your-repo/.claude/skills/   # Claude Code
cp -r unity-perf-review /path/to/your-repo/.agents/skills/   # Codex / Copilot / Gemini CLI（共通配置）
cp -r unity-perf-review /path/to/your-repo/.github/skills/   # Copilot 固有配置（上2行いずれかで届くため任意）

リポジトリ直下に配置すればチーム全員に同じレビュー基準が配られます。個人で試すだけならホームディレクトリ側（~/.claude/skills/ など）でも動きます。

3.6.2　配置後の状態

Claude Code の場合、配置と次項の環境プロファイル生成が済むとリポジトリは次の状態になります（リスト3.7）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

your-repo/
|-- .claude/
|   \`-- skills/
|       \`-- unity-perf-review/
|           |-- SKILL.md                      # name/description + 実行フロー
|           |-- README.md                     # 人間向けの導入手順
|           |-- references/
|           |   |-- checklist-code.md         # 一次スキャン用 (コード系)
|           |   |-- checklist-asset.md        # 一次スキャン用 (アセット/設定系)
|           |   |-- checklist-profile.md      # プロファイル解析用（静的レビューでは未使用の付属資料）
|           |   |-- rules-csharp.md など計13ファイル  # 詳細ルール (計163)
|           |   |-- diagnosis-knowledge.md    # 症状->原因->対処の診断集
|           |   \`-- rules-overrides.example.md
|           \`-- scripts/
|               |-- detect-env.py             # 環境プロファイル生成
|               |-- scan.py                   # 一次スキャンの機械実行
|               \`-- gen-checklists.py         # ルール修正時のチェックリスト再生成
|-- tuning-env.md                             # 環境プロファイル (次項で生成)
\`-- (Unityプロジェクト本体は無変更)

3枚のチェックリストは対象別（コード / アセット / プロファイル）で、1つのルールが複数枚に載ることがあるため、行数の合計はルール数163と一致しません。配置した時点でエージェントに載るのは、原則としてフロントマターの name と description（合計で数百トークン。前述のとおり実装によってはパス等が加わります）だけです。レビューを依頼すると、前述の段階的読み込みに従って SKILL.md 本文 → 対象に応じたチェックリスト → ヒットしたルールの詳細、の順に必要な分だけ読み込まれます。通常は163ルール全文（約125KB、概算で4万トークン強）を一括投入せずに済みます。rules-overrides.example.md はそのままでは無効です。プロジェクト固有の調整を始めるときに rules-overrides.md へリネームして編集します（後述）。

3.6.3　環境プロファイルの生成

前述のとおり163ルールには環境依存のものが含まれます。プロジェクトに該当しないルールを除外判断させるため、環境プロファイルを生成します。

1
2

python3 unity-perf-review/scripts/detect-env.py \
    /path/to/your-repo /path/to/your-repo/tuning-env.md

配置後に実行する場合は、パスを配置先（.claude/skills/ や .agents/skills/ など、使っているエージェントのスキルディレクトリ）に読み替えてください。Unity プロジェクトがリポジトリ直下ではなくサブディレクトリにあるモノレポ構成でも、リポジトリルートを渡せば設定ファイルを再帰的に探索して検出します。スクリプトの実行には python3 が必要です（無い環境では tuning-env.md を手動作成するか、この手順を飛ばして全ルール照合で運用できます。一次スキャンの scan.py も python3 を使いますが、無い場合はエージェントが grep を直接実行するフォールバックで動きます）。スクリプトは ProjectVersion.txt、Packages/manifest.json、GraphicsSettings.asset、ProjectSettings.asset から Unity バージョン・レンダーパイプライン・Scripting Backend・Addressables の有無を推定します。あくまで設定ファイルからの推定値であり、確定情報は tuning-env.md への手動記入が正です。検出できなかった項目（プラットフォーム別に設定が分かれる Scripting Backend の混在時など）は unknown となり、安全側（照合対象のまま）で扱われます。出力された tuning-env.md を開いて内容を確認し、特に出荷プラットフォームと SideFX VAT の使用有無は手動で補正し、render_pipeline も想定どおりの値かを確認してください。

3.6.4　プロジェクト固有の調整（任意）

意図的にルールから外れている箇所がある場合は、rules-overrides.md にレベルの上書きを記録します。初期化時の LINQ を許容する、Editor ツールではログルールを無効化する、といった調整です。環境プロファイルが「その環境では原理的に適用不能」なルールの除外を担い、overrides が「プロジェクト都合の調整」を担う、という役割分担です。ルールそのものを追加・修正したい場合は references/ の rules-*.md を編集し、python3 scripts/gen-checklists.py references/ でチェックリストを再生成します。チェックリストは自動生成物のため直接編集しません。配布物だけでこの追加・再生成のサイクルが完結します。

3.6.5　実行する

エージェントに依頼するだけです。通常は依頼文と description の一致で自動発動します（発動はモデル判断のため、確実に使わせたい場合は依頼文にスキル名 unity-perf-review を明記するか、各エージェントの明示呼び出しを使います）。

1
2

この差分をパフォーマンス観点でレビューして
Assets/Scripts/Battle/ 配下をチューニングバイブルのルールでチェックして

出力の最後に付く Coverage セクションで、照合したルール数・環境スキップしたルール数（ID付き）・grep ヒット数が確認できます。これらの件数は一次スキャンスクリプトの出力の転記で、エージェントの記憶には依存しません（二次精査での採用・誤検出除外の件数のみエージェントが集計します）。除外されすぎだと感じたら tuning-env.md を、指摘が多すぎると感じたら rules-overrides.md を調整してください。

3.7　運用で気をつけること

実際にプロジェクトへ導入して分かった注意点を挙げます。初回はリポジトリ全体ではなく、差分か特定ディレクトリから始めます。 一次スキャン自体はプロジェクト全体でも短時間で終わりますが、運用歴のあるコードベースではヒットするルールが数十件規模になり、二次精査（誤検出の除外）の負荷がそこに集中します。狭い範囲で精査し、恒常的に許容するものを overrides に落としてから対象を広げるほうが、指摘がノイズに埋もれずに定着します。静的解析は意図した設定も指摘します。 たとえば意図的に非圧縮にしているテクスチャも AS02（テクスチャ圧縮未設定）でヒットします。検出結果を鵜呑みに一括修正せず、1件ずつ意図を確認してから直すこと。恒常的に許容するものは overrides に理由付きで記録することで、次回以降のノイズを減らせます。overrides の調整単位はルール全体またはコンテキスト（in-game=ホットパス / init=初期化 / tooling=Editor）で、特定アセットだけの例外は備考欄にパスや理由を書いてエージェントの判断材料にします（専用の適用範囲指定は現バージョンでは未対応です）。実測値には計測環境が付いています。 ルールに引用した数値は特定の Unity バージョン・端末での実測です。「Pixel 8a での実測」を最新ハイエンド端末の判断に外挿はできません。ルール自体に対象バージョンを書き、Unity やレンダーパイプラインの更新をルール見直しのトリガーにします。最後に判断するのは人です。 本書の別章の言葉を借りれば「規約を決める・見直すのは人、守らせるのは機械」です。AIエージェントは「守らせる機械」の新しい実装であって、規約=評価項目の妥当性に責任を持つのは引き続き人間です。エージェントの指摘に納得できなかったら、それはルールの検出パターンか理由欄を改善するシグナルだと捉えてください。

3.8　おわりに

チューニングバイブルの知見をルール化してみて実感したのは、「実測値と対処がセットで書かれた原稿は、ほぼそのまま機械可読な評価項目になる」ということです。逆に言えば、根拠の数値がない経験則はルール化の段階で弱さが露呈します。これは執筆側へのフィードバックでもあります。計測環境と数値を明記した知見は、書籍の読者だけでなく、AIエージェントを通じてすべてのコードレビューに届きます。本章で紹介したスキルとルール集は、単一の正解というより出発点です。各プロジェクトの overrides が育ち、新しい章の知見がルールとして追加されていく、生きた規約集になることを期待しています。