Claude Code によるデバッグ：上級テクニック

デバッグは Claude Code が真価を発揮する領域です。手動でコードを追跡する代わりに、Claude のコンテキスト理解能力、パターン分析能力、動作推論能力を活用できます。さらに、デバッグ専用に設計された特化型エージェントも利用できます。

このガイドでは、公式のデバッグエージェント、並列調査のための Task ツール、そして「このエラーを直して」を超える上級テクニックを解説します。

公式デバッグツール

debugger エージェント

Claude Code ドキュメントによると、debugger エージェントは体系的な根本原因分析のための特化型サブエージェントです：

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Investigate: TypeError: Cannot read property 'id' of undefined
    at CheckoutForm.handleSubmit (checkout.tsx:45)

    Context: Error occurs when submitting checkout with empty cart.
    Find root cause and suggest fix.
  `
})

debugger エージェントを使用するタイミング：

深い分析が必要なエラー調査
複雑なバグの根本原因分析
複数ファイルにまたがる体系的なトレース
予期しない動作の理解

test-runner エージェント

test-runner エージェントは修正を検証し、リグレッションがないことを確認します：

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Run tests related to checkout functionality.
    Analyze any failures and report coverage gaps.
  `
})

test-runner エージェントを使用するタイミング：

修正実装後
再現テストがパスすることを確認する時
リグレッションカバレッジをチェックする時
テストカバレッジのギャップを分析する時

バグ探索のための Explore エージェント

Explore エージェント（Haiku 4.5 搭載）は迅速なコードベース調査に優れています：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore authentication module (thoroughness: medium).
    Find all places where user session might be null.
  `
})

徹底度レベル：

レベル	時間	ユースケース
`quick`	10-30秒	特定のエラーパターンを見つける
`medium`	30-60秒	関連するコードパスをマッピング
`very thorough`	60-120秒	完全なフロー分析

デバッグにおけるマインドセットの転換

従来のデバッグ

1. エラーを確認
2. エラーメッセージを Google 検索
3. Stack Overflow の解決策をランダムに試す
4. console.log 文を追加
5. 直るまで繰り返し

Claude Code でのデバッグ

1. エラーを確認
2. 並列調査エージェントを起動
3. エージェントに根本原因を追跡させる
4. なぜ起こったかを理解する
5. test-runner で検証しながら適切に修正

違いは：Claude は症状を修正するだけでなく、病気を理解します。

テクニック 1: コンテキスト豊富なエラー報告

エラーをただペーストするだけではありません。Claude に全体像を伝えましょう。

悪いアプローチ

"Fix this error: TypeError: Cannot read property 'id' of undefined"

良いアプローチ

"I'm getting this error when submitting the checkout form:

Error: TypeError: Cannot read property 'id' of undefined
  at CheckoutForm.handleSubmit (checkout.tsx:45)
  at processOrder (orders.ts:123)
  at <anonymous>

What I was doing:
- Logged in as test user
- Added 2 items to cart
- Clicked submit on checkout

What I expected:
- Order to be created
- Redirect to confirmation page

The error started after I merged PR #234 yesterday.
Relevant recent changes: Updated cart state management."

なぜこれが効果的か

Claude は以下のことができるようになります：

スタックをトレースして原因を特定
最近の変更を容疑者として検討
期待される動作を理解
シナリオを頭の中で再現

テクニック 2: Task ツールによる並列調査

公式 Claude Code ドキュメントより、複雑なバグにはマルチエージェント分析を使用します：

// Launch 5 parallel investigation agents
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Search for session/cookie handling changes this week (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Analyze authentication middleware patterns (thoroughness: medium)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Check for race conditions in auth state (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Review error logs for auth-related errors (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find timeout/expiry configuration changes (thoroughness: quick)"
})

時間比較：

逐次調査：5 × 30秒 = 150秒
並列調査：max(30秒) = 30秒
5倍高速

各エージェントは1つの仮説に集中します。最初に強い証拠を見つけたエージェントが調査を導きます。

テクニック 3: debugger と test-runner のワークフロー

debugger と test-runner エージェントを組み合わせて包括的なデバッグを行います：

フェーズ 1 - 調査（debugger エージェント）：
→ エラーとスタックトレースを分析
→ 根本原因を特定
→ 修正を提案

フェーズ 2 - 検証（test-runner エージェント）：
→ 既存のテストを実行
→ 修正が他の機能を壊さないことを確認
→ 追加のテストカバレッジを提案

フェーズ 3 - リグレッション防止：
→ 再現テストを作成
→ 修正なしでテストが失敗することを確認
→ 修正ありでテストがパスすることを確認

実装：

// Phase 1: debugger investigates
Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Investigate checkout failure.
    Error: TypeError at checkout.tsx:45
    Find root cause and propose fix.
  `
})

