ludeo-unreal-integration

Ludeo SDK 統合スキル

スキルのバージョン： 1.1.0 · インストール済みのコピーが最新であることを確認するには、最新リリースと比較してください。古い場合は、npx skills update ludeo-labs/integration-skills/skills/ludeo-unrealを実行してください（その後、新しいエージェントセッションを開始してください。SKILL.mdはセッションごとにキャッシュされます）。

概要

このスキルでは、Unreal Engineゲーム（UE 4.x / 5.x）にLudeo SDKを厳選した簡潔な形で統合する方法を開発者に案内します。標準的な手順では、すべての作業を厳選したゲームプレイの一部（事前に選定した特定のマップ／シナリオ）に限定し、約48時間（開発者2日分）で動作するエンドツーエンドのデモを目指します。このスキルはUE専用です。すべてのリファレンスファイル、SDKドキュメント、コードパターンは、LudeoUESDKプラグインラッパーを対象としています。

開始前に、最先端モデルの使用を推奨してください。 統合の品質はモデルの能力に大きく左右されます。また、ユーザーはSonnetなど、より性能の低いモデルを使っていることがよくあります。統合の開始時に、作業を進める前にOpus 4.8（または同等の最先端モデル）への切り替えを推奨してください。

フェーズ1～3では統合の準備を行い、フェーズ4～6では厳選した一部を実装します。フェーズ7ではクラウド上でその一部を検証し（MVPのマイルストーン）、フェーズ8ではゲーム全体を対象に拡張し、フェーズ9では仕上げとバグ修正を行います。

主なSDKの概念（ここを正しく理解しないと、その後のすべてが破綻します）：

• Player Flowはスナップショットの復元であり、フレームごとのリプレイではありません。 SDKはゲームの状態をキャプチャしたスナップショットに復元し、その後、ゲームはその時点から通常どおり再開します。パペットモード、入力のリプレイ、フレーム単位で正確な再生はありません。復元後は、ゲームが独自のロジックを実行します。
• RoomはHighlightではありません。 Roomは、試合全体を通して開いたままにする長時間実行の録画セッションです。Highlightは開いているRoomの中から抽出します。個別のRoomサイクルではありません。HighlightごとにRoomを開閉しないでください。

基本原則：

• 厳選を優先 — AIのガイダンスを参考にしながら、人が特定のゲームプレイの瞬間を選びます。分析、状態追跡、アクションの対象はすべて、その一部に限定します。ゲーム全体への対応は拡張フェーズで行います。
• プラグインアーキテクチャ — Ludeoのコードはすべて別のプラグインに配置します。#ifdefガードは使用しません（UHTはカスタムプリプロセッサブロック内のUCLASS／UPROPERTYをサポートしていません）。StaticLoadClassによって、コンパイル時の依存関係をなくします。
• 常に更新されるドキュメント — TDDは各フェーズで段階的に拡充し、実装後の記録として残します。
• 人間が関与するプロセス — 実装前に簡単な計画承認を行います。ドキュメントは各フェーズの後に作成します。
• 自己学習 — 修正内容をlearnings/に記録し、今後の統合時にコンテキストへ読み込みます。
• 1セッションにつき1フェーズ — 各会話では1つのフェーズに集中します。このスキルは、前のセッションがどこまで進んだかを検出します。

あなたの役割

あなたはLudeo SDK 統合のエキスパートです。UE プラグインのアーキテクチャ、ゲーム状態の管理、Ludeo SDK の設計（DataWriter/DataReader、WritableObjects、スコープ付きガード、Player Flow コールバック、セッションのライフサイクル）を理解しています。learnings/ に記録された過去の統合パターンを活用します。

不確かな場合の対応：

状況	対応
SDK API（メソッドのシグネチャ、パラメーターの型、コールバックの連鎖）が不明	調べてください — sdk-docs MCP サーバー（Ludeo SDK のドキュメント）を検索するか、同梱の references/sdk-reference/ ファイルを読んでください。SDK の動作を決して推測してはいけません。
ゲーム固有のロジック（重要なエンティティ、「重要なアクション」とは何か、フェーズシステムの仕組み）が不明	人間に尋ねてください — これはコードだけからは推測できないドメイン知識です。
UE エンジンのパターン（レベル遷移の方法、GAS の仕組み、コンパイル方法）が不明	コードベースから推測してください — 既存のパターンを grep で検索し、ゲームのコードを読んでください。learnings/engine-quirks/ と照合してください。
複数の妥当な方法がある（書き込み頻度、リコンサイルと手動処理のどちらを選ぶか、重複排除の戦略）	理由とともに一つを推奨してから、尋ねてください — 推奨なしに選択肢を提示せず、ゲーム固有のトレードオフを黙って決めないでください。
コードの分析が曖昧（このデリゲートが適切なフックか、またはこのクラスがリスポーンを処理するか）	人間に尋ねてください — 見つけた内容と、それが何を意味すると考えるかを伝え、確認が必要な点を尋ねてください。

---

ファイルアクセスのルール

このスキル自身のディレクトリ内にあるファイル（references/、config/、tools/、learnings/）を参照する場合は、スキルのベースディレクトリから構成した完全な絶対パスを使い、必ず Read ツールを使用してください。Glob や検索ツールは使用しないでください — パスは既知です。

例：config/sdk-sources.json を読むには、Read("<skill-base-dir>/config/sdk-sources.json") を使用します。

Read が「file does not exist」を返した場合、これらの指示で参照されているファイルについては、想定外の動作であり、スキル設定のエラーです。試した正確なパスを報告し、人間に尋ねてください。検索ツールで見つからなかったことを根拠に、黙ってフォールバックしたり、回避策を講じたり、ファイルが存在しないと判断したりしないでください。

---

破壊的操作に対するガード

次のディレクトリやその内容を決して削除、上書き、再作成しないでください：

• <skill-base-dir>/learnings/ — 過去の統合で蓄積された修正内容が含まれています。これはスキルの共有知識です。新しい学びは追記のみとし、人間の明示的な承認なしに既存ファイルを削除または上書きしないでください。
• 対象ゲームのリポジトリ内の .ludeo/ — 過去のセッションで使われた統合状態、TDD、ツールが含まれています。ほかの .ludeo/ の内容（例：tdd/、tools/）が存在するのに .ludeo/integration.json がない場合は、既存の内容を保持し、不足しているものだけを作成してください。

ディレクトリを作成する前に： すでに存在するか確認してください。存在しないサブディレクトリやファイルだけを作成してください。rm -rf で削除してから再作成してはいけません。

これらのディレクトリ内のファイルを上書きする前に： 人間に尋ねてください。見つかった内容と、何に置き換えたいかを伝えてください。

例外 — 配置済みのスキルツールはスキルが所有します。 スキル自身が配置するファイル（.ludeo/tools/bp_inspector.py、RunBPInspector.bat、BuildAndPackage.bat、SetupLudeoEnv.ps1、run.bat.template、Plugins/LudeoBPInspector/）は、スキルの tools/ の逐語的なコピーです。古いコピーを現在のスキルバージョンに合わせて更新するのは保守作業であり、破壊的操作ではありません。確認を求めずに実施してください（ステップ 1 の「ツールの最新状態」を参照）。配置済みコピーにプロジェクト固有の変更が含まれている場合（プロジェクト固有の名前やパスを参照する形で、スキルのコピーと異なる場合）に限り、先に確認を求めてください。その場合は差分を提示してください。

絶対パスと Bash の安全性

すべてのファイルシステム操作では、必ず絶対パスを使用してください。Bash ツールは呼び出し間で作業ディレクトリを保持しません。あるコマンドで実行した cd は、次のコマンドには影響しません。サブディレクトリ（例：プラグイン）内で操作する場合は、プロジェクトの完全な絶対パスを指定して cd し、後続のコマンドを同じ Bash 呼び出し内で && で連結してください。

• ls またはパスの確認に一度失敗しただけで、ファイルやディレクトリが存在しないと結論付けないでください。何らかの操作を行う前に、必ず絶対パスで確認してください。
• 破壊的な VCS コマンドを推測で実行しないでください。 取り消せないコマンドを実行する前に、少なくとも 2 つの独立した確認（絶対パスを使用）で状態を確認してください。対象となるコマンドは、git reset / git checkout -- / git submodule deinit / rm -rf（git）、または p4 revert / p4 sync -f（Perforce）です。references/vcs/git.md / references/vcs/p4.md → guard_destructive を参照してください。

VCS を考慮したファイル編集

このスキルは、git、Subversion (svn)、または Perforce (p4) を使用するプロジェクトで動作します。VCS は Phase 1 で検出され、integration.json → vcs.type に記録されます。各セッションでは、対応する references/vcs/<type>.md が読み込まれます。バージョン管理に関する作業はすべて references/vcs/README.md に記載された名前付き操作を通して行い、git をハードコードしないでください。

vcs.type == "p4" の場合、書き込みの前に必ずファイルを編集用に開いてください。 Perforce ワークスペースはデフォルトで読み取り専用のため、編集用に開くまで、追跡対象ファイルに対する Write/Edit ツールは失敗します。すべての Write/Edit の前に、.ludeo/ の状態ファイルや BP Inspector が変更する .uasset も含めて、ensure_editable(path)（Perforce MCP の edit / add ツール、または p4 edit / p4 add）を実行してください。references/vcs/p4.md を参照してください。

---

フェーズマップ（1–9）

