ludeo-unity-integration

Unity 向け Ludeo SDK 統合

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

⚠️ v4.3.0では、SDKが互換性を破る形で書き換えられました。 古いプラグイン（InitLudeoSession、LudeoStateObject／SetAttribute、AddNotify*、LudeoGameplaySession）で統合している場合は、references/ludeo-integration-docs/12-SDK-API-REFERENCE.mdの「What changed in v4.3.0」テーブルを参照してください。初期化はInitialize()+SessionManager.CreateSession、通知はC#イベント、キャプチャはLudeoRoom.Writer+スコープ付きWriteData経由となり、ゲームプレイセッションはLudeoPlayerになりました。

このスキルでは、パッケージのインストールからアクションマッピング、オブジェクトのトラッキング、状態の復元、ランタイム検証まで、Ludeo Unity plugin（マネージドLudeoSDK C# API）を使用してUnityゲームにLudeo SDKを統合する手順をエージェントに案内します。

これはUnity専用のスキルです。 C++／独自エンジンの場合は、代わりにludeo-unreal-integrationを使用してください。両者は同じワークフロー手法を共有していますが、ここではすべてUnity／C#の慣用表現（MonoBehaviourのライフサイクル、シーン、プレハブ、LudeoSDKマネージドAPI）で説明しています。

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

使用するタイミング

次のいずれかをユーザーが言ったときに、このスキルを有効にしてください。

• 「自分のUnityゲームにLudeoを統合して」
• 「UnityでLudeo SDKをセットアップして」
• 「Ludeoのアクショントラッキングを追加して」（Unityプロジェクト）
• 「Ludeo SDKを使ってUnityゲームをビルドして」
• 「UnityでLudeoのライフサイクルを接続して」

プロジェクトがUnityではない場合（Assets/、ProjectSettings/、Packages/manifest.json、.asmdef／.unityファイルがない場合）は、作業を中止し、ユーザーに適切なエンジン向けのスキルを案内してください。

最初に読む

UnityプロジェクトにC++／メインループの前提を当てはめないでください。 存在しないもの（main、ゲーム側で実装するループ、ビルドスクリプト）を探すことになり、存在するもの（シーン、MonoBehaviourのコールバック、プレハブ、インストール済みパッケージ）を見落とします。Unityの構造モデル全体とコードベースのスキャン用検索パターンはフェーズ2（references/2-map-game-code.md）に記載されています。以降の各フェーズには、必要なUnity固有の前提が組み込まれています。

フェーズ1の前に、C#ラッパー向けに再調整された必須ルールを記載した**references/ludeo-integration-docs/00-CRITICAL-REQUIREMENTS.md**を確認してください。

このスキルにはlearnings/に組織内の知見があります。これは、以前の統合で得られた、個人情報などを除去済みの修正事項です。各フェーズの開始時に関連する知見を読み込み、新たな知見を発見したらすぐに記録してください。 読み込み／記録のルールについては、以下の**知見**を参照してください。これは任意ではありません。

ワークフロー

この統合は順次進めるワークフローであり、従来のファイル番号（番号の振り直しは保留）ではなく、8 フェーズのガイドライン順（表の Phase 列）に沿って進みます。 順序は次のとおりです。1 インストール＋KYG → 2 コードのマッピング → 3 SDK のライフサイクル → 4 オブジェクトのマッピング → 5 トラッキングと復元（キャプチャをプレイ可能な Ludeo にする反復型のウェーブループ — Wave 1 は復元可能な基盤で、その後、対象を広げます）→ 6 アクション → 7 検証とアップロード → 8 仕上げと完了。ガイドラインに従い、アクション（フェーズ 6）はトラッキングと復元（フェーズ 5）の後に実施します — アクションを充実させる前に、プレイヤーフロー（Wave 1 で復元）が実証されます。フェーズ 8 は行き止まりではなく、ループです。 Ludeo がまだキャプチャできる状態を確認して提案し、ユーザーが拡張を希望する場合は、フェーズ 4 と 5 に再度入り、新しいウェーブとして追加します（その後、フェーズ 7 で対象を拡大したビルドを再アップロード）。その後、最終処理を行います。ユーザーが前のフェーズを完了したと伝えていない限り、必ずフェーズ 1 から開始してください。一度に 1 つのフェーズを完了し、次に進む前にユーザーに確認してください。トップレベルから各フェーズの開始と完了を報告し、references/ludeo-studio-mcp.md の 進捗の報告に従ってください。また、ディスパッチするすべてのサブエージェントに、ludeo-mcp ツールを呼び出さないよう伝えてください。

