Claude Codeでスタックトレースを読ませてバグ原因を調べる方法

エラーログをそのままClaude Codeに貼り付けて「直して」と頼むと、表面的な修正で終わったり、別の場所を壊されたりします。スタックトレースは「症状」であって「原因」ではありません。原因にたどり着くには、再現条件・関連コード・仮説検証の手順をAIに整理して渡す必要があります。この記事では、スタックトレースをClaude Codeに読ませてバグ原因を切り分ける手順を5ステップで整理します。

まずclaude doctorで環境問題を切り分ける

エラーがClaude Code自体の起動・通信エラーの場合、コードバグとは無関係です。最初に/doctorまたはclaude doctorで環境を確認します。

ネットワーク・認証・モデルアクセスのエラーが見つかれば、コードのデバッグに進む前にそちらを解決します。アプリ側のエラーであることを確認したらステップ1に進みます。エラーメッセージの逆引きは「Claude Codeのよくあるエラー一覧と原因別の直し方」にまとめてあります。

ステップ1：渡す前にスタックトレースを整理する

スタックトレースをそのまま貼り付ける前に、3点を確認します。

1. 機密情報が含まれていないか: トークン、APIキー、本番URL、個人情報、Authorizationヘッダなど
2. 再現条件が一緒に渡せるか: 入力値、リクエストボディ、実行コマンド、環境
3. 直前の操作が分かっているか: 何のテストを走らせたか、何のコミットの後に出たか

機密情報の扱いは「Claude Codeに秘密情報を渡さないための実践ルール」で詳しく扱っています。トークンやキーは***で伏字化してから貼ります。

ステップ2：再現可能な依頼文を作る

「エラーが出た」だけでは原因究明できません。次のテンプレートで依頼します。

依頼：以下のエラーの原因を特定し、修正方針を提案してください。実装はまだ行わないこと。

## 症状
POST /api/users で 500 エラーが返る

## エラー
TypeError: Cannot read properties of undefined (reading 'id')
    at createUser (src/api/users.ts:42:18)
    at handleRequest (src/server.ts:88:12)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

## 再現手順
1. `npm run dev` でローカルサーバーを起動
2. 次のリクエストを送る:
   curl -X POST http://localhost:3000/api/users \
     -H "Content-Type: application/json" \
     -d '{"name":"taro"}'
3. 上記エラーが返る

## 関連ファイル
@src/api/users.ts
@src/types/user.ts

## 確認したいこと
1. エラーの直接原因（どの値が undefined か）
2. なぜ undefined になったかの仮説（最大3つ）
3. 各仮説の検証方法
4. 最小修正案（実装はしない）

@プレフィックスで関連ファイルをコンテキストに入れることで、AIが該当箇所のコードを直接読めるようになります。ファイル名はスタックトレースに出てくるものを最低限渡します。

ステップ3：Plan Modeで仮説を出させる

修正にいきなり入らず、Plan Modeで原因の仮説を整理させます。

または実行中ならShift+TabでPlan Modeに切り替えます。Plan Modeは読み取り専用ツールしか動かないため、調査と仮説出しに集中させられます。Plan Modeの詳細は「Claude Codeに「計画してから実装」させるプロンプト例」を参照してください。

仮説を依頼する追加プロンプトの例：

スタックトレースを根本原因まで遡って、次のフォーマットで仮説を出してください。

## 仮説1
- 直接原因：（コードのどの行のどの値が undefined か）
- 上流原因：（その値が undefined になった経路）
- 検証方法：（このコマンド／このログ／このテストで確認できる）
- 影響範囲：（他の関数で同じ問題が起きうるか）

## 仮説2
（同じフォーマット）

## 仮説3
（同じフォーマット）

仮説が3つ出れば、人間が読んで「これっぽい」を選びやすくなります。1つの仮説だけだと早合点になりがちです。

ステップ4：失敗するテストを先に書かせる

仮説が決まったら、修正前に失敗するテストを書かせます。これはテスト駆動開発（TDD）でいうRedフェーズと同じ考え方です。

依頼：仮説1（リクエストボディに email が無いケースで createUser が落ちる）を
再現する失敗テストを書いてください。

制約：
- tests/api/users.test.ts に追加する
- 修正コードはまだ書かないこと
- このテストは現状の実装で必ず失敗することを確認できる形にする

完了条件：
- npm test を実行すると、追加したテストだけが新たに失敗する
- 既存テストの失敗数は変わらない

このテストが意図通り失敗することを人間が確認します。失敗の仕方が予想通りなら仮説は正しい可能性が高く、予想と違う失敗が出るなら仮説を見直します。

ステップ5：最小修正と再テスト

仮説が確定したら、最小修正を依頼します。

依頼：仮説1を修正してください。

制約：
- src/api/users.ts の createUser 関数だけを変更する
- 他のファイルは変えない
- 入力バリデーションを追加し、email 必須を保証する
- エラーレスポンスは 400 Bad Request にする

完了条件：
- ステップ4で追加したテストが通る
- 既存の全テストが通る（npm test）
- npx tsc --noEmit がエラーなしで通る

修正後に必ず実行する確認コマンド：

修正の差分は人間が読み、想定外の変更（他ファイルの修正、import追加、依存ライブラリ変更など）が混ざっていないか確認します。

デバッグ依頼でよくある失敗パターン

ログを絞るパイプラインの例

長大なログから関連スタックトレースだけ抽出して渡すには、シェルパイプラインが便利です。

# エラー周辺の前後5行だけ抽出して渡す
grep -B 2 -A 20 "TypeError" app.log | claude -p "このエラーの原因を3仮説で整理して"

claude -pは単発実行モードです。基本コマンドの全体像は「Claude Codeの基本コマンドと日常的に使う操作まとめ」で扱っています。

デバッグ依頼前のチェックリスト

• 機密情報を伏字化したか
• 再現手順が3行以内で書けるか
• 関連ファイルを@で2〜5件指定したか
• Plan Modeで仮説出しに切り替えたか
• 仮説を3つ要求したか
• 失敗するテストを先に書く依頼を入れたか
• 修正のスコープ（変更してよいファイル）を明示したか
• 完了条件にテストコマンドを入れたか

次に読むおすすめ記事：

• 「Claude Codeのよくあるエラー一覧と原因別の直し方」：症状からの逆引きハブ
• 「Claude Codeに秘密情報を渡さないための実践ルール」：ログとスタックトレースに含まれる秘密情報の扱い
• 「Claude Codeでテスト駆動開発をする手順」：Red→Green→Refactorをデバッグに応用する流れ