結論：Claude Code は「バグを自動で直す魔法」ではなく「原因の当たりを高速に絞り込むデバッグの相棒」として使うと、調査時間が大きく縮む。エラーを読む・再現する・コードと git 差分を突き合わせる・仮説を検証する、という人間がやっていた往復を一緒に回してくれます。
① エラー/スタックトレースを読ませて原因の当たりをつける：例外メッセージと該当ファイルを渡し、怪しい箇所を3〜5個に絞らせる。
② 再現手順を整理する：いつ・どの入力で・どんな環境で起きるかを言語化し、最小再現コードに落とす。
③ git の最近の変更から犯人を絞る：直近のコミット差分を読ませ、症状と相関する変更を特定する。
対象読者：自分の書いたコードや既存プロジェクトのバグ・障害を日常的に調査するアプリ／バックエンドエンジニア、テックリード、SRE。今日できること：手元の1件のバグで「エラー貼り付け→仮説3つ→最小再現→修正→テスト」を1周通す。
※本記事は2026年6月時点の Claude Code 公式ドキュメントに基づきます。バージョン・仕様は更新されるため、最終挙動は各自の環境で確認してください。AI の原因推定は外れることがあります。必ず実際に再現して確かめ、修正は人がレビューする前提で使ってください。また、認証情報や個人情報を含むログをそのまま貼らないでください。
「このバグ、原因どこだろう」とログを上から下まで何度もスクロールする時間。正直、デバッグで一番しんどいのは「直す」工程よりも「どこが壊れているかを突き止める」工程なんです。私もnullが飛んでくる箇所を半日追いかけて、結局3コミット前の小さな変更が犯人だった、みたいなことを何度もやってきました。
Claude Code が効くのは、まさにこの「当たりをつける」フェーズです。エラーメッセージとコードを渡せば、人間が頭の中でやっていた「この例外なら、たぶんこのあたり」という推論を、根拠つきで言語化してくれる。ただし鵜呑みは禁物で、推測を必ず再現で裏取りする運用にすると、調査がぐっと速くなります。この記事では、その具体的な手順を6ステップ＋落とし穴つきでまとめます。
なぜデバッグに Claude Code を使うのか
デバッグは大きく分けて「①原因を特定する」「②修正する」「③再発を防ぐ」の3工程です。このうち時間を食うのは圧倒的に①で、しかもここで方向を間違えると、関係ないコードを延々と読むことになります。
Claude Code が向いているのは、コードベースを横断して文脈を集めるのが速い点です。スタックトレースに出てくる関数の定義を追い、呼び出し元をたどり、最近の git 差分と突き合わせる──この「探索」を、ターミナルから対話的にやってくれます。Claude Code はプロジェクトのファイルを読み、必要に応じてコマンドを実行できるエージェント型のツールなので、「grep して、関連ファイルを読んで、仮説を出す」までを一気通貫で回せます（公式の概要はClaude Code overviewを参照）。
一方で、Claude Code はあなたのコードが本番でどう動いているかを実際に観測しているわけではありません。だから出てくるのはあくまで「もっともらしい仮説」であって、確定した原因ではない。ここを取り違えると、AI が示した間違った原因を信じて無関係な修正を入れてしまいます。本記事の手順は、すべて「仮説 → 再現で検証」という流れを軸にしています。
ステップ1：エラーメッセージとスタックトレースを読ませて当たりをつける
最初にやるのは、生のエラー出力をそのまま渡して、原因の候補を絞らせることです。スタックトレースは情報が多く、人間が目で追うと見落としが出ます。Claude Code に「どのフレームが自分のコードか」「どの行が起点か」を整理させると速い。
プロンプト例（実際の例外を貼り付ける想定）：
以下の例外が本番で出ています。原因の候補を可能性の高い順に3つ挙げ、
それぞれ「確認すべきファイル/関数」と「再現に必要な条件」を書いてください。
断定はせず、確認方法もセットで示してください。
TypeError: Cannot read properties of undefined (reading 'id')
at formatUser (src/users/format.ts:42:18)
at UserController.show (src/users/controller.ts:88:24)
at processTicksAndRejections (node:internal/process/task_queues:95:5)ポイントは「断定するな・確認方法をセットで」と明記すること。これを書かないと、AI は1つの原因を自信満々に言い切りがちです。候補を複数出させ、それぞれに検証手順を付けさせることで、こちらが裏取りしやすくなります。
スタックトレースを渡すときは、まず自分のソース行（上の例なら format.ts:42 や controller.ts:88）に注目するよう促すと、フレームワーク内部の行に気を取られずに済みます。
ステップ2：再現手順を整理し、最小再現コードに落とす
原因の当たりがついたら、次は「確実に再現させる」工程です。再現できないバグは直したかどうかも確認できません。ここで Claude Code に再現条件を整理させ、最小再現（minimal reproduction）に落とします。
プロンプト例：
このバグについて、再現に必要な前提を箇条書きにしてください。
- どの入力（値・型・サイズ）で起きるか
- どの環境/設定で起きるか（Node バージョン、env、フラグ）
- 直前にどんな操作・状態があると起きるか
そのうえで、依存を最小化した再現用のテスト関数を1つ書いてください。
外部APIやDBは呼ばず、手元で `node` で実行できる形にしてください。最小再現を1つ作っておくと、修正後にそのコードがエラーを出さなくなったかどうかで、直ったかを機械的に判定できます。手順は次の流れで進めると詰まりにくいです。
- 症状を1文で言語化する（「ユーザー詳細APIで user が null のとき 500 になる」）。
- 再現条件を入力・環境・直前操作の3軸で洗い出す。
- 外部依存を取り除いた最小再現コードを書く。
- その最小再現で本当にエラーが出ることを自分の手で確認する。
4番が大事です。AI が書いた再現コードでエラーが出なければ、まだ条件を捉えきれていないサイン。条件を足して、再現する形に持っていきます。
ステップ3：関連コードと git の最近の変更から原因箇所を絞る
「昨日まで動いていたのに今日壊れた」タイプのバグは、直近の変更が犯人であることが多いです。ここで git の差分を Claude Code に読ませると、症状と相関する変更を見つけやすくなります。
まず手元で直近の差分を出します。
git log --oneline -10
git diff HEAD~5..HEAD -- src/users/そのうえでプロンプト：
直近5コミットの差分を貼ります。今回の症状
「user が undefined のとき format.ts:42 で落ちる」と
関係しそうな変更を、コミット単位で指摘してください。
関係なさそうな変更は除外し、理由も書いてください。ここで Claude Code に git blame 的な視点（「この行はいつ・なぜ変わったか」）を持たせると、ガード句が削られた、型が変わった、デフォルト値がなくなった、といった原因を拾いやすくなります。git の操作や差分の扱いは公式のcommon workflowsでも基本パターンが紹介されています。
なお、二分探索的に犯人コミットを探す git bisect と組み合わせると強力です。Claude Code に「このバグを再現するテストを bisect 用に書いて」と頼み、そのテストを git bisect run に渡すと、原因コミットを機械的に特定できます。
ステップ4：仮説を立てて検証する（print／ログ追加・観測）
原因の候補が出たら、それを「証明」する工程です。ここでやってはいけないのは、AI の仮説をそのまま信じて修正してしまうこと。必ず観測して裏を取ります。
典型は print デバッグ（ログ追加）です。仮説が「user が undefined で渡ってくる」なら、その直前で値を出力して確認します。
// format.ts の該当箇所に一時的に追加
function formatUser(user: User | undefined) {
console.error('[debug] formatUser received:', JSON.stringify(user));
if (!user) {
throw new Error('formatUser: user is undefined'); // ガード句で原因を明確化
}
return { id: user.id, name: user.name };
}プロンプト例：
仮説「controller.ts:88 で user を渡す前に null チェックが抜けている」を
検証したいです。どこに何を出力すれば、この仮説の真偽が分かりますか？
最小限のログ追加箇所を3つ提案してください（本番に残さない前提）。検証で仮説が正しいと分かったら、原因を一文で確定させます（「show ハンドラで repository が null を返した場合の分岐が無く、そのまま format に渡していた」）。仮説が外れたら、ステップ1〜3に戻って候補を入れ替えます。この往復をサボらないことが、誤修正を防ぐ唯一の方法です。
ステップ5：修正したらテストで再発を防ぐ
原因が確定し、修正できたら、最後に「同じバグが二度と起きない」ための回帰テストを足します。ステップ2で作った最小再現コードが、ほぼそのままテストケースになります。
プロンプト例：
確定した原因
「repository が null を返したとき controller が format に null を渡していた」
に対する回帰テストを書いてください。
- 修正前なら失敗し、修正後なら通るテストにすること
- 正常系と「null が返るケース」の両方をカバーすること
テストフレームワークは Vitest を使います。「修正前なら失敗するテスト」を先に書いて、それが赤になることを確認してから修正を当てる──いわゆる回帰テスト先行の流れにすると、テストが本当にバグを捉えているか担保できます。テスト設計を Claude Code に任せる場合の進め方は、Claude CodeでQA・テスト自動化を加速する実践ガイドも合わせて読むと観点が増えます。
修正コミットには「原因」「再現条件」「テスト」をメッセージに残しておくと、将来の自分やチームが同じトレースを見たときの調査が速くなります。
ステップ6：チームの調査手順を CLAUDE.md に固定する
個人で速くなったら、次はチームで再現性を持たせます。デバッグの定石（どのログを見るか、再現環境の立ち上げ方、貼ってはいけない情報）を CLAUDE.md に書いておくと、Claude Code が毎回その前提で調査してくれます。
# デバッグの進め方（このリポジトリの約束）
- 例外調査はまず src/ 配下の自前コード行から見る
- 再現は scripts/repro.ts に最小ケースを書いてから直す
- 修正には必ず回帰テストを add する
- ログに含めてはいけないもの: トークン, Cookie, 個人情報, 本番URL
- 本番ログを貼るときは値をマスクしてから渡すCLAUDE.md はプロジェクトメモリとして Claude Code が自動で読み込む仕組みで、置き場所や記法は公式のMemory（CLAUDE.md）に整理されています。設計の考え方はClaude Code 実践テクニック完全ガイドでも触れています。さらに、調査の前処理（ログ収集・整形）を専用のサブエージェントに切り出すと、メインの文脈を汚さずに調べられます（Subagents）。
よくある失敗パターンと対策
最後に、実際にやらかしがちな落とし穴を ❌→⭕ で整理します。
❌ AI の原因推定をそのまま信じて修正する
⭕ 仮説は必ず再現・ログで裏取りしてから直す。Claude Code が出すのは「確定した原因」ではなく「もっともらしい候補」です。検証なしの修正は、別のバグを生むだけになりがちです。
❌ 再現できないまま「直った気」になる
⭕ 直す前に必ず再現させ、修正後にそれが消えることを確認する。再現できないバグは、修正の成否を判定できません。最小再現を1つ作るのが最短ルートです。
❌ 本番ログをそのまま貼って機密情報を渡す
⭕ トークン・Cookie・個人情報・内部URLはマスクしてから渡す。デバッグ用のログには想像以上に秘密情報が混ざっています。貼る前に値を置換するか、再現に必要な最小限だけ抜き出してください。
❌ いきなり広く修正して原因を曖昧にする
⭕ 1コミット＝1原因に絞る。複数箇所を同時に変えると、何が効いたのか分からなくなり、再発時に追えません。git 差分を小さく保つほど、次の調査が楽になります。
まとめ：当たりは AI、確定は再現で
Claude Code でデバッグが速くなるのは、「直す」工程ではなく「どこが壊れているかを絞る」工程です。エラーとスタックトレースを読ませて候補を出し、再現で裏を取り、git 差分で犯人を特定し、テストで再発を止める。この往復を一緒に回すと、半日かかっていた原因調査が現実的に短くなります。
大事なのは、AI の推測を確定情報として扱わないこと。当たりは AI に任せ、確定は必ず自分の手で再現して取る。この一線さえ守れば、デバッグの相棒として十分に頼れます。今日、手元の1件のバグで「エラー貼り付け→仮説3つ→最小再現→修正→回帰テスト」を1周だけ通してみてください。次のバグから、調査の入り方が変わります。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載を7回執筆。Claude Code を使った開発・デバッグの現場知見を発信している。