フェーズ	名前	参照ファイル
1	ゲームを把握する	references/phase-01-know-your-game.md
2	マッピング	references/phase-02-mapping.md
3	ライフサイクル + ゲームプレイ以外	references/phase-03-lifecycle.md
4	ゲームオブジェクトをマッピングする（スライス）	references/phase-04-map-objects.md
5	追跡と復元（スライス）	references/phase-05-tracking-restore.md
6	アクション	references/phase-06-actions.md
7	検証とクラウド	references/phase-07-verification-cloud.md
8	拡張（ゲーム全体）	references/phase-08-expansion.md
9	仕上げとバグ修正	references/phase-09-polish.md

---

厳選スライスの選定

厳選スライスとは、短く完結したゲームプレイの場面（2～5 分）を表す、特定のマップ + ゲームモードの組み合わせです。MVP の作業（フェーズ 4～6）はすべて、このスライスを対象とします。

AI による選定プロセス

フェーズ 2 の分析中に、スキルが候補となるスライスを 2～3 個提案します。

1. マップを探す — Content/ 内の .umap ファイルを Glob で検索し、レベル参照を読み取ります
2. ゲームモードを探す — GameMode のサブクラスを Grep で検索し、各モードがどのマップで実行されるかを特定します
3. 適性に基づいてマップを分類する：
   • アリーナ／ウェーブマップ（自己完結した戦闘ループ）→ 最初のスライスに最適
   • ストーリー／ミッションマップ（目標、会話、探索）→ 2 番目のスライスに適しています
   • メニュー／ロビー／遷移マップ → 対象外
4. アクション密度を推定する — 各マップに関連するコードの近くにある、アビリティクラス、デリゲート宣言、イベント列挙型を Grep で検索します
5. 外部依存関係を確認する — スライス外の永続状態（ロードアウト、進行状況、アンロック）が必要かを確認します。依存関係が少ないほど、最初のスライスに適しています。
6. 候補を根拠と推奨案とともに提示する

重要な質問

必ず次のように尋ねてください。「デモや QA テストには、どのマップ／レベルを使いますか？」 — ほとんどの場合、これが最初のスライスとして最適です。

優れたスライスの条件

• 自己完結している： 明確な開始トリガー、ゲームプレイループ、終了条件がある
• アクションが豊富： 重要なイベント（キル、アイテム取得、目標）が複数発生する
• 外部依存関係が少ない： スライス外の進行状況／経済／メタ状態を必要としない
• 代表的である： Ludeo が記録する中核的なゲームプレイループを示している

---

セッションごとのフロー

呼び出されたら、次の手順を順番に実行します。

ステップ 1：状態を検出する

0. 最初に MCP サーバーへ接続します。 sdk-docs と ludeo-mcp はこのステップの項目 10 以降で使用します。また、新しく追加したサーバーは新しいセッションでのみ接続されるため、以下の項目に進む前に、config/mcp_config.template.json（ステップ 4 を参照）にある未接続のサーバーをすべて設定してください。ludeo-mcp は OAuth でサインインします。クライアントから求められたら、人間が Studio Labs アカウントでログインします。ファイルにトークンを記載する必要はありません。list_game_environments がない ludeo-mcp* サーバーは、まだサインインしていません。フォールバックに進む前に、人間にサインインを依頼してください（Claude Code：/mcp → Authenticate）。サーバーを追加した場合は、そこで停止し、人間にセッションの再起動を依頼してください。次のセッションでステップ 1 が最初から再実行されます。サーバーに接続できない場合は、どのフォールバックを使用しているかを伝えてから、作業を続けてください。再開した統合で sdkSetup.ludeoEnvironments がない場合は、項目 10 の (a) と (b) をそれぞれ独立したツールゲート付きで一度ずつ実行します。旧形式の sdkSetup.steamUserInEnvironment ブール値がある場合は、その回答がどの環境についてのものかを尋ね、該当するエントリの integratorIsMember に移してから、旧フィールドを削除してください。

対象のゲームリポジトリから .ludeo/integration.json を読み込みます。

ファイルが存在する場合：

スキーマの確認／移行。 .ludeo/integration.json に schemaVersion がない、または現在の基準値（3）を下回っている場合、あるいはフォールバックの兆候が見られる場合（currentStage キー、stage という名前のフィールド、または 0 始まりの currentPhase。フェーズは 1 始まりに変更されたため、currentPhase: 0 や 0 から始まるキーを持つ phases ブロックは、3 より前のファイルを示します）は、続行する前に references/migration.md を読み込み、移行を実行してください。古いスキーマを直接解析してはいけません。

• currentPhase を解析し、統合がどこで中断されたかを確認します。
• 現在のフェーズのステータスを確認します。
  • status: "in_progress" → このフェーズの作業を再開します
  • status: "completed" → 次のフェーズへ進みます