フェーズ 3、5、6 はオーケストレーションされます。 各フェーズは、単一タスクのブリーフで構成される 1 つの論理的なガイドラインフェーズです。薄いオーケストレーターがタスクごとに 1 つのサブエージェント（Agent ツール）をディスパッチし、成果物をファイル経由で受け渡すため、ユーザーにはそれぞれが単一のフェーズとして体験されます。

• フェーズ 3（「SDK のライフサイクルを計画して実装する」）は references/3-lifecycle-orchestrator.md に従います。タスク 1～4 は自動的に実行され、コンパイルと実行のゲートは人間に提示されます。
• フェーズ 5（「トラッキングと復元」）は references/5-tracking-restore-orchestrator.md に従い、反復型のウェーブループとして実行されます。フェーズ 4 で 全体調査＋ウェーブ計画を作成し、フェーズ 5 ではそれを一度に 1 つのウェーブずつ実装します — ウェーブごとに、詳細なスコープ設定（タスク 0）→ キャプチャ（タスク 1）→ 復元計画（タスク 2）→ 再構築（タスク 4）の順に進め、復元のフロー（タスク 3）は Wave 1 で 1 回だけ構築します。Wave 1 では、復元可能な基盤＋必須セットを対象に、キャプチャから再生までの完全なラウンドトリップを実証します。それ以降の各ウェーブで、トラッキング対象を広げます。すべてのサブタスクは、オーケストレーターが実行するゲートで終了します。各ゲートを分けてください。 エージェント自身がコンパイル部分を検証します（ヘッドレスの -batchmode で実行し、ログを読み取ります — インタラクティブな Console はありませんが、Console の出力はログに記録されています）。人間が担当するのは、人の判断が必要な部分だけです。キャプチャ／再生のゲートでは、人間が Ludeo をキャプチャして再生し、忠実度を判断する必要があります。ゲートに失敗した場合は、ログを渡して修正用サブエージェントを再度ディスパッチします — 失敗の原因が状態にある場合は、前のウェーブを再度開きます。
• フェーズ 6（「アクション」）は references/6-actions-orchestrator.md に従います。マッピング → 実装の後、人間がコンパイルとログを 1 回確認します（各アクションは Creator と Player の両方のフローで出力される必要があります）。 | フェーズ | ファイル | 目的 | | --- | --- | --- | | 1 | references/1-build-game-with-sdk.md | 最新のプラグインリリースをダウンロード（github.com/ludeo-labs/unity-plugin-releases）＋ UPM パッケージをインストールし、スクリプト定義と LudeoSettings を設定。SDK 有効化前後のコンパイルを実施し、KYG（ゲームを知る）を実行（ゲームレベルのセーブシステム分類を含む） | | 2 | references/2-map-game-code.md | Unity プロジェクトの CODE_MAP を作成（シーン、MonoBehaviour、プレハブ、マネージャー） | | 3 | references/3-lifecycle-orchestrator.md | SDK ライフサイクル（オーケストレーション）— 以下の 5 つの概要をサブエージェントとしてディスパッチし、復元エントリーポイントと Non-Gameplay Handling を計画します | | 3 · task 1 | references/3a-find-sdk-integration-points.md | 各ゲームイベントから [SDK]／[Layer] 呼び出し箇所への対応付け | | 3 · task 2 | references/3b-create-tdd.md | 技術設計ドキュメント（アーキテクチャ、戦略、リスク）を作成 | | 3 · task 3 | references/3c-plan-sdk-lifecycle.md | LudeoController レイヤー＋通知登録＋非ゲームプレイ時のイベント送信を計画 | | 3 · task 4 | references/3d-implement-sdk-lifecycle.md | LudeoController／Flow／SessionManager レイヤーを実装し、フックを接続 | | 3 · task 5 | references/3e-compile-and-fix.md | Editor でコンパイル（定義の有効・無効の両方）、修正、キャプチャオーバーレイを確認 — 人間による承認が必要 | | 3f | references/3f-classify-save-system.md | 廃止予定： ゲームレベルのセーブ分類はフェーズ 1 の KYG に移動し、エンティティ単位のマトリックスはフェーズ 4 に移動しました。廃止待ち。 | | 4 | references/4-map-game-objects.md | ガイドラインのフェーズ 4 — 全数調査＋ウェーブ計画（パート A）：追跡可能なオブジェクトのタイプをすべて列挙し、重要なものに印を付け、ウェーブを割り当てます（ウェーブ 1 = 復元の中核＋必須セット）。フェーズ 5 で各ウェーブに対して実施するパート Bの詳細スコープ手順を定めます。ここでは詳細な検討やコード作成は行いません | | 5 | references/5-tracking-restore-orchestrator.md | 追跡と復元（オーケストレーション、反復型 WAVE LOOP）— ウェーブ計画を一度に 1 ウェーブずつ実装し、以下の概要をサブエージェントとしてディスパッチします。各サブタスク、各ウェーブごとに人間による承認ゲートを設けます | | 5 · task 0 | references/5a-deep-scope-wave.md | **ウェーブごと：**このウェーブのタイプを詳細にスコープ設定（フェーズ 4 のパート B を実施）→ OBJECT_TRACKING.md に ## Entity 行を追加 | | 5 · task 1 | references/5b-implement-object-tracking.md | **ウェーブごと（追加）：**このウェーブのタイプについて、ILudeoStateHandler の登録とティックごとの属性キャプチャを接続 | | 5 · task 2 | references/5c-plan-state-restoration.md | **ウェーブごと（追記）：**このウェーブの復元計画（objectType バケット、2 パス方式）を作成 → RESTORATION_PLAN.md | | 5 · task 3 | references/5d-implement-restoration-flow.md | 一度のみ（ウェーブ 1 のみ）：復元フローを実装：LudeoSelected→GetLudeo→プレイフロー、フリーズ／オーバーレイ、RoomReady→Begin、ApplyRestoredState() スタブ | | 5 · task 4 | references/5e-implement-state-reconstruction.md | **ウェーブごと（バケットを追加）：**このウェーブの ApplyRestoredState() を実装 — バケットからのスポーンと適用を行う 2 パス方式、参照、遅延プロパティ、環境 | | 6 | references/6-actions-orchestrator.md | アクション（オーケストレーション）— 以下の 2 つの概要をサブエージェントとしてディスパッチします。フェーズ 5 の後（プレイヤーフローの実証後）に実行し、人間によるコンパイル＋ログ確認ゲートを 1 回設けます | | 6 · task 1 | references/6a-map-game-actions.md | ゲームコード内のアクションポイントを特定（プレイヤー視点。フェーズ 3 で計画した非ゲームプレイ時の標準アクションを含む） | | 6 · task 2 | references/6b-implement-game-actions.md | SendAction 呼び出し（ゲームプレイ時＋非ゲームプレイ時）を挿入し、一度限りのプラットフォームのグローバルトリガーマッピングを文書化 | | 7 | references/7-upload-build.md | ガイドラインのフェーズ 7 — リリースビルドを検証（validate-build）し、ludeo CLI で Ludeo プラットフォームに準備・アップロードした後、ステータスが ready になるまで確認 | | 8 | references/8-polish.md | ガイドラインのフェーズ 8 — 仕上げと完了（ループ）。Ludeo がまだキャプチャできる状態がないか確認し、提案します。ユーザーの承認後、フェーズ 4 と 5 に再度入り、新しいウェーブとして追加（フェーズ 7 で再アップロード）します。さらに、見た目やタイミングの仕上げと、以前のバグ修正を行います。最後に、TDD に完了を記録します。独自のディスパッチは行わず、ウェーブループに戻します |

