Claude Codeのデバッグテクニック完全ガイド：バグ特定から修正まで

Claude Codeでデバッグが変わる

バグの特定と修正は開発者の時間を大きく消費する作業です。Claude Codeはエラーメッセージの解析、スタックトレースの追跡、根本原因の特定まで一貫して対応でき、デバッグ時間を大幅に短縮できます。

基本的な使い方をまだ把握していない方は、先にClaude Code入門ガイドをご覧ください。

テクニック1：エラーメッセージの直接貼り付け

もっとも簡単で効果的な方法は、エラーメッセージをそのまま渡すことです。

> 以下のエラーが出ている。原因を調査して修正して。
>
> TypeError: Cannot read properties of undefined (reading 'map')
>   at UserList (src/components/UserList.tsx:15:23)
>   at renderWithHooks (node_modules/react-dom/...)

Claude Codeは該当ファイルを開き、コードの文脈を理解した上で修正案を提示します。

実際の修正例

// 修正前: users が undefined の場合にクラッシュ
function UserList({ users }: { users: User[] }) {
  return (
    <ul>
      {users.map(user => <li key={user.id}>{user.name}</li>)}
    </ul>
  );
}

// 修正後: オプショナルチェーンとフォールバック
function UserList({ users = [] }: { users?: User[] }) {
  if (users.length === 0) {
    return <p>ユーザーが見つかりません</p>;
  }
  return (
    <ul>
      {users.map(user => <li key={user.id}>{user.name}</li>)}
    </ul>
  );
}

テクニック2：再現手順の共有

複雑なバグには再現手順を伝えると精度が上がります。

> 以下の手順でバグが再現する。原因を特定して修正して。
> 1. /dashboard にアクセス
> 2. フィルターで「2026-03」を選択
> 3. 「エクスポート」ボタンをクリック
> 4. CSVが空になる
>
> 期待動作：フィルター適用済みデータがCSVに含まれる

テクニック3：テストで失敗箇所を特定

テストの失敗結果を渡して原因を特定させるパターンです。

> npm test を実行して、失敗するテストを確認してから、
> すべてのテストが通るように修正して。

Claude Codeはテストを実行し、失敗したテストの内容から問題のあるコードを逆引きして修正します。テストとの連携についてはTDDとClaude Codeの相性で詳しく解説しています。

テクニック4：ログ埋め込みによる調査

> fetchUserData 関数の処理フローにconsole.logを追加して、
> どの段階でデータが欠落しているか調べて。

async function fetchUserData(userId: string): Promise<UserData> {
  console.log("[DEBUG] fetchUserData called with:", userId);

  const response = await api.get(`/users/${userId}`);
  console.log("[DEBUG] API response status:", response.status);
  console.log("[DEBUG] API response data:", JSON.stringify(response.data));

  const transformed = transformUser(response.data);
  console.log("[DEBUG] Transformed data:", JSON.stringify(transformed));

  return transformed;
}

調査後にログを削除するところまで指示すると、コードが汚れません。

> 原因がわかったら修正して、追加したconsole.logはすべて削除して。

テクニック5：型エラーの一括修正

TypeScriptの型エラーが大量に出たときは、一括で対応させましょう。

> npx tsc --noEmit を実行して、型エラーをすべて修正して。
> 各修正では型安全性を維持すること。any型は使わないで。

テクニック6：パフォーマンス問題の調査

動作はするが遅いという問題にも対応できます。

> この関数が遅い。計算量を分析して改善案を出して。

// 修正前: O(n^2) の非効率な実装
function findDuplicates(items: string[]): string[] {
  return items.filter((item, index) =>
    items.indexOf(item) !== index
  );
}

// 修正後: O(n) に改善
function findDuplicates(items: string[]): string[] {
  const seen = new Set<string>();
  const duplicates = new Set<string>();
  for (const item of items) {
    if (seen.has(item)) {
      duplicates.add(item);
    }
    seen.add(item);
  }
  return [...duplicates];
}

パフォーマンス改善の詳細な手法はパフォーマンス最適化ガイドも参考にしてください。

デバッグの効率を上げるCLAUDE.mdの設定

プロジェクトのCLAUDE.mdにデバッグ関連のルールを書いておくと、毎回の指示が減ります。

## デバッグルール
- エラー修正後は必ず関連テストを実行すること
- console.log等のデバッグコードは調査後に必ず削除
- any型での型エラー回避は禁止
- 修正前後のコードを提示すること

まとめ

Claude Codeを使ったデバッグのポイントは、エラーメッセージや再現手順を具体的に伝えることです。曖昧な指示では精度が下がるため、できるだけ多くの情報を提供しましょう。エラーハンドリングの設計自体を改善したい場合はエラーハンドリング設計パターンもあわせてご覧ください。

詳細な機能についてはAnthropic公式ドキュメントを参照してください。