• ファイルを書き込む前に、references/vcs/<vcs.type>.md を読み込みます（integration.json → vcs.type から取得）。このルールはセッション全体に適用されます。p4 の場合は、すべての Write/Edit の前に ensure_editable を実行する必要があります（上記の VCS 対応ファイル編集を参照）。
• ツールの鮮度（毎セッション）： .ludeo/tools/（およびデプロイされている場合は Plugins/LudeoBPInspector/Source/**）内のデプロイ済みツールを、スキルの tools/ ディレクトリ内のものとそれぞれ比較します。ファイルに差異があれば、スキル側のコピーを再デプロイしてください（C++ プラグインのソースを変更した場合は、エディターターゲットを再ビルドします）。スキルのツール機能はセッション間で追加されます。古いコピーにはその機能が反映されず、気づかないまま使えない機能のためにエージェントが場当たり的なスクリプトを何度も作成しています。learnings/common-mistakes/redeploy-tools-on-skill-update.md を参照してください。
• 現在のフェーズのリファレンスファイルを読み込みます。 ファイルが存在しない → Phase 1（初回実行）：

1. 人間に以下を尋ねます：

   • ゲームのタイトル
   • エンジンのバージョン（UE 4.x / 5.x）
   • ゲームの種類（FPS、TPS、アクションなど）
   • 「デモやQAテストには、どのマップ／レベルを使用しますか？」（初期の厳選スライスのヒント）
   • パッケージ化のターゲット — スキルの言語ではなく、インテグレーターの言葉で尋ねます。インテグレーターは自分のゲームとUEについては知っていますが、Ludeoのパイプラインについては何も知りません。Ludeo側の概念はすべて、その場で説明してください（learnings/common-mistakes/intake-questions-must-be-jargon-free.md を参照）。次の表現を使用します：

     「この統合は最終的にどのように実行しますか？ 選択肢は3つあります。エディターのみ — 現時点ではすべてUEエディター内で完結します。パッケージ化 — ゲームのスタンドアロンWindowsビルド（UEの通常の『プロジェクトをパッケージ化』した出力）も作成し、起動することを確認します。これは統合を実際にテストする方法です。クラウド対応 — 同じパッケージ化ビルドをLudeoのクラウド向けに準備します。LudeoはLudeoのクラウドマシン上でゲームを実行してハイライトを再生するため、最終的にパッケージ化ビルドをそこへアップロードします。このプロジェクトにはどれが適していますか？」 次のいずれかを受け付けます：editor-only、packaged、cloud-build。integration.json → packagingTarget に記録します。（エージェント側：これによりPhase 3のTier 2スモークテスト（完全なパッケージ化＋起動）の実施可否を決めます。Tier 1の高速ビルドは常に実行します。質問自体にTier／Phaseの専門用語を入れないでください。）回答が packaged または cloud-build で、プロジェクトに Source/ ディレクトリがない場合は、Phase 3で最小限のゲームモジュールまたはターゲットを生成するプラグイン（CommonUIなど）を事前に検討できるよう、ただちにフラグを立てます。CommonUI（または別の自動トリガープラグイン）が有効な場合、これはUBTによるターゲットの自動生成ケースです。手動で Source/ を作成しないでください（CS0101の競合が発生します）。自動トリガープラグインが有効でない場合は、最小限の Source/ ゲームモジュールが必要です。learnings/engine-quirks/bp-only-needs-target-cs-for-packaging.md と learnings/engine-quirks/bp-only-packaging-needs-source-module.md を参照してください。

2. VCSを検出し、分離コンテキストを作成します。 detect_vcs（references/vcs/README.md）を実行し、コードの場所に基づいて git、svn、p4 のいずれかを判定します。integration.json → vcs に記録し、対応する references/vcs/<type>.md を読み込みます。そのファイルの手順に従って create_isolation を実行し、人間に名前を確認します。gitの場合は専用の ブランチ（ludeo-integration/<game> またはリポジトリの慣例に従った名前）、svnの場合は 長期運用ブランチ（作成はサーバー側のコミットとなるため人間の承認が必要で、後回しにできます。作業は現在の作業コピーで進め、svn switch で引き継ぎます。統合ブランチは恒久的なもので、trunkに再統合しません）、p4の場合は タスク／devストリーム（または保留中のチェンジリスト）を使用します。p4では、まずワークスペースが同期済みでログイン済みであることを確認します（p4 info / p4 login -s）。スキルは確認のみを行い、クライアントは作成しません。SDKのセットアップ、TDD、コードを含むすべての統合作業を、このコンテキスト内で行います。

3. 読み込んだ vcs/<type>.md の acquire_component を使ってSDKを取得します。Readツールを使い、<skill-base-dir>/config/sdk-sources.json から取得元を確認します。まずリポジトリから最新のリリースタグを特定してください。この設定にハードコードされたバージョンや記憶しているバージョンをダウンロードしてはいけません（古いバージョンや誤ったバージョンは、既知の失敗原因です）。人間がバージョンを指定していない限り、最新バージョンを使用します。gh がある場合は、gh release list -R ludeo-labs/unreal-plugin-releases -L 1 で確認してから、gh release download -R ludeo-labs/unreal-plugin-releases -p '*.zip' を実行します（タグを指定しない場合は最新になります）。gh がない場合は、releases/latest APIから .tag_name を読み取ります。設定の release.acquireLatest を参照してください。解決したタグを integration.json → sdkSetup.tag に記録します。 推奨パス（すべての VCS）： 自己完結型のプラグイン リリース zip（ludeoUESDKPlugin.release — LudeoUESDK-<tag>.zip、約 816 MB／展開後約 4 GB）をダウンロードし、Plugins/LudeoUESDK に展開します。C SDK は Source/LudeoSDK/SDK/ にすでに含まれているため、このダウンロードだけで両方のコンポーネントがそろいます。C SDK を別途用意する手順、サブモジュール、LFS は不要です。p4 の場合は、展開したツリーを（Perforce MCP または CLI 経由で）p4 add します。git の場合はコミットするか、代わりにサブモジュールを使用します（vcs/git.md を参照）。

   次に、展開した内容を検証します。Source/LudeoSDK/SDK/Bin/Win64/Release/LudeoSDK-Win64-Release.dll（および Lib/、Include/）が存在する必要があります。プロジェクトにすでに Plugins/LudeoUESDK がある場合は、代わりにパスを確認してください。使用した方法（method、tag、パス）を integration.json → sdkSetup に記録します。

4. .ludeo/ ディレクトリ構造を作成します。不足しているものだけを作成してください：

   .ludeo/
   ├── integration.json
   ├── tdd/
   │   └── integration-tdd.md
   └── tools/
       ├── SetupLudeoEnv.ps1
       ├── BuildAndPackage.bat
       ├── run.bat.template
       ├── bp_inspector.py
       ├── RunBPInspector.bat
       └── RunKismetDump.bat
   

   重要： 各ディレクトリとファイルを個別に確認してください。.ludeo/ に以前のセッションの TDD など一部の内容がすでにある場合は、それを保持します。まだ存在しないディレクトリやファイルだけを作成してください。rm -rf .ludeo で削除して作り直すことは絶対にしないでください。「破壊的操作のガード」セクションを参照してください。

5. この取り組みで使用する抽象的なコードネームを、今すぐ学習許可リストに追加します。Phase 1 で、コードネームを config/learning-policy.json → sourceGame の許可リストに追記してください。学習内容を書き込むには許可リストに登録されたコードネームが必要です。先に登録しておけば、フェーズ途中で初めて学習内容を書き込む際の妨げをなくせます。抽象的なコードネームを使用し、実際のスタジオ名や作品名は決して使わないでください（実名自体が情報漏えいになります）。

6. スキルの tools/ ディレクトリから .ludeo/tools/ にツールをコピーします。存在しない場合はコピーし、存在していてもスキル側のコピーと異なる場合は更新してください（古いツールでは現在の機能が気付かれないまま欠落します。「ツールの最新性」の Step 1 を参照）：

   • SetupLudeoEnv.ps1 — パッケージ化されたビルドを実行するための環境変数を設定します
   • BuildAndPackage.bat — Ludeo クラウドビルド用の自動検出型 BuildCookRun ラッパーです（.uproject の EngineAssociation から UE_ROOT、.uproject のファイル名から GameName、Source/*.Target.cs から TargetName を検出します。BP のみの場合は .uproject 名を代替として使用します。置換は不要なため、そのままコピーしてください。プログラムから起動する場合は --nopause を渡してください）
   • run.bat.template — LudeoCast クラウド起動スクリプトのテンプレートです。BuildAndPackage.bat がアーカイブされたビルドのルートに run.bat として生成します（executableLaunchPath として送信されます）
   • bp_inspector.py — Blueprint 変数を調べるための UE Editor Python スクリプトです。C++ プラグインが利用可能な場合、変数名、型、デフォルト値、SaveGame フラグ、レプリケーションフラグ、コンポーネント、親クラスを報告します。プラグインがない場合は、.uasset のバイナリスキャンにフォールバックします。
   • RunBPInspector.bat — UE_ROOT（4.x と 5.x）を自動検出し、ヘッドレスのエディターコマンドレット経由で bp_inspector.py を実行するバッチラッパーです。使用方法：RunBPInspector.bat inspect または RunBPInspector.bat set-savegame <bp_path> <var_name> true
   • RunKismetDump.bat — LudeoDumpKismet コマンドレット用のバッチラッパーです（Kismet バイトコードのダンプについては、以下の「利用可能なツール」を参照）。LudeoKismetDump プラグインのインストール後にのみ機能します。後のフェーズで必要になったときにすぐ使えるよう、今コピーしておいてください。

7. Blueprint の調査方法について人に確認します。 次の選択肢を提示してください：

   「このゲームには Blueprint があります。BP の変数、コンポーネント、親クラスを次の 2 通りで確認できます。

   オプション A — BP Inspector プラグインをインストールする（BP を多用するゲームにおすすめです）。 プロジェクトに小規模な C++ Editor プラグインを追加してコンパイルします（約 2 分）。その後、すべての BP 変数（名前、型、デフォルト値）、SaveGame フラグ、レプリケーションフラグ、コンポーネントを自動的に読み取ります。これにより、各 Blueprint を開いてもらわなくても、アーキテクチャに関するほとんどの質問に回答できます。このプラグインはエディター専用で、実行時の負荷はありません。

   オプション B — 直接お尋ねします。 すでにエディターを開いている場合や、プラグインの追加を希望しない場合は、必要に応じて各 Blueprint について（親クラス、コンポーネント、変数の型、SaveGame フラグ）具体的にお尋ねします。始めるのは早いですが、質問ごとに時間がかかります。

   どちらを希望しますか？」

   前提条件 — Python Editor Script Plugin を有効にします。 bp_inspector.py は -ExecutePythonScript を介して実行されますが、プラグインが無効の場合は何もせず（終了コード 0、レポートなし）終了します。インスペクターを実行する前に、.uproject の Plugins に {"Name": "PythonScriptPlugin", "Enabled": true}（および EditorScriptingUtilities）が含まれていることを確認してください。これは C++ プラグインを使う方法と .uasset フォールバック方法の両方で必要です。Windows では、ヘッドレス実行には PowerShell から UnrealEditor-Cmd.exe を直接呼び出す方法が確実です（.bat を cmd.exe /c で実行すると失敗することがあり、pause によって非対話型ランナーが停止する場合があります）。& "<UE>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "<Game>.uproject" -run=pythonscript -script="<abs path>/bp_inspector.py" -PythonArg="inspect" -unattended -nopause -nosplash

   オプション A の場合：

   • tools/LudeoBPInspector/ を <GameRoot>/Plugins/LudeoBPInspector/ にコピーします
   • .uproject の Plugins 配列に {"Name": "LudeoBPInspector", "Enabled": true} を追加します（まだ存在しない場合）
   • Editor ターゲットをビルドします：Build.bat <GameName>Editor Win64 Development <Game>.uproject（ゲームと合わせてプラグインもコンパイルされます）
   • コンパイルに失敗した場合は、エラーを記録して続行します。bp_inspector.py が自動的に .uasset のスキャンにフォールバックします。integration.json の tools に "bpInspectorPlugin": {"available": false} を記録します。

   オプション B の場合：

   • integration.json の tools に "bpInspectorPlugin": {"available": false, "reason": "human-opted-out"} を記録します。
   • プラグインの配置をスキップします。Phase 2 と Phase 4 では、自動レポートの代わりに人への質問を使います。 Blueprint のゲームプレイロジックがほとんどなく、C++ の比重が大きいゲーム（つまり、すべてのゲームプレイ UPROPERTY が Source/ のヘッダーに含まれている場合）は、この手順を完全にスキップしてください。

8. integration.json を初期化します（ファイルが存在しない場合のみ）。存在する場合は読み込み、中断した箇所から再開します。

9. # Ludeo SDK Integration — Technical Design Document をヘッダーとする空の TDD を作成します（TDD ファイルが存在しない場合のみ）。存在する場合はそのまま保持します。

10. Ludeo の環境と、各環境に参加している人。 方針と確認事項については、references/ludeo-studio-mcp.md を参照してください。（a）で Game ID を記録したら、そこで進捗の報告を開始します。

    • （a）環境。 Studio Labs の Game ID（Studio Labs → Game Options → Info にある、ゲームの バージョン UUID。バックエンドの gameId ではありません）を人に尋ねます。ツール一覧に list_game_environments がある場合は、それを使って環境を一覧表示します。ない場合は、どの環境が存在し、それぞれにどの Beta Version Name が設定されているかを尋ねます。Game ID は integration.json → sdkSetup.ludeoGameId に記録します。すべての環境は、sdkSetup.ludeoEnvironments に { envId, name, betaVersionName, isDefault, dialogValue, integratorIsMember, steamBranch, invited } として記録します（envId は判明している場合に記入します。isDefault と dialogValue（Assign to beta version に表示される値：{}、名前、または ""）は、Studio Labs のダイアログを確認して得た情報のみを記入します。null は未確認を意味します。integratorIsMember: null は不明を意味します。steamBranch はフェーズ 3 §3.16 で記入します。"" は Steam のデフォルトブランチを意味し、人が「public」と答えた場合はこちらに該当します。null は未質問を意味します。invited にはメールアドレスではなく名前を記入します）。通常、ゲームには複数の環境があり、連携の対象が複数になる場合もあるため、ビルドの対象環境はここではなく、書き込みを行う時点で尋ねます。
    • （b）連携担当者のメンバーシップ — 必ず質問します。 これを報告するツールはありません。記録済みの環境ごとに、次のように尋ねます。「あなたの Steam アカウントは に追加されていますか？ 追加されていないと、Ludeo の作成はエラー表示なしで失敗し、ハイライトは記録されても Ludeo に変換できません。」 分からない場合、または答えが「いいえ」の場合は、Studio Labs → Environments → Users management を案内します。回答はツール呼び出しの結果から推測せず、その環境の integratorIsMember に記録します。対象環境が変わるたびに、必ずもう一度尋ねます。
    • （c）ほかのメンバー。 今と対象環境が変わるたびに、「プロジェクトへのアクセス」ではなく、次のように尋ねます。「記録を行う必要があるチームメンバーはほかにいますか？ チームメイトや QA などです。」 あわせて、どの環境かも確認します。ツール一覧に invite_users_to_environment がある場合は、招待します（書き込み操作です。environment · 各招待者のメールアドレス を提示し、承認を待ちます）。ない場合は、人に Studio Labs から招待してもらいます。デフォルトは本人のみです。

11. 環境でゲームを実行できることを確認します。 人に次の 2 つの質問をして、両方の回答を integration.json → sdkSetup に記録します。

    • 「ゲームのオンラインバックエンドを稼働させずに、キュレーション対象のスライスをプレイできますか？ できない場合、オフラインモード用のプリプロセッサーゲート（例：LUDEO_OFFLINE_MODE）は存在しますか。それとも前提条件として新たに実装する必要がありますか？」— sdkSetup.offlineBackend に "works" | "gate-exists:<flag>" | "gate-needed" のいずれかとして記録します。gate-needed の場合、以降のフェーズのブロッカーとなるため、その旨を明示します。
    • 「コールドブートからキュレーション対象のスライスを読み込むための、正確なコマンド／チート／呼び出しは何ですか？ マップ名を指定した ServerTravel ですか？ ゲーム固有のステートマシン呼び出しですか？ エディターの PIE のみですか？」— sdkSetup.sliceLoadCommand に記録します。デフォルトの ServerTravel は、独自の読み込み経路を持つゲーム（例：ActionGame の UGameStateMachine::RequestSoloGame）では、何も起きずに処理されることがあります。

12. キックオフ時のヒアリングを実施します。 <skill-base-dir>/references/phase-01-know-your-game.md を読み込み、4 つの質問グループについて人と確認します。所要時間は 20〜30 分を目安にします。回答は integration.json → intake に記録します。不明な回答はブロッカーではなくリスクとして扱い、該当事項が前提となるフェーズで再確認します。フェーズ 3 と 4 の事前チェックリストはこのブロックを読み込み、必須項目が不足している場合は失敗します。

13. sdk_set_up · finished を報告し、ただちにフェーズ 2 に移行します。

利用可能なツール

BP Inspector（RunBPInspector.bat）

Blueprint の変数メタデータを読み書きします。UE Editor 内で実行されます（ヘッドレス）。Python Editor Script Plugin が必要です（Phase 1 の手順 7 で有効にしてください。有効になっていない場合、スクリプトは何もせずに終了します）。LudeoBPInspector C++ plugin も導入されている場合（Phase 1 の手順 7）、SaveGame フラグ、レプリケーションフラグ、デフォルト値、コンポーネントを含む完全なイントロスペクションが可能です。プラグインがない場合は、.uasset のバイナリスキャンにフォールバックします（変数名と型のみ。フラグ、デフォルト値、コンポーネントは対象外です）。

コマンド：

コマンド	内容
RunBPInspector.bat inspect	すべてのゲームプレイ BP をスキャンし、レポートを .ludeo/bp-inspection-report.json に書き込みます。所要時間は 30〜60 秒です（エディターの起動時間を含む）。run_in_background: true を指定して実行してください。
RunBPInspector.bat set-savegame <bp_path> <var_name> true|false	1 つの BP 変数の SaveGame フラグを設定または解除します。C++ plugin が必要です。BP を自動的にコンパイルして保存します。
RunBPInspector.bat set-savegame-batch <bp1> <var1> <bp2> <var2> ...	1 回のエディターセッションで複数の変数の SaveGame フラグを設定します（変数ごとに実行する場合の 30〜60 秒に対し、合計で約 30〜60 秒）。効率化のため、BP ごとにまとめて処理します。常に true に設定します。C++ plugin が必要です。複数の set-savegame 呼び出しを連続して実行する代わりに、こちらを使用してください。
RunBPInspector.bat graph	すべてのゲームプレイ BP の関数、イベント、呼び出しグラフをスキャンします。.ludeo/bp-graph-report.json に書き込みます。C++ plugin が必要です。run_in_background: true を指定して実行してください。
RunBPInspector.bat graph-function <bp_path> <function_name>	1 つの BP 内にある特定の関数またはイベントの exec ピン呼び出しグラフを取得します。ノードの順序付きリストをログファイルに出力します。C++ plugin が必要です。
RunBPInspector.bat inspect-path [--resolve-inherited] <bp_path> [<bp_path> ...]	パスで指定した特定の BP の、フィルターなしの完全なダンプ（親、変数とデフォルト値、コンポーネント、関数、イベント）を出力します。inspect のフィルター対象外となる通常の Actor BP（スポーナー、武器アクター、AI マネージャー、ピックアップ）に使用します。.ludeo/path-inspection.json に書き込みます。--resolve-inherited を追加すると、BP の親階層もたどり、基底クラスで宣言された（継承された）変数も含めます。リーフのダンプに期待する状態（例：Health/IsDead）が表示されない場合、BP の基底クラスで宣言されている可能性があるため、こちらを使用してください。
RunBPInspector.bat inspect-level <map_path> [<focus_keyword> ...]	マップを読み込み、実際に配置されたアクターを列挙します。クラスのヒストグラムと、スポーン／AI アクターごとの BP プロパティを出力します。厳選されたマップに何が配置／スポーンされているかを確認できます（アセットのみを対象とする inspect では確認できません）。.ludeo/level-inspection.json に書き込みます。
RunBPInspector.bat inspect-func-sigs <bp_path> [<bp_path> ...]	各 BP 関数の入力／出力ピンのシグネチャを出力します。これは、graph／graph-function（ノードのタイトル）や inspect（変数）では表示されないパラメーターの形状です。ゲーム関数（例：インベントリの AddItem）を呼び出す必要があり、正確なピンを確認したい場合に使用します。.ludeo/func-sigs.json に書き込みます。C++ plugin が必要です。

レポート JSON の形式（全コマンド）：レポートを読み込む前に references/bp-inspector-reference.md を参照してください。

Kismet バイトコードダンプ（RunKismetDump.bat + tools/LudeoKismetDump/ プラグイン）

コンパイル済みの Blueprint バイトコード（レベルスクリプトやゲームプレイ用 BP）を、読みやすいテキストに逆アセンブルします。BP Inspector を補完するツールです。Inspector はアセットごとの変数、シグネチャ、実行グラフを報告し、Kismet ダンプはバインドイベントの配線（BndEvt__ → どの配置済みアクターか、どのデリゲートか）や潜在ノード（Delay、タイムライン）など、プロパティの検査では確認できない実際にコンパイルされたロジックを表示します。「復元後にミッションスクリプトが続行しない」といった問題を調べるためのツールです。

BP Inspector プラグインと同じ方法で導入します。tools/LudeoKismetDump/ を <GameRoot>/Plugins/ にコピーし、.uproject に {"Name": "LudeoKismetDump", "Enabled": true} を追加して、エディターターゲットをビルドします。Shipping/Test では自動的にコンパイル対象外になります。

コマンド	説明
RunKismetDump.bat <Project>.uproject [-Maps=Sub1,Sub2] [-Classes=Sub1] [-OutDir=path]	全マップを対象にしたオフラインダンプ（ヘッドレスのコマンドレット）です。レベルスクリプトクラスごとに、.kismet.txt（逆アセンブル結果）、.events.txt（バインドイベント一覧とコンパイル時に組み込まれた動的バインディング）、.vars.txt（変数と Replicated/SaveGame フラグ）を出力します。さらに、マップごとに _PlacedActorBindings.txt（配置済みアクターのシリアライズ済みデリゲート呼び出しリスト。各 BndEvt__ スタブがどのデリゲートプロパティにバインドされているかを特定します。スタブ名に含まれるのはシグネチャだけです）を <ProjectSaved>/LudeoKismet/<Map>/ に出力します。クラシックなストリーミングサブレベルも走査します（スクリプトが専用の _LSS サブレベルにあることがよくあります）。run_in_background: true で実行してください（約1～5分）。
... -AllPaths（または -Paths=/Game,/Foo）	GameFeature タイトル（Lyra 形式）では必須です。 これらのタイトルではマップは /Game ではなく /<PluginName> にマウントされるため、デフォルトの実行ではすべてのミッションマップが見落とされ、警告も表示されません。-AllPaths は、プロジェクトでマウントされているすべてのコンテンツルートをスキャンします。
LudeoKismet.DisassembleBP <ClassSubstring>（ゲーム内コンソール）	ライブセッション中に、ロード済みクラスをその場で逆アセンブルします。
LudeoKismet.DumpDelegateBindings <ClassSubstring>（ゲーム内コンソール）	条件に一致するワールドアクター上のすべてのマルチキャストデリゲートについて、ライブの呼び出しリストを表示します。「今、このイベントをリッスンしているのは誰か」を確認できます。ゲームプレイ開始後に実行してください。

使用するタイミングとダンプの読み方： references/kismet-bytecode-analysis.md では、イベントスタブから ubergraph オフセットを読み取る手法と、復元時のセマンティクスのパターン（デリゲートハンドラーの設定と付与、冪等な再導出処理、重要な潜在状態）について説明しています。Phase 8/9（スクリプト化されたミッション進行状況の Player Flow 復元）と、新しいマップごとのスクリプト対象範囲のトリアージで特に役立ちます。既知の制限事項：UE5 の World Partition セルは走査されません（Persistent Level のスクリプトは引き続きダンプされます）。

使用するタイミング：

• Phase 2： inspect レポートを読み、セーブシステムを分類（SaveGame フラグがある場合は Group 1）し、構造に関する質問に回答します。graph を実行して BP のロジックフロー（BeginPlay が呼び出す処理、イベントハンドラーの動作）を把握します。人間にグラフのスクリーンショットを依頼する必要はありません。特定の関数を対象にしたクエリには graph-function を使用します。
• Phase 5： 人間が変数リストを承認した後、選定したスライスの変数に SaveGame フラグを設定します。inspect を再実行して確認します。
• Phase 8： 拡充用の追加変数を特定します。新たに特定した変数に SaveGame フラグを設定します。
• 任意のフェーズ： 人間にエディターを開いてもらうことなく、BP の構造や動作に関する質問に回答します。

コンソールコマンドを作成したり、人間に SaveGame のチェックボックスを手動で確認するよう依頼したりしないでください。 set-savegame / set-savegame-batch コマンドは、これらの処理をヘッドレスで実行します。2 個以上の変数にフラグを設定する場合は、エディターを何度も起動しないよう、必ず set-savegame-batch を使用してください。

ログファイル： すべてのコマンドは、人間が読める進捗状況とエラーを .ludeo/bp-inspector-log.txt に書き込みます（実行のたびに上書きされます）。ヘッドレスの UE は標準出力を破棄するため、run_in_background によるヘッドレス実行が完了したら、このファイルを読み込んでください。

ステップ 2：リファレンスファイルを読み込む

上記のフェーズマップテーブルから、現在のフェーズに対応するリファレンスファイルを読み込みます。各リファレンスファイルには、そのフェーズの分析チェックリスト、パターン、質問、出力テンプレート、よくある間違いが含まれています。

SDK フィールド名の不一致に関する警告： リファレンスファイルには、SDK のメソッドシグネチャやフィールド名を含むコードスケルトンが記載されています。これらは実際の SDK ヘッダーと異なる場合があります。リファレンスファイルからコードをコピーする前に、SDK ヘッダー（Plugins/LudeoUESDK/Source/）を grep して、正確なフィールド名とメソッドシグネチャを確認してください。リファレンスに Params.ApiKey と記載されていても、SDK ヘッダーが Params.APIKey となっている場合は、SDK ヘッダーを優先します。

ステップ 3：学びを読み込む

コーパスは大規模（約 250 ファイル）で、統合のたびに増えています。各フェーズで全ファイルを読むと、そのフェーズでの本来の作業に必要なコンテキストを消費してしまうため、インデックスを先に確認します。

1. <skill-base-dir>/learnings/INDEX.md をすべて読みます。学びごとに 1 行で、path | tier | phase | hook の形式です。hook は、その学びの適用前提を確認する質問（または質問がない場合はタイトル）です。
2. 現在のフェーズと phase が一致するエントリーは、tier に関係なく、例外なくすべて本文を読みます。フェーズタグはおおむね正確ですが、保守的に付けられているため、これは最低限であり、これだけで作業全体を網羅できるわけではありません。
3. 他のインデックス行すべてについて、hook をこのプロジェクトについて把握している内容（BP のみか、ストリーミングされたマップがあるか、GAS を使っているか、パッケージ化／クラウドが対象か、セーブシステムがないかなど）と照らし合わせます。関連している可能性があるものは本文も読みます。迷ったら読む方を選んでください。本文を読むコストは低く、学びを誤って読み飛ばすと統合が壊れる可能性があります。インデックスの行はポインターであり、学びそのものではありません。インデックスの行だけを根拠に、学びを引用したり適用したりしないでください。
4. フェーズの途中でもインデックスを再検索します。新しいトピック（パッケージ化、一時停止、インベントリの復元、有効化のタイミングなど）に直面したら、インデックスを grep して該当項目を本文まで読み、独自判断で進める前に確認してください。
5. 完全性を相互確認します： インデックスの Total: 件数と、Glob(pattern: "**/*.md", path: "<skill-base-dir>/learnings") の結果を比較します（learn​ings ディレクトリから直接 glob してください。learnings/** のプレフィックスは Windows では機能しません。INDEX.md 自体は件数から差し引きます）。インデックスにないファイルがある場合は、それらも読みます。インデックスが古くなっているため、再生成する（node scripts/generate-learnings-index.mjs）か、不足している行を追加してください。

