unity-yaml-editing

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターを使ってスキルを呼び出そうとしている場合は、いったん停止してください。まずこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend/schema でパラメーターの定義をすでに確認している場合は、そのまま dryRun に進んでかまいません。

トリガー

• REST で対応できない場合の YAML の手動編集
• m_Script GUID または壊れた fileID 参照の修正
• .meta ファイルまたはマージコンフリクトの修正
• REST で対応できない場合の YAML の手動編集、m_Script GUID または壊れた fileID 参照の修正、.meta ファイルまたはマージコンフリクトの修正

YAML 編集 - 安全な手動編集ルール

アドバイザリーモジュールです。REST スキル（および Editor）では対応できない場合に、Unity のシリアライズ済み YAML テキストを直接編集するための運用ガイダンスです。YAML の手動編集は最後の手段であり、近道ではありません。

モード：ドキュメントのみ — 制限対象の REST スキルはありません。どの動作モード（Approval / Auto / Bypass）でも自由に読み込めます。

読み込む場合／読み込まない場合

まず REST を優先してください。 通常のオブジェクト／アセット操作には REST スキルを使用してください。シリアライズを適切に保ってくれます。

• GameObject / コンポーネント → gameobject_*
• Prefab → prefab_*
• ScriptableObject → scriptableobject_*
• Scene → scene_*
• Importer → importer_*
• グラフィックス／レンダリング → graphics_*

REST で対応できない場合に限り、 YAML を手動編集してください。具体的には次のいずれかです。