重要なルール

• 一度に進めるフェーズは一つです。 次のフェーズに進む前に、ユーザーの確認を得てください。

• スキルではなくインテグレーター向けに書きます。ただし、製品については説明してください。 用語は3種類あり、それぞれ役割が異なります。

  1. 製品名 — Ludeo、Studio Lab。説明してください。決して避けないでください。 インテグレーターはLudeoを組み込んだ製品を提供し、プレイヤーもその言葉を目にします。初出時に一度、簡潔に定義してください（「Ludeoとは、誰でもそのままプレイできる短いクリップです」）。その後は通常どおり使ってください。わかりやすく見せようとして製品名を避けて書くと、ドキュメントもダッシュボードも、自分たちのバックログも読めなくなります。
  2. SDKのAPI名 — LudeoRoom、WriteData、SendAction。 読み書きするコードそのものが話題である場合は、正確なAPI名を使う必要があります。ただし、API名だけで動作の説明を済ませないでください。「OpenRoomはプレイの取り込みを開始し、CloseRoomは終了します」のように書き、単にOpenRoomとだけ書かないでください。また、この説明では「記録」という言葉を避けている点にも注意してください。以下の言い換えの落とし穴を参照してください。
  3. スキル内部の略語 — CR-006、Wave 1、「two-pass」、「non-ludeoable」、「readiness gate」、案件ごとの課題タグ（SHIP-2）、名詞として使われるフェーズ番号。 これらは私たちの用語であり、インテグレーターには何の役にも立ちません。エージェント同士のやり取りやludeo-integration-plan/内の成果物では問題ありませんが、人が読むものでは、必ずわかりやすい表現に置き換えてください。「CR-006 two-pass」ではなく、「シードからレベルを再構築してから、オブジェクトを元に戻す」のように書きます。IDを記載する意味がある場合（成果物がIDで管理されている場合）は、平易な説明の後ろに括弧書きで記載し、説明の代わりにしてはいけません。

  平易な言葉を使うときも、違いを保ってください。違いを曖昧にしてはいけません。 言い換えには情報の損失が伴います。用語を置き換える前に、その用語がどのような違いを表していたかを考え、置き換え後もその違いが保たれていることを確認してください。特に、混同しやすい2つの概念を区別するために用語が存在する場合は注意が必要です。実際に起きた失敗： あるエージェントが、このルールに従っているにもかかわらず、Roomを「記録」と訳しました。これは動画のような印象を与え（取り込まれるのは映像ではなく状態です）、RoomとLudeoを同一視することになります。その結果、フェーズ3の適用範囲が誤って狭まり、しかもエージェントは同じセッション中に二度も注意を受けていました。正しくは（現行SDKドキュメントのGameplaySessionsに基づく）：Roomは、取り込まれたゲームプレイの一区間を囲むものです。プラットフォームはその区間からLudeoを生成します。その区間からいくつのLudeoが生成されるかをゲームが決めるわけではありません。 注意を促された誤解をかえって招きやすくする単純化は、単純化ではありません。 テスト方法： この SDK を聞いたことがない有能な Unity 開発者が、すべての文を理解し、さらにその内容に異議を唱えられるでしょうか。エンゲージメント中に利用できる主なエラー修正手段は、その異議です。理解できない用語があると、最も必要としているレビューが妨げられます。用語を一つ指摘されたら、その用語だけでなく文体全体を見直してください。