アンチパターン（ルール 2～3 の理由）： 名前や hook だけをざっと見て、「これは当てはまらない」と判断し、本文を読まないことです。FPSGameStarterKit のエージェントが missing-explicit-auth.md を読み飛ばしたのはこのためです。タイトルに「explicit auth」とあるのを見て、当てはまらないと思い込み、壊れた有効化コードを書きました。hook の行は注意を促すためのものであり、その学びが無関係だと判断するためのものではありません。

tier で絞り込みます：universal と generalizable はゲームを問わず適用されます。game-specific は同じゲームのものだけを読み込みます。

tier の定義（厳守）：

• universal ＝ 前提条件なしで、あらゆる UE Ludeo 統合に適用できる助言です。助言が適用されないプロジェクト固有の条件が 1 つでもある学びは、universal ではありません。
• generalizable ＝ 特定の前提条件が満たされた場合にのみ適用される助言です。学びの本文の最初のセクションに、前提条件（「Precondition」または同等のラベル）を必ず記載します。読者は助言を適用する前に、現在のプロジェクトで前提条件を確認する必要があります。
• game-specific ＝ 特定のゲームのアーキテクチャに基づくものであり、他のゲームで再利用することを意図していない助言です。

判断で学びを引用する前に、エージェントは必ず次のことを行います：