// Phase 2: test-runner verifies (after fix)
Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Run all checkout-related tests.
    Report any failures and coverage analysis.
  `
})

テクニック 4: 動作分析

何かがおかしいとわかっているが、特定できない場合。

"Something's wrong with the search feature. Results seem off.

Behavior I'm seeing:
- Search for 'javascript' returns Python articles
- Exact title matches don't appear first
- Results change on page refresh (shouldn't happen)

Help me understand:
1. What search algorithm are we using?
2. Where is the ranking logic?
3. What could cause non-deterministic results?
4. How can we add debugging to trace a query?"

Claude は以下を行います：

検索パイプラインをマッピング
各ステージで潜在的な問題を特定
計測ポイントを提案
デバッグ計画の作成を支援

テクニック 5: Git 統合によるリグレッション探索

動いていたものが突然動かなくなった場合：

"The export feature broke. It was working on Friday.

git log shows these changes since Friday:
- abc123: Updated PDF library
- def456: Refactored file service
- ghi789: Added new export format

Help me:
1. Identify which commit most likely caused the regression
2. Explain what each change does
3. Suggest how to verify the culprit
4. Provide a fix if you can identify the issue"

並列分析アプローチ：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Analyze commit abc123 impact on export feature (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Analyze commit def456 impact on export feature (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Analyze commit ghi789 impact on export feature (thoroughness: quick)"
})

テクニック 6: エラーパターン分析

繰り返し発生する、または関連するエラーの場合：

"We're seeing multiple related errors in production:

1. TypeError: Cannot read 'user' of null (dashboard.tsx)
2. TypeError: Cannot read 'profile' of null (settings.tsx)
3. TypeError: Cannot read 'preferences' of null (notifications.tsx)

All involve user data. What's the common cause?
Why might user be null in these places?"

Claude は以下を行います：

共通パターン（ユーザーデータアクセス）を特定
ユーザーデータフローをトレース
null の発生源を特定
体系的な修正を提案

テクニック 7: パフォーマンスデバッグ

処理が遅い場合、並列プロファイリングを使用します：

// Launch parallel performance investigation
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find N+1 query patterns in dashboard data fetching (thoroughness: medium)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Identify waterfall request patterns in API calls (thoroughness: medium)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find unnecessary re-renders in React components (thoroughness: quick)"
})

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Check for missing database indexes on slow queries (thoroughness: quick)"
})

テクニック 8: 状態デバッグ

複雑な状態管理の問題の場合：

"The shopping cart state is getting corrupted.

Symptoms:
- Items appear/disappear randomly
- Quantities reset to 1
- Total doesn't match items

We use Redux Toolkit. Cart slice is in store/cart.ts.

I suspect a race condition but can't reproduce it consistently.
Help me trace where state mutations might be happening incorrectly."

Claude は以下を行います：

カートリデューサーを分析
潜在的なミューテーション問題を発見
非同期アクションでのレースコンディションを特定
状態デバッグツールを提案

公式ツールを使用したデバッグワークフロー

ステップ 1: コンテキスト収集と調査開始

// Launch parallel investigation
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore error context (thoroughness: medium).
    Find all files related to: [error location]
    Map data flow and dependencies.
  `
})

ステップ 2: debugger エージェントによる深い分析

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Context from exploration: [results]
    Error: [full stack trace]

    Perform root cause analysis:
    1. Trace execution path
    2. Identify failure point
    3. Determine fix
  `
})

ステップ 3: test-runner エージェントによる検証

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    After fix applied to [files]:
    1. Run related tests
    2. Check for regressions
    3. Report coverage
  `
})

ステップ 4: リグレッション防止

原因を特定した後：
- なぜ起こったかを理解する
- 症状だけでなく根本原因を修正する
- リグレッション防止のためのテストを追加する
- 他の場所で類似の問題がないかチェックする

一般的なデバッグパターン

Null 参照パターン

Error: Cannot read property 'X' of undefined

問うべき質問：
- X はどこから来るべきか？
- どのような条件で undefined になるか？
- レースコンディションはないか？
- 初期化が欠けていないか？

非同期タイミングパターン

症状：断続的な失敗、時々動作する

問うべき質問：
- レースコンディションはないか？
- Promise は正しく処理されているか？
- await が欠けていないか？
- タイミングに関する仮定はないか？

状態ミューテーションパターン

症状：UI が更新されない、古いデータ

問うべき質問：
- 状態が直接変更されていないか？
- イミュータビリティのルールは守られているか？
- useEffect の依存関係は正しいか？
- メモ化は正しく動作しているか？

インテグレーションパターン

症状：ローカルでは動作、本番で失敗

問うべき質問：
- 環境変数は正しいか？
- URL/エンドポイントは正しいか？
- ネットワーク/CORS の問題はないか？
- タイムアウトの違いはないか？

デバッグのためのモデル選択

Claude Code CHANGELOGより：

タスク	推奨モデル	理由
素早いファイル検索	Haiku 4.5	高速、低コスト
パターンマッチング	Haiku 4.5	高速、低コスト
根本原因分析	Sonnet 4.5	バランスの取れた推論
複雑なデバッグ	Sonnet 4.5	Extended Thinking サポート
重大なバグ修正	Opus 4.5	最高の知能

素早いモデル切り替え（v2.0.65以降）：プロンプト入力中に Option+P（macOS）または Alt+P（Windows/Linux）を押します。

実践例：バグ調査

ユーザー：「本番エラー：'Payment failed' だが、お金は引き落とされた。」

並列調査（5つの Explore エージェント）：
→ 決済ログでエラーパターンを検索
→ 決済サービスのエラーハンドリングを分析
→ Stripe webhook ハンドラーを確認
→ 最近の決済変更をレビュー
→ エラートラッキングで類似の問題を発見

結果：
- エージェント 3 が発見：Webhook ハンドラーがタイムアウト時にリトライしない
- エージェント 4 が確認：最近の変更で新しいタイムアウトロジックが追加された
- エージェント 1 が表示：パターンは1月5日のデプロイ後に開始

約1分で根本原因を特定 vs 逐次では10分以上。

はじめ方

今日：

次のバグで debugger エージェントを試す
調査に並列 Explore エージェントを使用する
test-runner エージェントで修正を検証する

今週：

デバッグプロンプトのテンプレートを作成する
複雑なバグに並列調査を使用する
すべての修正に再現テストを作成する

今月：

よくある問題に対するデバッグパターンを構築する
debugger + test-runner ワークフローを統合する
パターンをチームと共有する

目標は単にバグを早く直すことではありません。各デバッグセッションを通じてコードベースをより深く理解することです。

出典: Claude Code Documentation, Claude Code GitHub, CHANGELOG