debug-workflow

name	debug-workflow
description	バグの原因を体系的に特定する。推測修正を防ぐため、複数観点 (データ / 状態 / 依存 / 境界変換 / 既存成功パターン / 直近変更 / 未読領域) で仮説を網羅し、実観察 (ログ) で 検証してから修正する。 Use When — テスト失敗・実装が意図通りに動かない・原因不明のバグ・「デバッグして」 「なぜ動かないか調べて」「期待した動きにならない」と言われた時

Debug Workflow (複数観点並列版)

体系的にバグの原因を特定し修正する。推測で修正せず、証拠に基づいて行動する。仮説の生成は単一視点ではなく 複数観点のサブエージェントを並列起動 して網羅的に行い、ログ検証ゲートを通してから修正に進む。

中核ルール (絶対に守る)

1. Step 4 のログ検証は Step 5 への必須ゲート。スキップ禁止。
2. サブエージェント出力受領後の最初の Edit/Write は「ログ仕込み」のみ許可。修正コードの Edit は Step 5 セルフチェック 3 項目通過後のみ。
3. サブエージェントは仮説生成のみ、修正コードは書かない。サブエージェントが「修正案」を出してきても、メインは Step 4/5 を必ず通す。
4. サブエージェントが Critical を返した事実は Step 5 セルフチェックの「Yes 根拠」として使えない。Critical は「Step 4 で検証する最有力候補」を意味するに過ぎず、観察結果ではない。

---

Step 1: 症状の正確な把握

修正に飛びつく前に、問題を正確に理解する。

• エラーメッセージ・スタックトレースを全文確認
• 期待される動作と実際の動作の差分を明確化
• 再現条件を特定 (常に発生? 特定条件のみ?)

【記録テンプレート】
期待: [期待される動作]
実際: [実際の動作]
エラー: [エラーメッセージ全文]
再現: [再現手順・条件]
関連ファイル: [ユーザー提示 + 周辺で関係しそうなパス]
既知の試行: [試したこと・棄却済み仮説があれば]
尊重すべき制約: [プロジェクト規約・既存アーキテクチャ・触らない方針]

これら 3 ブロック (症状 / 既知の試行 / 制約) は Step 2 でサブエージェントに渡す必須コンテキスト。

---

Step 2: 並列サブエージェントによる仮説生成

仮説の生成は単一視点で行わない。agent/ 配下の 7 観点サブエージェントを 1 メッセージ内で並列起動 して網羅的に仮説を集める。メインはどのサブエージェントを呼ぶか選ばない (毎回全並列、code-reviewer と同じ契約)。

Bundled agents カタログ (全 7 体)

• agent/data-input-hypothesis.md — 入力値・マスターデータ・初期化順序
• agent/state-lifecycle-hypothesis.md — オブジェクト寿命・タイミング・並行性
• agent/dependency-event-hypothesis.md — 他システム連携・イベント順序・通信境界
• agent/boundary-conversion-hypothesis.md — 外部入力 → 内部ドメイン型の変換境界
• agent/working-precedent-hypothesis.md — 同種入力を扱う既存成功経路との差分
• agent/recent-change-hypothesis.md — 直近 git 変更との関連
• agent/unread-evidence-hypothesis.md — 未読領域 (prefab YAML / 設定 / 外部 docs / git 履歴)

並列起動の物理形

1 メッセージ内で 7 個の Agent 呼び出しを並列実行する。順次呼び出しは禁止。

// 1 メッセージ内で 7 体を並列発火
Agent({
  description: "3〜5語の説明",
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `まず以下の 2 ファイルを Read で読み、共通ルール → 個別テンプレートの順に従ってください。

共通ルール: /絶対パス/.claude/skills/debug-workflow/references/subagent-common-rules.md
個別テンプレート: /絶対パス/.claude/skills/debug-workflow/agent/{name}.md
出力フォーマット: /絶対パス/.claude/skills/debug-workflow/references/hypothesis-output-format.md

---

## 症状

${症状ブロック (期待 / 実際 / エラー / 再現 / 関連ファイル)}

## 既知の試行

${試したこと・棄却済み仮説}

## 尊重すべき制約

${プロジェクト規約・触らない方針}`
})

各サブエージェントは 早期終了しない。自分の観点が一見スコープ外でも最低 1 件の仮説 (Info でよい) を必ず返す。

---

Step 3: 仮説集約と絞り込み

7 体のサブエージェント全返却を集めて以下を行う。手動でやる代わりに scripts/aggregate-hypotheses.py を使って機械的に処理してよい (Available scripts 参照)。

1. 重複検出 (正規化キーでグループ化)
   • キー: 対象ファイル + 因果動詞 + 期待/実際
   • 同一クラスタは 1 件に統合し、Evidence と Recommended log placement を union
2. 確度ブースト
   • 異なる観点 ≥ 2 が同一クラスタを支持 → 深刻度 1 段アップ (Info→Warning, Warning→Critical)
3. ソート
   • (深刻度, 観点支持数) 降順
4. 絞り込み
   • 上位 1〜2 個を verify_targets として Step 4 検証対象に確定
   • 残りは fallback として折りたたみ表示。Info 仮説も削除せず必ず控えに残す (Step 4 が空振った時の次候補)
5. 強制文言の出力
   • 集約結果の末尾に必ず以下を機械的に出力する:

次のアクション: Step 4 ログ Edit (修正 Edit ではない)

これは並列化で「仮説が多いから 1 個試そう」となる事故への物理的ストッパー。

Available scripts