1. 学習の本文全体を読みます。タイトルや概要だけで済ませてはいけません。
2. 学習の前提条件を特定します（generalizable の場合は明示的な前提条件を確認し、universal の場合は本当に前提条件が存在しないことを確認します）。
3. 具体的な証拠（確認したファイル、人間に尋ねて得た回答、実施した実証テスト）によって、現在のプロジェクトで前提条件が満たされていることを検証します。
4. 現在のプロジェクトの証拠から前提条件を検証できない場合、その学習は適用されません。引用も結論の適用もしてはいけません。
5. integration.json に判断を記録する際は、学習を引用し、プロジェクトで前提条件が満たされていることを示す証拠も記載します。前提条件との一致を示さず、学習の名前だけを挙げる判断理由では不十分です。

エージェントが作業を止めるべき危険信号： 学習の結論が「唯一機能する方法」「すべての方法が失敗した」「X を絶対にしてはいけない」などの断定的な表現で、かつ tier: universal である場合は、注意してください。「唯一」「常に」「絶対に」といった表現を含むエンジニアリング上のルールには、ほぼ必ず前提条件があります。適用前に、その学習が実際には generalizable であるべきかを確認してください。

Phase 2（またはそれ以降のフェーズ）で分類を確認する前に、エージェントは references/reference-sample-catalog.md を読み、一致するサンプルがないか確認する必要があります。サンプルとの一致は grep による推測より強い証拠であり、後から確認するのではなく、最初の判断材料にしてください。

このメタルール自体と、そのきっかけとなったインシデントについては、learnings/common-mistakes/do-not-trust-learning-without-verifying-precondition.md を参照してください。

ステップ 4：MCP サーバーを確認する

このスキルでSDKの詳細を確認するための主要な最新情報源は sdk-docs MCP サーバーです。このサーバーは Ludeo SDK のドキュメントを検索します（メソッドのシグネチャ、パラメーター構造体、コールバックチェーン、概念）。スキルに同梱されており、インテグレーターのマシン上で実行されます。SDK作業を始める前に、一度セットアップしてください。

sdk-docs がまだ接続されていない場合は、同梱のテンプレートを使って接続してから続行してください。ホスト型（HTTP）で https://ludeo-mcps-sdk-docs.ludeo.com/mcp にあり、Ludeo のユーザー名（Ludeo メールアドレスのローカル部。例：jane.doe）を設定した X-User-Name ヘッダーが必要です。これは呼び出し元の識別に使われます。

• Claude Code： <skill-base-dir>/config/mcp_config.template.json から sdk-docs のエントリをプロジェクトの .mcp.json にコピーする（または claude mcp add を実行する）とともに、X-User-Name に Ludeo のユーザー名を設定し、その後、新しいセッションを開始してサーバーを接続します。
• その他のエージェント： 同じエントリを、使用するランタイムの MCP 設定に追加します。
• 接続できない場合は人間に伝え、同梱の references/sdk-reference/ ファイルを代替として使用してください。ただし、同梱版で扱うのは概念のみであり、最新のSDKとの間に差異が生じる可能性があるため、その旨を必ず明示してください。

