deep-debug

深掘りデバッグ - マルチエージェント調査

ステータス: 本番環境対応 最終更新日: 2026-02-03 依存関係: Chrome MCP ツール（任意）、デバッガーエージェント、コードレビュアーエージェント

---

使用する場面

• 同じところを行き来している - 複数の修正を試したものの、何も解決しない
• ブラウザーと API の相互作用に関するバグ - Network タブやコンソールログを確認する必要がある
• 症状が想定と一致しない - 何か別の問題が潜んでいる
• 複雑な状態管理に関するバグ - React フック、クロージャー、競合状態

コマンド

コマンド	目的
/debug	証拠を収集し、並行調査を行うガイド付きデバッグワークフロー

クイックスタート

/debug [description of the bug]

または、自然な言葉で呼び出します。

• 「このバグで行き詰まっています。詳しく調査してもらえますか？」
• 「このバグは通常のデバッグでは解決できません」
• 「徹底的に調べてほしいです」

---

プロセス

フェーズ 1: 証拠を収集する（仮説を立てる前に）

ブラウザー関連のバグの場合は、Chrome MCP ツールを使用します。

// Get network requests (look for duplicates, failures, timing)
mcp__claude-in-chrome__read_network_requests

// Get console logs (errors, warnings, debug output)
mcp__claude-in-chrome__read_console_messages

// Get page state
mcp__claude-in-chrome__read_page

バックエンドのバグの場合は、以下を収集します。

• エラーログとスタックトレース
• リクエスト／レスポンスのペイロード
• データベースクエリログ
• タイミング情報

フェーズ 2: 並行調査を開始する（3 つのエージェント）

収集した証拠を使って、以下のエージェントを同時に開始します。

エージェント 1: 実行トレーサー（debugger）

Task(subagent_type="debugger", prompt="""
EVIDENCE: [paste network/console evidence]

Trace the execution path that leads to this bug. Find:
1. Where the bug originates
2. What triggers it
3. The exact line/function causing the issue

Focus on TRACING, not guessing.
""")

エージェント 2: パターンアナライザー（code-reviewer）

Task(subagent_type="code-reviewer", prompt="""
EVIDENCE: [paste evidence]

Review the relevant code for common bug patterns:
- React useCallback/useMemo dependency issues
- Stale closures
- Race conditions
- State update ordering
- Missing error handling

Find patterns that EXPLAIN the evidence.
""")

エージェント 3: エントリーポイントマッパー（Explore）

Task(subagent_type="Explore", prompt="""
EVIDENCE: [paste evidence]

Map all entry points that could trigger this behavior:
- All places [function] is called
- All event handlers involved
- All state updates that affect this

Find if something is being called MULTIPLE TIMES or from UNEXPECTED places.
""")

フェーズ 3: 調査結果を相互参照する

エージェントの調査が完了したら、以下を確認します。

シグナル	意味
3 つすべてが根本原因で一致	確信度が高い - 修正する
2 つが一致し、1 つが異なる	相違点を調査する
3 つすべてが異なる	さらなる証拠が必要

フェーズ 4: 修正を検証する

修正を実装した後、同じ証拠を再度収集して確認します。

• Network タブに想定どおりの動作が表示される
• コンソールにエラーがない
• 状態が正しく更新される

---

実例: API 呼び出しの重複バグ

収集した証拠

Network タブに、同じメッセージに対する 2 件の fetch リクエストが表示されました。

並行調査の結果

エージェント	調査結果
debugger	useCallback の依存配列にある state.messages がコールバックの再作成を引き起こす
code-reviewer	同じ調査結果に加え、原因となる React のパターンを説明
Explore	UI レイヤーで二重に呼び出されていないことを確認（原因から除外）

根本原因（合意）

sendMessage の useCallback の依存配列に state.messages が含まれていました。状態が更新されるたびにコールバックが再作成され、React の再レンダリング中に重複した呼び出しが発生していました。

修正

依存配列に含めずに現在の状態にアクセスするため、stateRef を使用します。

const stateRef = useRef(state);
stateRef.current = state;

const sendMessage = useCallback(async (text) => {
  // Use stateRef.current instead of state
  const messages = stateRef.current.messages;
  // ...
}, [/* state.messages removed */]);

---

この方法で検出できる一般的なバグのパターン

React フックの問題

• useCallback の依存配列にある state が再作成を引き起こす
• 依存関係の不足によって古いクロージャーが使われる
• useEffect が複数回実行される

API／ネットワークの問題

• リクエストの重複（Network タブで確認可能）
• リクエスト間の競合状態
• CORS エラー
• タイムアウト処理

状態管理の問題

• 状態の更新が正しくバッチ処理されない
• 楽観的更新がサーバーのレスポンスと競合する
• 信頼できる情報源が複数ある

---

Chrome ツールのクイックリファレンス

ツール	用途
read_network_requests	すべての fetch／XHR 呼び出し、重複、失敗を確認する
read_console_messages	エラー、警告、デバッグログを確認する
read_page	現在の DOM 状態を確認する
javascript_tool	ページのコンテキストでデバッグコードを実行する

---

成功のためのヒント

1. まず証拠を集め、仮説はその後に立てる - 具体的なデータを得るまでは推測しない
2. Network タブは重要です - ほとんどのフロントエンドのバグは、ここに症状が現れる
3. エージェントの並行調査で時間を節約する - 順番に推測する代わりに、3 つの視点を同時に得る
4. 調査結果を相互参照する - 一致していれば確信が持てる
5. 同じ証拠で検証する - バグの発見に使ったものと同じツールで修正を確認する