• コードを書く各フェーズの最後には、再コンパイルと実行のゲートが必須です。 .cs を編集するファイル（4、7、9、11、12）では、それぞれ最後にインテグレーターへ、（1）エディターにフォーカスして問題なく再コンパイルすること、（2）ゲームをプレイして引き続き動作することを確認するよう求めます。Unity はフォーカス時に再コンパイルするため、「コンパイル」は一度きりのマイルストーンではなく、フェーズごとに必要です。オーケストレーションされるフェーズ（3、5、6）では、オーケストレーターがこれらのゲートを実行します。コード生成サブエージェント（コンパイルは行いません）に処理を振り分けた後、人間に再コンパイル／プレイのゲートを提示し、失敗した場合はログを添えて修正サブエージェントに再度処理を振り分けます。エージェントは可能な範囲で Editor.log／Player.log を読みますが、どちらの手順も実際に検証することはできません。ログ以外の情報は、インテグレーターの申告に頼ります。両方の確認が取れるまで（または明示的にスキップされるまで）先へ進まないでください。コンパイルと修正のループ、および error CS の表は phase 3 · task 5 に記載されており、このゲートでは繰り返さず、そこを参照します。

• まず Unity のメンタルモデルを把握してください。 フェーズ 1 の前に、上記の「最初にお読みください」のモデルとフェーズ 2 の「Unity ゲームの構造」を理解し、すべての検索や指示をその観点から扱ってください。