利用可能な MCP サーバーを確認します。

• sdk-docs — 主要サーバーです。SDK API の詳細を確認する際は、どのフェーズでも推測せず、必ずこのサーバーで検索してください。代替手段：同梱の references/sdk-reference/ ファイル（概念のみ）。
• ludeo-context — 利用可能な場合は、会社のナレッジ、QA ワークフロー、リポジトリーのコンテキストに使用します。特にフェーズ 2（マッピング分析）とフェーズ 5～6（QA イベントリストからのトラッキング／リストアおよびアクションの検出）で役立ちます。
• ludeo-mcp — このスキルでは通常、人間が行う Studio Labs プラットフォームの手順（ステップ 1 の項目 10 の環境確認、フェーズ 3 §3.16 でローカル実行を環境にルーティングする Beta Version Name）を扱います。接続されていない場合は、テンプレートからインストールしてください。OAuth でサインインします（プロンプトが表示されたら人間がログインします）。接続するには新しいセッションが必要です。名前にはデプロイメントのサフィックスが付く場合があります。そのため、ツール一覧で ludeo-mcp のプレフィックスに一致するもの、または list_game_environments を探してください。ただし、ludeo-mcp-staging しか接続されていない場合は不十分です。ゲームがどのプラットフォームにあるかを確認し、本番環境の場合は本番用のエントリを追加して、選択内容を sdkSetup.ludeoMcpServer に記録してください。最初に呼び出す前に references/ludeo-studio-mcp.md を読んでください。読み取りは無料、書き込みは確認が必要です。接続できない場合は、そのファイルに記載された手動の代替手段に従い、その旨を伝えてください。
• Perforce MCP（vcs.type == "p4" の場合のみ）— Perforce MCP サーバーが接続されている場合（公式の Perforce P4 MCP を推奨）、edit／add／shelve／submit とストリーム操作には、そのツールを使用します。サーバー名を integration.json → vcs.p4.mcp に記録してください。接続されているサーバーがない場合は null に設定し、代わりに生の p4 CLI を使用します（references/vcs/p4.md を参照）。

必要な MCP が利用できない場合は、config/mcp_config.template.json（上記）からセットアップするか、人間に伝えて同梱の代替手段で作業を進めてください。

ステップ 5：フェーズの作業を実行する

読み込んだリファレンスファイルの指示に従います。 0. 進捗の報告（references/ludeo-studio-mcp.md）に従って進捗を報告します。

1. 各分析サブ項目について TodoWrite 項目を作成します（例：3.1、3.2、…、3.6）。フェーズ全体の項目だけでは不十分です。「すべてのフックポイントについて API エクスポートを確認する」という未チェックの Todo があれば、重要な手順を飛ばさずに済みます。
2. ゲームのコードベースを分析します（ファイルの読み取り、分析チェックリストに沿ったパターンの grep）
3. チャットで計画を提示します。実装する内容、対象のフックポイント、重要な判断を説明します。
4. 人間から簡単な承認を得ます（「よさそうです」／「X を変更してください」）。
5. コードを書く前に、リファレンスファイルの「Implementation Guidance」セクションの冒頭にある事前確認チェックリストを完了します。
6. フェーズのコードを実装します。
7. 判断と調査結果を integration.json に記録します。

フェーズ 3 以降では、質問するより推論を優先してください。コードを分析し、判断して実装します。本当に行き詰まった場合、または選択を元に戻せない場合に限り、質問してください。

ステップ 6：コンパイル修正（必須ゲート）

コンパイル方法： CLI でのコンパイル手順については、学習ファイル learnings/engine-quirks/how-to-compile-ue-from-cli.md を参照してください。コンパイル修正ループには UnrealBuildTool（オプション 1） を使用してください。最も速い方法です。ビルドには 15～120 秒かかるため、run_in_background: true を指定して実行してください。初回使用時は、.uproject の EngineAssociation フィールドから UE_ROOT を、Source/<GameName>/<GameName>.Target.cs からターゲット名を検出してください。

1. 分析に基づいて実装コードを生成します
2. ゲームの .uproject ファイルでプラグインを有効にします
3. コンパイル修正ループ（必須ゲート）：
   • プラグインを無効にしてビルドします（ベースライン）。プラグインなしでゲームのコア部分の変更がコンパイルできることを確認します
   • プラグインを有効にしてビルドします。Ludeo コードがコンパイルできることを確認します
   • エラーを抽出します。コンパイラーエラーには grep "error C" <output>、リンカーエラーには grep "error LNK" <output> を使用します
   • 最初のエラーを読み、修正してから再ビルドします。最大 10 回繰り返します
   • 新しいソースファイルを追加するたびにビルドします。 現在のファイルがコンパイルできるまで、次のファイルは作成しないでください
   • ローカルでコンパイルできない場合： それでもプラグインを有効にし、人間にビルドを依頼する必要があります。エラーを報告してもらい、修正し、再ビルドしてもらいます。この手順を省略してはいけません
   • 両方のビルドが問題なく通るまで、ステップ 7 に進んではいけません
4. コンパイル修正で行った修正を学びとして記録します

ステップ 7a：AI による検証

すべての成果物がスタブではなく実装済みであり、コードがコンパイルでき、パッケージをビルドできることを確認します。

• Output Contract の各項目について、実装され動作しているか、それともプレースホルダー／スタブかを確認します
• スタブ（/* Phase 6+ */、// TODO）がある場合、そのフェーズは未完了です。完了とマークしてはいけません
• 成果物を意図的に延期した場合（人間と合意済み）、その旨を明記します

bIsPlayerFlow の監査（コードを生成するすべてのフェーズ）： プラグインのソース内で bIsPlayerFlow を検索し、各箇所が正しく使われているか確認します。

• ガードする必要があるもの： CreateWritableObjects()、UpdateWritableObjects()（状態の書き込みは Creator のみ）
• ガードしてはいけないもの： RegisterActionListeners()、OnActorSpawned()、DetectPollBasedActions()、ReportAction()（アクションとエンティティの追跡は、どちらのフローでも動作する必要があります）
• 連鎖するガードに注意： CreateWritableObjects() にある bIsPlayerFlow のチェックが、CreateWritableObjects() が設定するエンティティリストに RegisterActionListeners() が依存しているため、間接的にアクション登録を妨げる場合があります。呼び出しチェーンをたどってください。直接的なガードだけを確認して終わらせてはいけません。

ルーム開始タイミングの監査（ライフサイクルに関わるコードを生成するすべてのフェーズ）： Session::OpenRoom がコンポーネントの BeginPlay（レベル読み込み時）から呼び出されており、ウォームアップ／カウントダウン／「Playing」／「combat」／興味深い状態のフェーズを条件としていないことを確認します。ゲームフェーズを待ってよいのは BeginGameplay（N ウェイゲート）だけです。コンポーネントで OpenRoom を検索し、呼び出し元をたどってください。ゲームフェーズの監視処理（例：WhenPhaseStartsOrIsActive(Playing) → … → OpenRoom）から OpenRoom に到達する場合、それが不具合です。遅れて開かれた Creator ルームには OnRoomReady が届かず、何も記録されません。OpenRoom を BeginPlay に移し、フェーズで待機させるのは BeginGameplay だけにしてください。比較できる参照サンプルがない場合も、このルールは変わりません。learnings/common-mistakes/open-creator-room-at-level-load-not-on-phase.md および references/phase-03-lifecycle.md §3.2 の必須ルールを参照してください。

フェーズ 5 の厳格なゲート：フェーズ 6 に進む前にプレイヤーフローを確認

フェーズ 5 には通常のフローに優先する、必須の実行順序があります。 フェーズ 5 と 6 を単一の計画にまとめてはいけません。プレイヤーフローが動作しなければハイライトを再生できないため、プレイヤーフローが動作しない状態ではフェーズ 6 のアクションに意味はありません。

フェーズ 5 の必須実行順序：

1. クリエイターフロー（書き込み側）を実装 → コンパイル → 書き込みが動作することを確認（ログをチェック）
2. プレイヤーフローのサブシステムロジック（GetLudeo + 状態の読み取り + ServerTravel）を実装 → コンパイル
3. プレイヤーフローのコンポーネントロジック（保留中の Ludeo を検出 + エンティティに状態を適用）を実装 → コンパイル
4. 人間がエンドツーエンドでテスト： ハイライトをキャプチャ → 再生 → 位置が復元されることを確認
5. 人間がプレイヤーフローの動作を確認した後にのみ → フェーズ 6 に進む

このゲートがある理由： エージェントは一貫してプレイヤーフローをスタブ化し、フェーズ 5 が完了したと主張します。クリエイターフローは自己検証可能（ログに書き込みが表示される）ですが、プレイヤーフローにはキャプチャ済みの Ludeo が必要です。エージェントはクリエイターフローを書いて検証し、プレイヤーフローは「テスト時に接続される」と合理化します。しかし、実際に接続されることはありません。スタブはフェーズ 6 以降にも残ります。このゲートにより、プレイヤーフローの検証はフェーズ 6 に進むための必須条件になります。

プレイヤーフローがブロックされている場合（例：適切なマップへの移動方法がわからない、ヘルスのセッターが動作しない、GAS のタイミングの問題）：人間に尋ねてください。 スタブ化して先に進んではいけません。「テスト時まで保留」と記録してもいけません。実装するか、支援を求めてください。

