Unity Debug

Unity Debug

Unity のバグを体系的に診断し、修正します。実行経路を追跡して根本原因を特定し、修正と予防策を提案します。

このスキルでできること

1. 症状を収集します（エラーメッセージ、スタックトレース、説明）
2. バグの種類を分類します
3. 関連するコードを読みます
4. カテゴリ別の診断ツリーに従います
5. 説明を添えて修正を提案します
6. 防御的なコードと予防策を追加します

前提条件

• Unity プロジェクトのソースファイルにアクセスできること
• 推奨：正確なエラーメッセージまたはスタックトレース
• Claude Code のツールのみ（Read、Grep、Glob）を使用します。MCP Unity は不要です

クイックスタート

1. ユーザーがバグの説明またはエラーを貼り付けます
2. バグの種類を分類します（カテゴリを参照）
3. 関連ファイルを読みます
4. 診断ツリーに従います
5. 次の形式で診断を出力します：症状 | 原因 | 修正 | 予防

---

判断ツリー

Le bug est...
|
+-- Erreur de compilation (code rouge, pas de Play)
|   +-- COMPILE ERROR -> verifier syntaxe, references, asmdef
|
+-- Exception a l'execution (message en console, peut crasher)
|   +-- NullReferenceException        -> ARBRE NULL REF
|   +-- MissingComponentException     -> ARBRE MISSING COMPONENT
|   +-- MissingReferenceException     -> ARBRE DESTROYED OBJECT
|   +-- IndexOutOfRangeException      -> verifier tailles collections
|   +-- InvalidOperationException     -> verifier etat collection pendant iteration
|   +-- StackOverflowException        -> verifier recursion / boucle d'events
|   +-- OperationCanceledException    -> ARBRE ASYNC/AWAITABLE
|
+-- Comportement incorrect (pas d'erreur visible)
|   +-- LOGIC BUG -> tracer le chemin d'execution
|
+-- Performance (lag, stutter, freeze)
|   +-- Bug de perf specifique -> PERF ISSUE -> chercher allocations, Update lourd, physics
|   +-- Audit systematique     -> utiliser /perf-audit a la place
|
+-- Probleme visuel (rendu, UI, shader)
|   +-- VISUAL GLITCH -> verifier materials, sorting, render pipeline
|
+-- Probleme physique (traverse les murs, jitter)
|   +-- PHYSICS BUG -> verifier Update vs FixedUpdate, layers, scale
|
+-- Probleme async / Awaitable
    +-- ASYNC BUG -> ARBRE ASYNC/AWAITABLE

手順ガイド

1 — 症状を収集する

ユーザーから取得する情報：

• 正確なエラーメッセージ（スタックトレースを含む全文）
• 発生するタイミング（起動時、操作後、ランダム）
• 再現性（常に、ときどき、ビルド時のみ）
• 最近の変更（問題が発生する前に何を変更したか）

スタックトレースがある場合は、次の情報を抽出します：

• ファイルと行番号（at Namespace.Class.Method () in File.cs:line X）
• 呼び出しチェーン（どの処理がどの処理を呼び出しているか）

2 — 関連ファイルを読む

Grep("class NomDuScript", type: "cs")        -> trouver le fichier
Read(fichier identifie)                       -> lire le code complet
Grep("GetComponent|Find|SendMessage", fichier) -> reperer les appels risques
Grep("void Update|void FixedUpdate", fichier)  -> reperer les hot paths

スタックトレースがある場合は、呼び出しチェーンに記載されているすべてのファイルを、最も深い呼び出し元から上位へ順に読みます。

3 — 診断ツリーを適用する

詳細な診断ツリーについては、references/diagnostic-trees.md を参照してください。

4 — 修正を提案する

出力形式

各診断で必ず使用する形式：

## Diagnostic

**Symptome** : [description precise de ce qui se passe]
**Cause** : [explication technique de pourquoi ca arrive]
**Fix** : [code corrige avec diff ou snippet]
**Prevention** : [comment eviter ce bug a l'avenir]

防御的なコード — パターン

// Null check avec log explicite
if (_target == null)
{
    Debug.LogWarning($"[{name}] Target reference is missing.", this);
    return;
}

// TryGetComponent au lieu de GetComponent
if (!TryGetComponent(out Rigidbody rb))
{
    Debug.LogError($"[{name}] Missing Rigidbody.", this);
    return;
}

// Verifier destruction avant callback
private IEnumerator DelayedAction()
{
    yield return new WaitForSeconds(1f);
    if (this == null) yield break;  // objet detruit pendant le wait
    DoAction();
}

// Desubscription propre
private void OnEnable() => _eventChannel.Subscribe(OnEvent);
private void OnDisable() => _eventChannel.Unsubscribe(OnEvent);

---

厳守するルール

必ず行うこと：

• 診断の前に実際のソースコードを読む
• 実行経路全体を追跡する（証拠のない推測をしない）
• 修正に加えて予防策も提案する
• 最も単純な説明から始める（オッカムの剃刀）
• Inspector の参照を確認する（未割り当ての [SerializeField] フィールド）
• Unity のライフサイクルの順序を確認する（Awake -> OnEnable -> Start）
• 症状 | 原因 | 修正 | 予防 の形式で診断を提示する

絶対にしないこと：

• コードを読まずに原因を推測する
• 根本原因を理解せずに修正を提案する
• スタックトレースを無視する（各行が手がかりです）
• 修正として try/catch を提案する（バグを隠すだけで、解決にはなりません）
• バグが Unity Engine にあると決めつける（ほとんどの場合、ユーザーのコードに原因があります）
• 新たな問題（リグレッション）を引き起こす修正を提案する

---

関連スキル

• バグが特定のケースに限らない一般的なパフォーマンスの問題ですか？ /perf-audit（Unity Perf Audit）を使用してください
• 修正に大規模なリファクタリングが必要ですか？ /unity-refactor（Unity Refactor）を使用してください
• テストによる検証が必要ですか？ /unity-test（Unity Test）を使用してください

トラブルシューティング

問題	解決策
スタックトレースがない	ユーザーにコンソールを開いた状態で再現してもらうか、既存の Debug.Log を探してトレースします
バグを再現できない	競合状態を探し、シーンの読み込み順序やフレームレートに依存するかを確認します
サードパーティーパッケージでのエラー	パッケージのコード（Library/PackageCache/）を読み、既知の issue を探し、回避策を提案します
ビルド時のみ発生するバグ（Editor では発生しない）	コードストリッピング（IL2CPP）、シリアライズの違い、誤った位置にある #if UNITY_EDITOR、実行時に変更された SO を確認します
フレームレートに関連する断続的なバグ	FixedUpdate に置くべき、Update 内のフレーム依存コードや、イプシロンを使わない float の比較を探します
パフォーマンスが徐々に低下する	解放されていないイベント、クリアされずに増え続けるリスト、プールを使わずにインスタンス化されたオブジェクトなど、リークを探します

---

よくあるバグの一覧：references/common-bugs.md を参照してください。