• scripts/aggregate-hypotheses.py — Step 3 集約を機械的に実行する Python スクリプト。7 体のサブエージェント出力 (markdown) を 1 つのテキストとして stdin に流すと、verify_targets / fallback / 強制文言を出力する。LLM で集約すると揺らぐ場合の決定的な代替手段。使用例: cat all_subagent_outputs.md | python3 scripts/aggregate-hypotheses.py

---

Step 4: ログによる仮説検証 (必須ゲート・スキップ禁止)

このステップは Step 5 への必須ゲート。スキップして修正コードに進むことを禁止する。

絞り込んだ verify_targets 仮説 (1〜2 個) に対して、各仮説の Recommended log placement をコードに 実際に Edit/Write で仕込む。

// サーバー側
Debug.Log($"[DEBUG] {変数名}: {値}");

// クライアント側 (UniRx 等の非同期フローの場合)
Debug.Log($"[DEBUG] {メソッド名} called at frame {Time.frameCount}, value={値}");

ログ配置の指針 (サブエージェントの Recommended log placement を優先、足りない時のみ追加):

• 問題のメソッドの入口と出口
• 条件分岐の直前 (判定に使う値を出力)
• データ変換の前後

Step 4 完了条件 (すべて満たすまで Step 5 へ進めない)

1. ログコードを Edit/Write で実際に仕込み、変更箇所をユーザーに提示した
2. ユーザーから観察結果 (ログ出力 / 動作変化) を受け取った
3. 受け取った観察結果が verify_targets 仮説の Falsification 欄と照合され、支持 / 棄却の判定が明示された

往復コストを理由にスキップしてはならない。ユーザー操作が必要なら ログを仕込んだ状態で動作確認を依頼して待つ。

検証結果が「棄却」だった場合は fallback リストの次仮説を verify_targets に格上げして Step 4 を再実行する。

---

Step 5: 検証と修正

Step 5 着手前セルフチェック (修正コードを書く前に必ず実行)

以下 3 項目すべてに Yes と答えられない限り、Edit/Write による修正コードを書いてはならない。1 つでも No なら Step 4 へ戻る。

• ログを仕込んで提示したか? (推測ではなく実コードを置いたか)
• ユーザーから実観察結果を受け取ったか? (ログ出力 / 動作変化 / スクリーンショット等)
• その観察結果と Step 3 で絞った仮説は一致したか? (一致しないなら Step 2 に戻る)

サブエージェントが Critical を返した事実は「Yes 根拠」として使わない。サブエージェントの出力は推測の高度化であって観察ではない。

「最有力仮説だから試す価値がある」「往復コストが高いので先に修正してしまう」「ユーザーを待たせたくない」「複数の観点が同じ仮説を支持しているから確実」といった自己正当化はすべてアンチパターン「推測修正」のサインであり、却下する。

修正の実施

ログ結果から原因を特定し修正する。

• 仮説が正しければ → 最小限の修正を実施
• 仮説が外れたら → fallback リストから次仮説を選び Step 4 へ。または Step 2 へ戻り新たな仮説をサブエージェント再起動で追加
• 修正後は必ずテストを再実行して確認

---

Step 6: クリーンアップ

• デバッグ用ログをすべて削除
• 修正内容がプロジェクト全体の一貫性を保っているか確認

---

Gotchas (このスキル固有の罠)

• 再帰起動禁止: サブエージェント内から本スキル (debug-workflow) を再起動させない。並列発火対象から自分自身を除外する。サブエージェントは仮説を返すだけで、別スキル起動の権限を持たない
• コスト適用判定: 7 体並列は context cost が大きい。コンパイルエラー / 型エラー / 単純な typo など静的に自明なバグでは使わない (より軽量な手段で十分)。判断: 「単一視点でも分かる」と感じたバグでは並列起動はオーバーキル
• メインが集約段でサブエージェントの「修正案」を採用する誘惑: サブエージェントは仕様上修正コードを書かないが、Recommended log placement を「これを入れれば直る」と誤読しないこと。あくまで 検証用ログ
• Step 3 集約結果が長文化したらコンテキスト圧迫: 7 体 × 3-5 仮説 = 最大 35 件。集約段で重複統合 + fallback 折りたたみを徹底する。verify_targets 1-2 個に絞った後、残りは見出しのみ表示
• 多観点支持 ≠ 真実: 「複数観点が同じ仮説を支持しているから確実」と思った瞬間が罠 (会話前半の train ride バグで実証済)。共通の盲点が原因で多観点が誤合致する場合がある。Step 4 ログでの実観察が唯一の決着手段

アンチパターン

• 推測修正: ログで確認せずに「たぶんここが原因」で修正する → 二次障害の温床
• 一度に大量変更: 複数箇所を同時修正すると原因特定が困難になる
• ログ残し: デバッグログを残したままコミットする
• ゲートスキップの自己正当化: 「往復コストが高い」「最有力仮説なので試す価値がある」「サブエージェントが Critical と言った」「確証バイアスではない」「ユーザーを待たせたくない」「複数観点で支持されている」等の理由で Step 4 を省略する。これらの思考が浮かんだ瞬間が Step 4 ログ仕込みの起動条件
• サブエージェント選別: 「この観点は今回は関係なさそうだから呼ばない」と判断する → 全 7 体を毎回並列起動する。サブエージェント側が観点で再解釈して仮説を返す
• 修正案の先食い: サブエージェントが提案 (本来禁止) してきた fix を Step 4 経由なしに採用する → サブエージェントの fix 提案は 削除して無視、自分の Step 4-5 を通す