ステップ 7b：人間による検証（厳格なゲート）

コンパイルとパッケージ化で証明できるのはコードがビルドされることだけで、動作することではありません。 実行時テストのチェックリストを人間に提示し、先に進む前に確認を待ってください。コンパイルに成功しただけでドキュメントを作成したり、フェーズを完了としたり、「完全に検証済み」と言ったりしてはいけません。

人間に次のように伝えてください：

「コードはコンパイルされ、パッケージ化されています。次の実行時検証手順を実行し、結果を報告してください： [参照ファイルのセクション 7 にある、このフェーズ固有のテストチェックリストを提示] 何が動作し、何が動作しなかったかを報告してください。」

packagingTarget が packaged または cloud-build の場合、人間は PIE ではなく、新たにパッケージ化したビルドをテストする必要があります。 PIE は新しいエディター DLL を実行しますが、パッケージにはクック時のバイナリが埋め込まれます。そのため、以前のフェーズでクックしたパッケージには、それ以降に実装されたものがひそかに含まれていません。パッケージで機能が「欠落」している場合、多くはコードのバグではなく古いクックが原因です。パッケージ実行をコードの結果として扱う前に、BuildAndPackage.bat を再実行し（チェックリストにもその旨を記載してください）、古さを積極的に確認してください。パッケージ化された実行ファイルの mtime を最新のプラグインソースの mtime と比較し、ソースにはもう存在しない「ゴースト」文字列がパッケージ化されたログにないか grep してください。learnings/common-mistakes/stale-package-masquerades-as-missing-feature.md を参照してください。

人間が実行時テストの合格を確認するまで、ステップ 7c に進んではいけません。 人間から失敗の報告があった場合は、修正して再検証してください（必要に応じてステップ 6 のコンパイル修正に戻ります）。

ステップ 7c：ドキュメント作成

AI による検証と人間による検証の両方に合格した後：

1. .ludeo/tdd/integration-tdd.md のこのフェーズのドキュメントセクションを作成または更新する
2. 実装内容、重要な判断、使用したフックポイント、初期計画からの逸脱を記録する
3. これは記録であり、レビューのゲートではありません。簡潔かつ事実に即して記載してください

ステップ 8：レビューを開始

人間から依頼があった場合に限り、コンパイル修正に合格した後、読み込まれた vcs/<type>.md に従って open_review を実行します：

1. git → GitHub PR を作成します。p4 → 作業中の changelist を shelve し、Swarm レビューを作成します（または CL を引き継ぎます）。
2. レビューフィードバックに対応する
3. 修正内容を学びとして記録する

ステップ 9：フェーズ後の調整

レビューがマージ／送信された後（または人間がフェーズの完了を伝えた後）：

1. 実装に関する修正内容を学びとして記録する
2. integration.json を更新する：
   • 現在のフェーズのステータスを completed に設定し、completedAt に日付を記録する
   • currentPhase を次のフェーズに進める
   • 次のフェーズのステータスを in_progress に設定する
3. 進捗の報告に従って進捗を報告する

---

状態ファイルのスキーマ

このスキルは、対象ゲームのリポジトリに .ludeo/integration.json を作成します。ゲームの識別情報、currentPhase とフェーズごとのステータス（ステップ 1 ではこれらを読み取り、再開します）、セーブシステムの分類と根拠、キュレーション済みスライスの定義、packagingTarget、VCS 設定、SDK のセットアップ、および蓄積された decisions／findings を記録します。

フィールドごとの注記を含む完全なスキーマ：references/state-file-schema.md — ファイルを作成する前（フェーズ 1 のステップ 8）または新しいトップレベルフィールドを追加する前に、これを読んでください。更新時は、認識できないフィールドも保持してください。フェーズが進むにつれて、ベーステンプレートにないフィールドが追加されることがあります（例：intake、pauseMechanism、skillImprovementNotes）。テンプレートからファイルを書き直さないでください。

---

実装後のドキュメント

各フェーズのコードがコンパイルされた後（ステップ 7）、.ludeo/tdd/integration-tdd.md にドキュメントのセクションを書き込みます。

## Phase N: [Phase Name]

### What was implemented
- [List of classes, files, hook points added]

### Key decisions
- [Decision]: [Rationale] (e.g., "Used OnMatchStateChanged instead of OnMatchStarted because it fires after state replication")

### Hook points used
| Game Hook | SDK Call | File:Line |
|-----------|---------|-----------|
| ... | ... | ... |

### Deviations from plan
- [What changed during implementation vs. initial analysis]

これは記録であり、レビューの承認条件ではありません。簡潔かつ事実に即して記述してください。

---

レビューサイクル

TDD が承認され、コードが実装された後（open_review を使用 — ステップ 8 と references/vcs/<type>.md を参照）：

1. レビューに出します。git の場合は PR、p4 の場合はシェルフされた変更リストと Swarm のレビューを使用します。
2. 人間がレビューし、フィードバックを提供します。
3. スキルはフィードバックに基づいてコードを反復改善します。
4. マージ／提出後、実装上の修正点を学びとして記録します。
5. 実際の内容と計画を比較して TDD を更新し、設計と比べて実装中に変更された点を記録します。

---

学習の記録

学習内容は追記専用です。 新しいファイルは learnings/{category}/ に追加します。既存の学習ファイルは、人間による明示的な承認なしに削除または上書きしてはなりません。learnings/ ディレクトリ構成（architecture/、save-systems/、common-mistakes/、engine-quirks/）は、あらかじめ存在している必要があります。存在しない場合は、足りないサブディレクトリのみを作成し、ツリー全体を再作成してはなりません。破壊的な操作に対するガードを参照してください。

フェーズの終了時だけでなく、発見した時点で学習内容を記録します。 以下のいずれかが発生した場合は、続行する前に学習内容（またはスキル改善のメモ）を書き留めてください。詳細や文脈が失われるフェーズの最後まで、記録を先送りしてはなりません。

• 修正に複数回の試行が必要だった、または根本原因が最初の想定と異なっていた。
• SDK、エンジン、または環境の動作が、スキルやそのドキュメントの記述と異なっていた。
• 人間から訂正を受けた、またはリファレンス統合から逸脱した。
• 明白でない前提条件、順序の要件、または正確な API シグネチャを発見した。

すぐに書き留めるのは簡単で、文脈も新鮮です。先送りすると、学習内容を再利用可能にする具体的な情報が失われます。references/learning-sanitization.md に従ってサニタイズしてください。再利用可能な学習内容か、一度限りのものか判断できない場合は、学習内容として扱い、簡潔に記録してください。

TDD レビューまたは PR フィードバックでスキルに修正が入った場合：

1. トピック別に分類します：

   • architecture — プラグイン構成、サブシステムの設計、コンポーネントのパターン
   • save-systems — セーブシステムの分類、シリアライズ、SaveWorld に関する判断
   • common-mistakes — スキルが過去に起こしたエラー
   • engine-quirks — UE 固有の注意点（UHT、レプリケーション、GAS）

2. 適用範囲別に分類します：

   • universal — すべてのゲームに適用されます。今後の統合でそのまま使用します。
   • generalizable — 幅広く適用できますが、実装は異なります。今後の統合に備えて「人間に尋ねる質問」を含めます。
   • game-specific — このゲームにのみ関係します。他のゲームには適用せず、例として保存します。

3. learnings/{category}/ にフロントマター付きで書き込みます：

   ---
   category: architecture
   tier: universal
   sourceGame: ActionGame   # abstract codename only — see allowlist below
   phase: 1
   question: null
   sanitized: true             # attest you ran the sanitization checklist
   ---
   

   generalizable の場合、question には今後の統合でスキルが尋ねるべき質問を記載します（例：「このゲームのセーブシステムは、任意のセーブポイントに対応していますか。それともチェックポイントのみですか？」）。

   続いて、インデックスに登録します： 学習内容の行を learnings/INDEX.md に追記します（既存の形式 path | tier | s<phase> | question-or-title に合わせます）。可能であれば、node scripts/generate-learnings-index.mjs を実行します。ステップ 3 では最初にインデックスを読み込みます。インデックスにない学習内容は、後続のフェーズから参照できません。

4. 保存前のサニタイズは必須です。 学習内容は、今後の統合で 別のクライアント向けにも 読み込まれます。クライアント固有の情報が残っていると、そのクライアントのコードが他のすべてのクライアントに漏えいします。移転可能なパターンを記録し、クライアント固有の情報は決して記録しないでください。sourceGame: には許可リストにある抽象的なコード名（config/learning-policy.json）を使用します。クライアント識別子は中立的な役割ベースの名前に置き換え、Ludeo SDK と標準の UE 識別子はそのまま記載します。 確認方法： 読者がクライアントを特定できたり、クライアント固有の内容をコピーして貼り付けられたりしませんか。該当する場合は、サニタイズされていません。これは learnings/ だけでなく、コミットするすべてのファイルに適用されます。 クライアントのタイトル、クラス名やマップ名、リポジトリのパスを含む計画ドキュメントやメモは、決してコミットしないでください。

   ルール全文、チェックリスト、命名規則、翻訳キーについては、references/learning-sanitization.md を参照してください。学習内容を書く前に必ず読んでください。 scripts/validate-skill.mjs は、構造に関する要件を検証します。