1. コンパイルエラー — スクリプトのコンパイルに失敗しているため、Editor がコンポーネントをデシリアライズできません。Editor／REST API を利用できず、残された手段は YAML テキストだけです。
2. .meta ファイル — .meta を扱う REST スキルはありません。GUID とインポーターのフィールドはテキストにのみ記録されています。
3. 非公開の ProjectSettings フィールド — 多くの ProjectSettings/*.asset フィールドには、公開 API や REST のインターフェースがありません。
4. マージコンフリクト — REST は逐次実行されるため、.unity／.prefab の 3-way マージを実行できません。

いずれにも当てはまらない場合は、作業を止めて REST を使用してください。便宜上 YAML を手動編集しないでください。

基本概念

• オブジェクトブロック／アンカー：シリアライズされた各オブジェクトは、--- !u!<classID> &<fileID> で始まるブロックです。<classID> は Unity の型 ID（例：1 = GameObject、4 = Transform、114 = MonoBehaviour）です。<fileID> はそのオブジェクトのアンカーで、ファイル内で一意です。
• GUID と fileID：
  • GUID = アセットレベルの識別子。32 文字の 16 進数文字列で、アセットの .meta に保存されます。アセット全体（スクリプト、Prefab、テクスチャなど）を識別します。
  • fileID = ファイル内のサブオブジェクトの識別子（特定のコンポーネント、特定の MonoBehaviour スクリプトクラスなど）。
• シリアライズ済み参照：オブジェクト／アセットをまたぐ参照は {fileID: N, guid: H, type: T} です。同一ファイル内の参照では guid が省略されます（{fileID: N}）。
• m_Script：MonoBehaviour は m_Script: {fileID: 11500000, guid: <scriptGUID>, type: 3} を使ってスクリプトを参照します。fileID: 11500000 は一般的な MonoScript の fileID、guid は .meta に記録された .cs ファイルの GUID、type: 3 は参照先がディスク上のアセットであることを示します。ここで guid／fileID が間違っていると、「missing script / missing component」が発生します。

対応シナリオ

1. 参照／fileID の修復

対象となる状況：スクリプトの名前が変更された、または移動されたため、プレハブ／シーンの m_Script の guid／fileID が解決できなくなった場合、またはコンパイルエラーによりコンポーネントが Missing になり、YAML レベルでその場所を特定、削除、あるいは参照先を変更する必要がある場合（壊れたコンポーネントはエディターでデシリアライズできないため、REST／Editor API は利用できません）。

方法：スクリプトの現在の GUID を .cs.meta から読み取ります。プレハブ／シーン内で問題のある m_Script: {fileID: 11500000, guid: ..., type: 3} を見つけ、guid を正しい値に設定します（fileID: 11500000 と type: 3 はそのままにします）。Missing コンポーネントを削除するには、そのコンポーネントの --- !u!114 &<fileID> ブロック全体と、オーナーの GameObject の m_Component リストにある対応する {component: {fileID: <fileID>}} エントリーを削除します。片方だけを残すとファイルが壊れます。

危険：オブジェクトのブロックを削除しても m_Component の参照を残したままにする（またはその逆）と、GameObject が壊れます。他のオブジェクトから参照されている fileID を変更すると、それらの参照先が失われます。

2. .meta／GUID の安全性

対象となる状況：.meta の GUID が疑似ランダムな GUID に見え、サードパーティとの衝突のリスクがある場合、または REST では公開されていないインポーターのフィールドを編集する必要がある場合。

方法：疑似 GUID の検出と uuid4 による修復手順については、/metacheck を再利用してください。5 つの疑似 GUID 判定ヒューリスティック（連続する 16 進数の並び、交互に増加する並び、文字の繰り返し、文字列 abcdef、長さの誤り）、uuid4 の再生成手順、および ValidationSkills.cs.meta の衝突に関する教訓が記載されています。ここで再度導き出す必要はありません。置き換え用の GUID は python -c "import uuid; print(uuid.uuid4().hex)" で生成し、手作業で作成しないでください。

危険：すべての参照を更新せずに GUID を変更すること。GUID を変更する前に、プロジェクト全体でその GUID を grep し（.asset／.prefab／.unity／.meta）、同じ変更内ですべての参照箇所を更新してください。変更の前後に /metacheck を実行し、GUID の健全性を全面的に監査してください。

3. ProjectSettings のパッチ適用

対象となる状況：REST では公開されていない ProjectSettings/*.asset のフィールド（YAML）が必要な場合。たとえば、特定の物理レイヤー／衝突マトリックスのエントリーや、非表示の QualitySettings の値などです。

方法：最初に Git でバックアップを作成する（または作業ツリーがクリーンであることを確認する）こと。キーで正確なフィールドを特定し、その値だけを変更してから、Unity に再読み込みと再シリアライズを行わせて検証します。変更が取り消されたり、再フォーマットされたりせず、Unity がファイルを書き換えても同じ内容が保たれることを確認してください。

危険：衝突マトリックスや列挙型に基づくフィールドのエンコード方式を推測して編集すると、設定が気付かないうちに壊れる可能性があります。再読み込み時に Unity が値を受け入れることを必ず確認してください。

4. マージコンフリクトの解決支援

対象となる状況：.unity／.prefab に Git のコンフリクトマーカーがあり、解決する必要がある場合。

方法：Unity YAML は、各オブジェクトが独立した --- !u!<classID> &<fileID> ブロックになっているため、行単位でマージできます。ブロックごとに解決します。一方の側だけで変更されたブロックは、その側の内容を採用します。同じブロックが両側で変更されている場合は、競合するフィールドを正しく 3-way マージしてください。解決後は、参照されているすべての fileID／guid に定義ブロックが存在することを確認してください。

危険：一方の側を無条件に採用（--theirs／--ours）すると、もう一方の側で追加されたオブジェクトが失われたり、参照先がない参照が残ったりします。内部の fileID 参照を確認せずに、コンフリクト範囲全体を削除して解決してはいけません。

厳守事項

• 最初にバックアップする：YAML を編集する前に、クリーンな Git ツリーであることを確認するか、コミット／スタッシュして、差分の確認と変更の取り消しができるようにします。
• 参照の修復以外では構造に触れない：値のみを変更し、明示的な参照修復タスクでない限り、anchor／fileID の番号を振り直したり並べ替えたりしないでください。
• 再インポートして検証する：編集後、Unity の再インポート／再読み込みを実行し、新たなエラーがなく、ファイルを往復させても問題がないことを確認します。
• GUID は uuid4 にする。手書きは禁止：python -c "import uuid; print(uuid.uuid4().hex)"。
• 一括編集の前にドライランする：まず grep で影響範囲を調べ、変更を加える前に、影響を受ける参照の数を正確に把握します。
• GUID を変更したら、すべての参照も変更する：同じ変更内ですべての参照先ファイルを更新するまで、GUID の編集は完了していません。

振り分け

• REST スキルで対応できる場合は REST を使用し、手作業で編集しないでください。対象は gameobject_*／prefab_*／scriptableobject_*／scene_*／importer_*／graphics_* です。
• GUID の健全性監査／疑似 GUID の検出／uuid4 への修復 → /metacheck。
• スキルのドキュメント編集後、またはドキュメントとコードの整合性確認 → /skillcheck。