• オブジェクトは、既定で一塊のデータではなく属性として追跡してください。 SDK は両方をサポートしますが、Ludeo は属性によるインテグレーションを強く推奨しています。オブジェクトをマッピングして追跡する際（フェーズ 4～5）は、既定で離散した型付き属性（WriteData(name, int/float/double/bool/string/Vector3/Quaternion)、using (obj.EnterObjectScope()) の内部）を記録し、どちらを使うかユーザーに尋ねないでください。blob／byte[] ストレージは、ユーザーが明示的に求めた場合、またはエンティティが実際に不透明な場合に限って使用してください。詳しくは 06-TRACKING-PATTERNS.md を参照してください。不透明な値（列挙型、型コード、コンテンツ ID）には、補助的な <Attr>Name の string ラベルも付与してください。これにより、下流では EnemyType: 3 が EnemyTypeName: "HeavyGunner" と表示されます。数値が引き続き信頼できる唯一の情報源であり、復元時にラベルを読み取ることはありません（06 §1.5）。

• 書き込みと読み取りにはスコープが必要です（CR-002、v4.3.0）。 すべての WriteData／ReadData は、using EnterObjectScope() の内部で実行します（コンポーネントのスコープはその内側にネストします）。指定された ILudeoStateHandler がティックごとの書き込みスコープを管理するため、ゲームプレイコードでは WriteData を呼び出すだけで構いません。一方、復元適用コードでは読み取りスコープを自分で開きます。12-SDK-API-REFERENCE.md と 00-CRITICAL-REQUIREMENTS.md を参照してください。

• SDK のティック処理は SDK 自身が行います。 プラグインは LudeoUnityManager をインスタンス化し、SDK のティックを駆動します。SDK のティックを Update ループに組み込まないでください。ゲームが駆動するのは、属性をサンプリングする周期である独自の UpdateStateObjects() だけです。

• 可能な場合は Ludeo レイヤーを優先し、ゲームファイルの編集は最小限にしてください（これは推奨であり、必須ではありません）。 インテグレーションの正しさが最優先です。ゲームコードへの変更を避けるためだけに、インテグレーションを無理に変えたり、必要なフックを省いたり、ゲームのアーキテクチャに逆らったりしてはいけません。ただし、適切に選択できる場合は、ロジックをゲームの Ludeo インテグレーションフォルダー（[Layer] クラス。unity/REFERENCE-ARCHITECTURE.md）に置き、ゲーム独自のソースコードへの変更は小さく機械的なもの（理想的には単一のファサード呼び出しまたはイベント購読）にとどめてください。ゲームファイルへの変更が少なく、小規模であれば、インテグレーションのレビュー、切り分け、削除が容易になります。これを目指しつつ、両者が相反する場合は常に正しさを優先してください。

• Ludeo の無効化は、主にランタイム上の対応であり、条件付きコンパイルによるものではありません。 パッケージをインストールすると自動的に参照されるため、asmdef の設定は不要です。SDK の使用はすべてインターフェース経由にし、同意がオフの場合や未初期化状態の場合には Dummy*／Disabled* の実装にフォールバックして、ゲームが通常どおりプレイできるようにしてください。スクリプト定義（例：LUDEO_SDK）は任意です。SDK パッケージ自体を含めずにビルドを出荷する必要がある場合に限り使用してください。

• ドキュメントを確認せずに SDK の動作を断言しないでください。 sdk-docs MCP サーバー（下記のMCP の設定を参照）を検索するか、同梱の references/ludeo-integration-docs/ を読んでください。どちらにも記載がない場合は、推測せず、不確かな点を伝えてください。

• ワークフローファイル内のパスは、そのワークフローファイルを基準とした相対パスです。 references/N-*.md にあるワークフローでは、ドキュメントフォルダーにアクセスするパスを ludeo-integration-docs/<file>.md と記述します。

• エージェントが出力を書き込む先は、このスキルではなくゲームの Unity プロジェクトです。 たとえば、ludeo-integration-plan/CODE_MAP.json は Unity プロジェクトのルートに作成されます。

• 新しいセッションの開始を推奨します。 各フェーズで大量のコンテキストが生成されます。フェーズの実行に時間がかかっている場合は、次のフェーズに進む前に新しいエージェントセッションを始めるようユーザーに提案してください。

学び

learnings/ は、このスキルの組織的な記憶です。過去の統合で得られた、サニタイズ済みの修正内容を architecture/、common-mistakes/、engine-quirks/（Unity/C# の癖）、save-systems/ に分類して整理しています。各ファイルには、フロントマター（category、tier、sourceGame、phase、question、sanitized）と、1 件の学びが記載されています。

