Claude Codeのエラー調査・デバッグ手法完全ガイド

【結論】claude code エラー調査の解決策 / 実行コマンド

エラー調査では、Claude Code本体の障害と開発中アプリのバグを混同しないことが重要です。

本体は/doctor、/debug、--safe-modeで調べ、アプリは再現テストとログで調べます。

調査専用ブランチを作り、修正前の状態を固定してください。

git switch -c investigate/error
claude --debug-file ./claude-debug.log

具体的な手順・設定方法

1. 期待結果、実際の結果、最小再現コマンド、最初に失敗した時刻をdebug-notes.mdへ記録します。

2. Claude Code本体を疑う場合は/doctorと/statusを実行し、認証・設定・拡張を確認します。

3. アプリを疑う場合は失敗するテストを1件だけ再現し、スタックトレースの最初の自作コード行を特定します。

4. 仮説ごとに観測方法を決め、1回の変更で1要因だけを変えて再実行します。

npm test -- --runInBand 2>&1 | tee test-error.log
# Pythonの場合
pytest -x -vv 2>&1 | tee test-error.log

実践プロンプト / 活用テクニック

最初からコードを書き換えさせず、証拠と反証条件を提示させます。

調査結果を確認してから、最小パッチと回帰テストを別の手順で依頼します。

test-error.logと関連ファイルだけを調査してください。
まだ修正しないでください。
①観測事実 ②根本原因の仮説を確度順に3件 ③各仮説を否定できる確認コマンド ④最小再現手順を示してください。
推測とログで確認できた事実を明確に分けてください。

注意点・よくあるエラーと対処法

• DEBUGログは通信・設定調査用であり、アプリのビジネスロジックを自動的に説明するものではありません。

• 曖昧な「全部直して」は大量変更を生み、原因を隠します。

• 調査中は依存関係の一括更新やフォーマット変更を避けます。

• 修正後は再現テスト、関連テスト、git diffの順で確認し、偶然直った状態を完了としません。