tyunta-prefab-sentinel

Prefab Sentinel 統合仕様書（Services / Skills / 運用設計）

0. このドキュメントの目的

この文書は、Unity/VRChatプロジェクトに対して安全かつ再現可能にPrefab/Scene/Udon設定を編集するためのツール群の全体構想・詳細仕様・相互関係を定義する。

本仕様の主目的は以下。

• 手作業YAML編集で起きる参照破損（Broken PPtr）を防ぐ
• Prefab Variantのoverride不整合を検出・修復する
• Udon/ClientSimログに基づく原因特定と修正を自動化する
• 人間の判断が必要な変更と、機械的に実行可能な変更を明確分離する

---

0.1 セットアップ

前提条件

• Python 3.11 以上
• uv （パッケージマネージャ）
  • インストール: curl -LsSf https://astral.sh/uv/install.sh | sh
  • 詳細は uv 公式インストールガイド を参照

Claude Code Plugin としてのインストール

Claude Code Plugin として導入すると、Claude Code から /prefab-sentinel:guide 等のスキルを直接利用できる。

# マーケットプレイス登録
/plugin marketplace add tyunta/prefab-sentinel

# プラグインインストール
/plugin install prefab-sentinel@tyunta-prefab-sentinel

利用可能なスキル:

スキル	呼び出し	説明
guide	/prefab-sentinel:guide	MCP ツールリファレンス・パッチスキーマ・ブリッジセットアップ
prefab-reference-repair	/prefab-sentinel:prefab-reference-repair	壊れた参照の検出・修復ワークフロー
variant-safe-edit	/prefab-sentinel:variant-safe-edit	Prefab Variant の安全な編集ワークフロー
udon-log-triage	/prefab-sentinel:udon-log-triage	ランタイムログのトリアージワークフロー

ツールの呼び出し: 各スキル内のコマンドは ${CLAUDE_PLUGIN_ROOT}（Plugin インストールディレクトリに展開されるテンプレート変数）を使ってローカルから実行される。ネットワークアクセス不要。

個人コマンドファイルからの移行: ~/.claude/commands/prefab-sentinel.md を手動配置していた場合、Plugin インストール後は冗長になるため削除可能。Plugin 側（/prefab-sentinel:guide）と個人コマンド（/prefab-sentinel）は名前空間が異なるため共存も可能。

Unity Bridge セットアップ: パッチ実適用・ランタイム検証に必要な Unity Bridge のセットアップ手順は /prefab-sentinel:guide スキルに記載。

MCP サーバー（唯一のインターフェース）

Model Context Protocol (MCP) サーバーとして起動し、AI エージェントから Unity アセットの検査・編集ツールを直接呼び出せる。MCP が Prefab Sentinel の唯一の外部インターフェースとなる。

# MCP 依存をインストール（ファイル監視オプション付き）
pip install prefab-sentinel[mcp,watch]

# stdio トランスポートで起動（デフォルト）
prefab-sentinel-mcp

# プロジェクトルートを明示指定
prefab-sentinel-mcp --project-root /path/to/unity/project

# HTTP トランスポート
prefab-sentinel-mcp --transport streamable-http

提供ツール:

ツール	説明
activate_project	プロジェクトスコープ設定 + キャッシュ warm（セッション開始時に呼ぶ）。project_root で Unity プロジェクトルートを明示指定可
get_project_status	セッション状態（キャッシュ件数、スコープ、watcher 動作状況）の表示
get_unity_symbols	アセットのシンボルツリー取得。depth（int|None, default None）で階層深さ制限、detail（"summary"/"fields"/"full", default "full"）で情報量制御、expand_nested=true で Nested Prefab 展開
find_unity_symbol	人間可読パス（例: CharacterBody/MeshRenderer）でオブジェクト検索。include_fields=true でフィールド値付き、show_origin=true で Variant チェーンのオリジン注釈付き
diff_unity_symbols	Variant と Base の差分のみ返す（override プロパティ + オリジン注釈）
find_referencing_assets	GUID/パスの参照元アセット検索
validate_refs	壊れた GUID/fileID 参照のスキャン
inspect_wiring	MonoBehaviour フィールド配線の分析
inspect_variant	Prefab Variant の override チェーン分析
set_property	シンボルパスでコンポーネントのフィールド値を設定（dry-run/confirm ゲート付き）
copy_component_fields	同一型コンポーネント間でシリアライズフィールド値をコピー（cross-asset/same-asset、dry-run/confirm ゲート付き）
set_component_fields	GameObject シンボルパス + コンポーネント型名で複数フィールドを一括設定（dry-run/confirm ゲート付き）
add_component	シンボルパスで指定した GameObject にコンポーネントを追加（dry-run/confirm ゲート付き）
remove_component	シンボルパスで指定したコンポーネントを削除（dry-run/confirm ゲート付き）
list_serialized_fields	C# スクリプトのシリアライズ対象フィールド一覧（パス・クラス名・GUID 指定、include_inherited で基底クラス含む）
validate_field_rename	フィールドリネームの影響分析（派生クラス経由の影響含む、影響アセット一覧、衝突検出）
check_field_coverage	C# フィールドと YAML propertyPath の不一致検出（継承チェーン解決済み、未使用/孤立）
inspect_materials	レンダラーごとのマテリアルスロット表示（override/inherited マーカー、Nested Prefab フォールバック、source_prefab 注釈付き）
inspect_material_asset	.mat ファイルのシェーダー・プロパティ・テクスチャ参照を構造化データで返す（read-only）
set_material_property	.mat ファイルのプロパティをオフライン YAML 編集（dry-run/confirm ゲート付き）
copy_asset	アセットファイルをコピーし m_Name を自動同期、新 .meta を生成（dry-run/confirm ゲート付き）
rename_asset	アセットファイルをリネームし m_Name を自動同期、.meta を追従リネーム（dry-run/confirm ゲート付き）
validate_structure	YAML 内部構造の検証（fileID 重複、Transform 整合性）
inspect_hierarchy	GameObject 階層ツリー表示（深度制限、コンポーネント注釈対応）
validate_runtime	UdonSharp コンパイル + ClientSim 実行検証
patch_apply	パッチ計画の検証・適用（JSON 文字列入力、dry-run/confirm ゲート付き）
revert_overrides	Prefab Variant から特定プロパティの override を YAML レベルで削除（dry-run/confirm ゲート付き）
editor_screenshot	Unity Editor の Scene/Game ビューのスクリーンショット取得（refresh=true で事前に AssetDatabase.Refresh 実行）
editor_select	Hierarchy 内の GameObject を選択（Prefab Stage 対応）
editor_frame	選択オブジェクトを Scene ビューでフレーミング
editor_get_camera	Scene ビューのカメラ状態取得（position, rotation, pivot, size, orthographic）
editor_set_camera	Scene ビューのカメラ設定（Mode A: 絶対座標 / Mode B: pivot 周回。yaw=0 が正面）
editor_list_children	GameObject の子オブジェクト一覧（各エントリに active/tag を含む）
editor_list_materials	ランタイムのレンダラーのマテリアルスロット一覧
editor_list_roots	現在の Scene / Prefab Stage のルートオブジェクト一覧（各エントリに active/tag を含む）