読み込み — 各フェーズの開始時

このコーパスは統合のたびに増えていきます。各フェーズで全ファイルを読むと、そのフェーズの実作業に必要なコンテキストを消費してしまいます。まずインデックスを読み込んでください。

1. learnings/INDEX.md を最初から最後まで読みます。 各学びは path | tier | phase | hook の形式で 1 行に記載されています。hook は、その学びの前提条件を問う質問（前提条件がない場合はタイトル）です。インデックスの行はポインターであり、学びそのものではありません。インデックスの行だけを根拠に学びを引用したり、適用したりしないでください。
2. phase が現在のフェーズと一致するすべての項目について、tier にかかわらず本文全体を読みます。 フェーズタグは控えめに設定されているため、これが最低限の作業であり、すべてではありません。
3. 他のすべての hook を、このプロジェクトについて把握している内容と照らし合わせて確認します（メニューを経由するか、直接ゲームプレイを開始するか？オブジェクトプールを使っているか？セーブシステムがないか？blob による追跡か、属性による追跡か？）。関連する可能性がある項目は本文を読みます。迷ったら読む方を選んでください。本文を読む手間はわずかですが、学びを誤って読み飛ばすと統合に支障をきたします。
4. フェーズの途中でも、インデックスを再検索します。 新しいトピック（同意／オーバーレイ、復元順序、プールされたスポーン、アクションの出力など）に直面したら、インデックス内を grep で検索し、一致する項目を即興で進める前に読みます。
5. 網羅性を相互確認します。 インデックスの Total: 件数を Glob(pattern: "**/*.md", path: "<skill-base-dir>/learnings") の結果と比較します（learnings ディレクトリから直接 glob を実行してください。Windows では learnings/** のプレフィックスが機能しません。INDEX.md 自体は差し引いてください）。インデックスに記載されていないファイルがあれば、それらも読みます。インデックスが古くなっているため、再生成する（node scripts/generate-learnings-index.mjs）か、不足している行を手動で追加してください。

Tier の意味（厳守）： universal = 前提条件なしに、すべての Unity Ludeo 統合に適用されます。generalizable = 明記された前提条件が満たされる場合にのみ適用されます（question フィールドがその前提条件です。適用前に、このプロジェクトで満たされているか確認してください）。game-specific = 1 つのゲームに固有です。他のゲームには再利用しないでください。

意思決定で学びを引用する前に： 本文全体を読み、前提条件を特定し、具体的な根拠をもとに、このプロジェクトでその前提条件が満たされていることを確認してください（読んだファイル、得られた回答、実行したテストなど）。前提条件を確認できない場合、その学びは適用されません。引用しないでください。「唯一の方法」「X は絶対にしてはならない」などの断定的な結論が universal とタグ付けされている場合は危険信号です。まず generalizable にすべきか確認してください。

記録 — フェーズ終了時ではなく、発見した時点で

学びは追記専用です。 新しいファイルは learnings/{category}/ に追加し、明示的な人間の承認なしに既存のファイルを削除または上書きしないでください。次の場合は、作業を続ける前に学びを書き留めてください。修正に複数回の試行が必要だった、または根本原因が想定と異なっていた場合、SDK／エンジン／環境の挙動がドキュメントの記述と異なっていた場合、人間から訂正を受けた場合、あるいは自明でない前提条件、順序要件、正確な API シグネチャを見つけた場合です。先送りすると、再利用に必要な詳細が失われます。

1. 分類（architecture／common-mistakes／engine-quirks／save-systems）し、階層を判定します（上記の説明を参照）。
2. フロントマターを付けて learnings/{category}/<slug>.md を作成します。

   ---
   category: common-mistakes
   tier: generalizable
   sourceGame: FPSSample      # abstract codename only — see config/learning-policy.json
   phase: 4
   question: "..."            # the precondition to re-check on future integrations (null if universal)
   sanitized: true            # attest you ran the sanitization checklist
   ---
   

3. インデックスに登録します。node scripts/generate-learnings-index.mjs を実行するか、node を実行できない場合は同じ形式で learnings/INDEX.md に行を手動で追加します。Load ステップでは最初にインデックスを読み込むため、インデックスにない学びは後続フェーズから見えません。
4. 保存前のサニタイズは必須です。 学びは将来、別のクライアントとのインテグレーションで参照されます。クライアント固有の情報が残っていると、あるクライアントのコードが他のすべてのクライアントに漏洩します。移転可能なパターンを記録し、クライアントのペイロードは決して記録しないでください。sourceGame は許可リストにある抽象的なコードネームにし、クライアントの名前空間／.asmdef／クラス名は中立的な役割ベースの名前に置き換え、Ludeo SDK と Unity 標準の識別子はそのまま記載します。確認方法： 読者がクライアントを特定できたり、クライアント固有のものをコピー＆ペーストできたりしませんか？できる場合は、サニタイズされていません。これは learnings/ だけでなく、コミットするすべてのファイルに適用されます。ルール全文とチェックリスト：references/learning-sanitization.md — 学びを書く前に必ず読んでください。 scripts/validate-skill.mjs は、構造上の要件（コードネームの許可リスト、インデックスの最新性、クライアント識別子のチェック）を適用します。

参考資料

• references/learning-sanitization.md — クライアントの IP を漏らさずに学びを書く方法（ペイロードではなくパターン）と、保存前チェックリスト。コードネームの許可リストは config/learning-policy.json にあります。
• references/ludeo-integration-docs/ — 主要なインテグレーションガイド（ビルド、ライフサイクル、トラッキング、復元、API リファレンス、調査テンプレート、ゲームパターンのプレイブック）。すべて Unity／C# です。
• references/ludeo-integration-docs/unity/ — Unity 固有の資料：
  • REFERENCE-ARCHITECTURE.md — 推奨されるインテグレーションレイヤー（LudeoController／LudeoFlowSwitch／LudeoGameplaySessionManager／ILudeoStateHandler／LudeoKeys）。
  • UPM-INSTALL-AND-DEFINES.md — インストール方法、スクリプティング定義、ダミー実装パターン。
  • LAUNCH-AND-READINESS.md — 起動モデル（メニュー経由と、起動直後にゲームプレイへ進む方式）、およびメニューで暗黙的に待機していた Activate／同意を置き換える SDK 準備完了ゲート。
  • CONSENT-AND-OVERLAY.md — 双方向の同意ゲートと一時停止／再開（CR-011）。いずれかを組み込む前に §3 を読んでください。
  • READING-UNITY-LOGS.md — コンパイル／実行ゲートのために Editor.log／Player.log を見つけて読む方法。
• references/ludeo-studio-mcp.md — ludeo-mcp の操作ポイント（環境の検索、ベータ版、招待）、デプロイ済みのツール、および読み取りは自由・書き込みは確認後に行うポリシー。

MCP 設定

このスキルで SDK の詳細を確認する際の、最も重要で常に最新の情報源は sdk-docs MCP サーバーです。このサーバーはLudeo SDK のドキュメント（API リファレンス、メソッドシグネチャ、コールバックチェーン、Unity/C# を含む）を検索します。スキルに同梱されており（config/mcp_config.template.json）、インテグレーターのマシン上で動作します。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/ludeo-integration-docs/ を代わりに使用してください。ただし、同梱のコピーは最新の SDK と内容が異なる可能性があるため、必ずその旨を明示してください。

サーバー	ホスト型エンドポイント	目的	代替手段
sdk-docs	https://ludeo-mcps-sdk-docs.ludeo.com/mcp（HTTP、X-User-Name ヘッダー）	Ludeo SDK のドキュメントを検索	同梱の references/ludeo-integration-docs/
ludeo-context	https://mcp-ludeo-context-internal.ludeo.com/mcp（HTTP、ベアラートークン）	社内ナレッジ、QA ワークフロー、リポジトリのコンテキスト	接続せずに進めます。分析の品質が低下する可能性があります
ludeo-mcp	https://mcp.ludeo.com/mcp（HTTP、OAuth サインイン）	エージェントが通常ユーザーに依頼する Studio Lab プラットフォームでの作業 — 環境、ローカル実行を環境に振り分ける Beta Version Name、招待など。対象機能と読み書きポリシー：references/ludeo-studio-mcp.md	Studio Lab でこの手順を実行するようユーザーに依頼します

まずはこちら

references/1-build-game-with-sdk.md を読み、その手順に従ってください。（コードベースのマッピングに進むと、フェーズ 2 で Unity の構造モデルと検索パターン全体を確認できます。）