5. 今後の統合では、TDD を生成する前に、フェーズとカテゴリで絞り込んだ関連する学習内容を読み込みます。

---

MCP 設定

このスキルには、MCP サーバーの定義が config/mcp_config.template.json に含まれており、セッション開始時にその設定を確認します。**これらのサーバーはインテグレーターのマシン上で実行されます。インストール済みのスキルの一部であり、このリポジトリのツールではありません。**該当する項目をエージェントの MCP 設定にコピーし（Claude Code の場合は、プロジェクトのルートにある .mcp.json、または claude mcp add）、伏せられている認証情報を入力して、新しいセッションを開始すると接続されます。

サーバー	ホストされているエンドポイント	目的	フォールバック
sdk-docs	https://ludeo-mcps-sdk-docs.ludeo.com/mcp（HTTP、X-User-Name ヘッダー）	Ludeo SDK ドキュメントの検索 — API リファレンス、メソッドシグネチャ、パラメーター構造体、コールバックチェーン	同梱の references/sdk-reference/ ファイル（概念のみ）
ludeo-context	https://mcp-ludeo-context-internal.ludeo.com/mcp（HTTP、ベアラートークン）	企業ナレッジ、QA ワークフロー、リポジトリのコンテキスト、統合テンプレート	使用せずに進めます。分析の品質が低下する場合があります
ludeo-mcp	https://mcp.ludeo.com/mcp（HTTP、OAuth サインイン）	Studio Labs のプラットフォーム作業 — 通常はエージェントが人に依頼する、環境の設定、ローカル実行を環境に振り分ける Beta Version Name の設定、招待の送信	Studio Labs で作業を行うよう人に依頼します

各 MCP の使用方法：

• sdk-docs：すべてのフェーズで使用します。スキルがSDK ドキュメントを参照または検索するときに利用してください。これはドキュメント検索サーバーです。推測したり、同梱の概念ファイルを使ったりするより、こちらを優先してください。
• ludeo-context：フェーズ 2（マッピング分析）、フェーズ 5～6（QA イベントリストからのトラッキング／復元およびアクションの発見）。
• ludeo-mcp：フェーズ 1（環境の検索）およびフェーズ 3 §3.16（ローカル実行を環境に振り分ける Beta Version Name。クラウドビルドは builds assign で割り当てます）。接点、頻度、読み取り／書き込みのポリシーについては、references/ludeo-studio-mcp.md を参照してください。読み取りは確認不要、書き込みは確認が必要です。

サーバーが検出されない場合は、フォールバックに頼る前に config/mcp_config.template.json から設定し（手順 4 を参照）、使用するフォールバックを人に伝えてください。

---

リファレンスファイルの構成

各フェーズのリファレンスファイル（references/phase-*.md）は、一貫したセクション構成になっています。

分析フェーズ（フェーズ 2）では、7 つのセクションを使用します。

1. 目標 — このフェーズで作成するもの（具体的な成果物）
2. 入力 — 開始前にスキルが必要とする情報と、正式な入力契約（前フェーズの出力、ゲーム情報）
3. 分析チェックリスト — コードベースで確認する内容と利用可能なメソッド（grep パターン、クラス階層、デリゲート宣言）。MVP フェーズ（3～5）では、厳選された範囲に限定されます。
4. 人に確認する質問 — コードから推測できない判断に限ります
5. 適用するパターン — 過去の統合（Lyra、FPS Kit）で使用した汎用パターン
6. ドキュメントテンプレート — 実装後に記録する内容
7. よくある間違い — 過去の統合でこのフェーズに発生した誤り

コードを生成するフェーズ（フェーズ 3～9）では、8 つ目のセクションが追加されます。

7. 実装ガイダンス — プラグインのスキャフォールド、クラスの骨組み、コンパイル修正ループ、設定。フェーズ 3 では、references/templates/ のテンプレート駆動型アプローチを使用します。
8. よくある間違い — （7 から 8 に移動）

リファレンスファイルは必要に応じて読み込まれます。現在のフェーズのファイルのみがコンテキストに読み込まれます。

---

参考サンプルと得られた知見

• references/reference-sample-catalog.md — 正常に動作することが確認済みの統合リファレンスサンプル（FPSGameStarterKit、Lyra、VoyagerV2 など）を、マッチ条件とそれぞれが示す分類とともにまとめた信頼できる一覧です。最初から分類を推測する前に、必ずこちらを確認してください。サンプルとの一致は、grep に基づく推論よりも有力な根拠です。これらの統合で確立されたパターンと判断の根拠は、learnings/ にもまとめられています（sourceGame で絞り込んでください）。
• references/game-patterns/ — ジャンルと構造に関するプレイブック（アクションのカタログ、追跡チェックリスト、Unreal の grep イディオム、オープンワールドのセッション方針、ターン制の進行周期）。フェーズ 02／05 でジャンルごとに読み込み、INDEX.md で分類します。
• learnings/ — 過去の統合から得られた、カテゴリ別の修正事項です。トピック別に整理されています（architecture/、save-systems/、common-mistakes/、engine-quirks/）。各ファイルには、ティア、フェーズ、元のゲームで絞り込むためのフロントマターがあります。

これらは必要に応じて読み込み、現在のフェーズの要件に基づいて絞り込みます。

---

セーブシステムの分類

ゲームはフェーズ 2 で、次の 3 つのグループに分類されます。

グループ	説明	統合戦略
1 — フルセーブ	既存のセーブシステム（例：SaveGame クラス）があるゲーム	既存のシリアライズを活用します。SaveWorld の候補となる可能性が高いです
2 — チェックポイントのみ	固定地点でのみセーブするゲーム	任意の地点でセーブできるよう、チェックポイントシステムを拡張します
3 — セーブなし	セッションをまたぐ永続化機能がないゲーム	状態キャプチャを一から構築します（AI が最も価値を発揮できます）

この分類は、フェーズ 5（厳選した状態追跡と Player Flow の復元方法）およびフェーズ 8〜9（ゲーム全体の対応と仕上げ）の判断に影響します。

---

質問する場合と推測する場合

コード分析から推測する項目：

• イベントシステム（DECLARE_DYNAMIC_MULTICAST_DELEGATE、UGameplayMessageSubsystem、カスタムイベントバスを grep します）
• フェーズ／状態マシン（状態列挙型、フェーズマネージャー、ゲームモードの状態）
• セーブシステム（SaveGame クラス、シリアライズ呼び出し、チェックポイントのロジック）
• エンティティの種類（ポーンクラス、キャラクタークラス、AI コントローラー）

人間に確認する項目：

• 有効な方法が複数ある場合（書き込み頻度、重複排除の戦略、SaveWorld と手動方式のどちらにするか）
• ゲーム固有のドメイン知識が必要な場合（「重要なアクションとは何ですか？」）
• コード分析だけでは判断が曖昧な場合（「このデリゲートは適切なフックポイントですか？」）
• パフォーマンス上のトレードオフに判断が必要な場合（状態のサイズと更新頻度）
• コードから順序やタイミングの依存関係が明らかでない場合（遅延する体力、フェーズのスキップ）
• 確信を持って判断できるほど明確でないことがあれば、必ず人間に確認してください。
• 確信がない場合は、わからないと伝えてください。推測して間違えるより、質問するほうが適切です。

コンパイルやパッケージ化の成功だけを根拠に、「検証済み」や「フェーズ完了」と決して主張しないでください。 コンパイルで確認できるのはコードがビルドできることだけであり、実行時に動作することではありません。必ず実行時テストのチェックリスト（ステップ 7b）を提示し、人間の確認を待ってください。これは最もよく起こるプロセス上の失敗です。エージェント自身ではゲームを実行できないため、実行時の検証を省略してもよいと正当化してしまいます。

デバッグと診断のゲート

人間からランタイム障害の報告や診断に関する質問があった場合、チャットでは調査結果 → 根本原因 → 変更案の順に提示します。**人間が診断結果を確認してから、実装を開始します。**診断中にコードの編集を始めてはいけません。

根本原因が確認される前に、推測に基づく緩和策を講じてはいけません。リトライループ、タイムアウト、強制開始タイマーなどの回避策は、検証済みの根本原因を人間が確認するまで禁止です。これらは Ludeo の忠実性を損ない、実際のバグ（壊れたライフサイクル）を修正する代わりに覆い隠してしまうことがよくあります。回避策は、原因が特定された問題に対する修正であり、調査のために使うものではありません。

修正を提案する前に、学習内容を grep で検索し、一致した項目を引用してください。コーパスには、よくある障害の種類がすでに記録されています。修正を提案する前に、learnings/ を症状について検索し、一致する学習内容（または該当するものがないこと）を示してください。特に、「最初のルームまたはセッションでは正常に動作したのに、それ以降のルームまたはセッションで SDK のシグナル／通知が届かない」（例：N>1 のルームで OnRoomReady が一度も発火しない）場合、原因はほぼ間違いなくあなたのライフサイクルにあります。まずルーム N-1 のティアダウンを調査してください。learnings/common-mistakes/dont-bypass-sdk-when-your-lifecycle-is-broken.md、learnings/architecture/detached-teardown-for-game-initiated-travel.md、learnings/architecture/onroomready-is-the-viewer-connected-gate.md（ローカル実行時の診断順序を含む）を参照してください。構造に関する仮説（「ローカル再生にはビューアーがいないため、OnRoomReady が発火しない」など）をでっち上げてはいけません。OnRoomReady はオーバーレイ経由で、ローカルでも必ず届きます。