AIでのデバッグ: Claude Code で根本原因を見つける (2026)

Jasmine、毎日 Claude Code を使ってデバッグしている開発者。

AIでのデバッグとは?

AIでのデバッグとは、AIエージェント（ここでは Claude Code）を使って、コードを読み、ログを読み、実行経路をたどりながらバグの根本原因を調査することであり、修正用のスニペットをただ提案させることではありません。違いは、あなたが割り当てる役割にあります。「このバグを直して」と頼むのではなく、AIに調査役の仕事を渡すのです。「なぜ壊れたのかを突き止めて」と。

ほとんどのガイドが省略する最も重要な点は、症状と根本原因の切り分けです。スタックトレースが示すのはプログラムがどこで崩れたかだけであり、例外を投げる場所は通常バグのある場所ではありません。ビュー層で発生する NullPointerException が、フィルタ条件の欠落によって null を返したリポジトリのクエリまで、3ファイル離れた場所へたどり着くこともあります。最後のエラー行だけを貼り付けて修正を求めれば、AIは「症状にパッチを当て」ます。クラッシュしたまさにその場所にnullチェックを追加するのです。エラーは画面から消えますが、不正なデータは水面下で流れ続け、別のどこかでまた爆発します。

正しく行うAIデバッグは、症状から発生源へと逆向きにたどり、仮説を立て、コード内の証拠と照らし合わせて検証し、それからようやく修正を提案させます。これは推測ではなく調査です。このアプローチが全体像のどこに位置するのかを知るには、AIを使ったvibe codingのワークフローをお読みください。

なぜ Claude Code は根本原因を見つけるのが得意なのか?

根本原因分析における Claude Code の強みは、チャットボックスに貼り付けられたスニペットだけでなく、コードベース全体を扱えることから来ています。Anthropic の Claude Code ドキュメント（2026年8月アクセス）によれば、このエージェントは自分でファイルを読み、リポジトリを検索し、コマンドを実行できます。つまり、狭い一枚のビューに縛られることなく、コントローラからサービス、リポジトリへと複数のファイルをまたいでバグをたどれるということです。

具体的には、原因を追う際に Claude Code が得意とすることが3つあります。

• 層をまたいで実行経路をたどる。 スタックトレースを渡せば、そのトレースに含まれるファイルを自分で開き、関数がどう呼び合っているかを読み、データがたどった経路を再構成します。本来ならタブを行き来しながら手作業でやることです。
• 微妙で多層的なバグを捕まえる。 うっかり書き換えられた変数、誤った順序で走る非同期条件、DBスキーマとコード内モデルの不一致など、Claude Code は両端を読むため、それらを突き合わせられます。
• 隔離されたコンテキストで調査する。 バグ探しを別のセッションや subagent に任せれば、メインの会話が何十行ものログに埋もれずに済みます。

さらに、Claude Code はコマンドを実行できるため、調査のループを自分で閉じられます。変更を試し、再現テストを再実行し、結果を読み、新たな証拠に基づいて仮説を調整するのです。これはテキストで返すだけのアシスタントとの大きな違いで、推測するだけでなく検証できます。

公平を期して言えば、「コードベース全体を読める」ことは「常に正しい」ことを意味しません。特にコンテキストが薄い、あるいはトレースが途中で切れている場合、Claude Code はもっともらしいが誤った原因を提案することがあります。本当の力は、コードで仮説を証明させて初めて発揮されます。以下のセクションでその方法を示します。

AIでデバッグする前に準備すること

AIデバッグのセッションが失敗するのは、たいていAIが「ダメ」だからではなく、入力が薄かったからです。セッションを開く前に、このチェックリストに目を通してください。

• バグを再現できること。 バグを確実に出現させるコマンド、テスト、あるいは特定のクリック手順が必要です。「たまにしか起きない」バグははるかに難しいので、まず一貫して再現させる方法を見つけましょう。
• 完全なスタックトレースまたは完全なログがあること。 最後の1行だけでなく、呼び出しフレームを含むトレース全体です。これはAIが逆向きにたどるための地図です。
• テスト／コマンドの実行を許可すること。 Claude Code にテストスイートや再現コマンドを実行させ、推測ではなく自分で検証できるようにします。まだ設定していない場合は、Claude Code のインストールガイドをご覧ください。
• 期待される挙動を把握していること。 「Xを返すべきなのにYを返している」と書き出しておきましょう。正しい基準点がなければ、比較する対象がありません。

Claude Code で根本原因を見つける6ステップ

これは私が何度も繰り返しているワークフローです。「AIにバグを直させる」との違いは、コードに触れる前に置く仮説検証のステップにあります。

ステップ1: バグを再現して完全なスタックトレースを取得する

バグを引き起こすコマンドを実行し、最後の1行だけでなくトレース全体をコピーします。フレームが多いほど、AIの手がかりも増えます。バグがUI経由でしか出ない場合は、小さな再現スクリプトを書いてターミナルで確実に発生させましょう。その方が速く、修正後に再実行するための安定した基点をAIに与えられます。バグを引き起こす入力値（ペイロード、パラメータ）も含めておけば、AIがデータを推測せずに済みます。

npm test -- users.spec.ts
# or run the reproduction script directly
node scripts/reproduce-bug.js

ステップ2: 完全なコンテキストを読み込ませる

完全なスタックトレースを Claude Code に貼り付け、関連ファイルを指し示します。どのファイルかをAIに推測させないでください。道を示すのです。期待される挙動と実際の挙動の説明（「合計は正のはずなのに負になっている」）を含めれば、AIに基準点ができます。バグがデータに関わるなら、サンプルレコードやスキーマを貼り付けましょう。AIがコードと実データを突き合わせられると、探索範囲がずっと速く絞られます。

Here is the full stack trace (pasted verbatim). The bug shows up when
calling POST /orders. Relevant files: src/orders/order.service.ts,
src/orders/order.repository.ts, src/payments/payment.client.ts.
Don't change anything yet - read first.

ステップ3: 「まず調査し、編集しない」

これが決定的な指示です。AIを「パッチ」モードから「調査」モードへ切り替えさせます。何か変更を提案する前に、コードを読み、フローを説明し、疑わしい箇所を指摘させるのです。このステップがないと、AIは最初に見つけた怪しい行を直しがちです。可能性の高い順に2〜3個の仮説を、それぞれ証拠となるコード行を添えて挙げるよう頼みましょう。そうすれば、AIが実際のコードに根拠を持たず憶測しているときに、すぐ露見します。

ステップ4: 根本原因の仮説を検証する

AIが原因を示しても、すぐに信じてはいけません。なぜなぜ分析（5 Whys）（岩盤に当たるまで繰り返し「なぜ」と問う）を使い、各ステップについてコード内の具体的な証拠を求めます。手強いリグレッションには、バグを混入させたコミットを特定するために git bisect を仕込むようAIに頼みましょう。

Why is `total` negative? Show me the exact line that assigns that value,
and where the input value comes from. Prove it with code, don't speculate.

ステップ5: 再現テストとともに最小限で安全な修正を適用する

根本原因が明確になり証拠に裏付けられたら、実際の原因に対処する最小限の修正を求めます。抱き合わせのリファクタリングも、「ついでに」の掃除もなしです。修正が小さいほど差分はレビューしやすく、新しいバグを生む可能性も減ります。同時に、バグを再現するテストを書きましょう。それは修正前に失敗し、修正後に成功する必要があります。本当の根本原因を突き止めたのであって、たまたま運が良かっただけではない、という客観的な証明です。さらに一歩進めてテストに修正を主導させたい場合は、AIを使ったTDDのガイドをご覧ください。

ステップ6: 失敗パターンを記録する

修正のあとは、プロジェクトの CLAUDE.md ファイルにそのパターンを書き留めます。たとえば「tenantId が欠けているとリポジトリは null を返す。常にテナントフィルタを確認すること」のように。次回、AIはそのメモを読み、同じ罠を避けます。こうして、あらゆるデバッグのセッションをコードベースの永続的な資産へと変えていくのです。

実際のデバッグセッション: スタックトレースから根本原因まで

これは最近の実例で、「どこで失敗したか」が「バグのある場所」ではないことを示しています。POST /orders APIが、ときどき負の合計を返していました。スタックトレースはクラッシュせず、支払い層で警告をログに出しただけでした。amount の値が不正だ、と。最初の衝動は、その支払いクライアントにそのまま if (amount < 0) amount = 0 を追加することです。それこそまさに症状へのパッチです。

パッチを当てる代わりに、私は完全なログを貼り付け、調査を徹底させました。Claude Code は支払いクライアントから注文サービス、注文リポジトリへと逆向きに読み進め、こう指摘しました。期限切れの割引コードがリポジトリでフィルタされておらず、古い割引行が符号を反転したままカートに追加されていた、と。根本原因はリポジトリ層にあり、警告がログされた場所から2層離れていました。最小の修正は、割引クエリに expired = false のフィルタを追加することであって、支払いクライアントで値をクランプすることではありませんでした。

正直に一つ補足すると、最初の実行で Claude Code は危うく誤った方向へ進みかけました。サービス層に原因（数値の丸め）があると提案し、それが非常にもっともらしく聞こえたのです。実データでそれを証明させて（ステップ4）はじめて仮説が崩れ、ようやくリポジトリまでたどり着きました。だからこそ検証のステップは省けないのです。

記録する価値のある教訓はこうです。警告がログされる場所は結果が表面化する場所であって、原因が生まれる場所ではありません。もしあの日、支払いクライアントでそのままパッチを当てていたら、請求の合計は正しく見えたでしょうが、期限切れの割引レコードは依然カート内で誤ったまま居座り、のちに売上レポートを歪めていたはずです。元のログ行よりはるかに高くつく、静かなバグです。

/debug と subagent でコンテキストを隔離する

デバッグのセッションは多くの「ノイズ」を生みます。何十行ものログ、たくさんのファイル読み込み。機能を作っている会話にそれを混ぜると、メインのコンテキストが薄まり、回答の質が落ちます。解決策は調査を隔離することです。

Claude Code では、カスタムのスラッシュコマンドを定義し、専用の subagent に作業を渡せます。上記6ステップのワークフロー（まず調査、根本原因を証明、最小の修正を提案）をパッケージ化したプロンプトとして、プロジェクト独自の /debug コマンドを作り、必要なときに呼び出せます。あるいはバグ探し全体を専用のデバッグ subagentに渡せば、別のコンテキストで動き、簡潔な結論を返してくれるので、メインのセッションはきれいなまま保てます。

二重のメリットがあります。コンテキストがログで汚染されず、そしてバグごとにプロンプトを打ち直す代わりに、標準のワークフローを1つ使い回せます。実践的なコツ: 調査中はデバッグ subagent を読み取り専用にしておき、根本原因の結論を承認してから初めて編集権限を開くことです。そうすれば「調査」の部分と「修正」の部分が、ステップ3の精神に沿ってはっきり分かれ、実際の変更を起こすボタンを押すのは常にあなた自身になります。

効果的なデバッグ用プロンプト（コピーしてすぐ使える）

これは私が使い回しているプロンプト集です。コピーして、角括弧の部分を差し替え、Claude Code に貼り付けてください。

# 1. Investigate first, don't edit
Read [the files] and explain the flow that leads to the error in this
stack trace: [paste full trace]. DO NOT change anything. Just list 2-3
root-cause hypotheses, ranked by likelihood, each with a line of code
as evidence.

# 2. Trace the root cause
Walk backward from where the error fires to its source. For each step,
answer "why" (5 Whys) and quote the exact line of code that proves it.
Stop when you reach a cause you can no longer ask "why" about.

# 3. Propose the smallest safe fix
The root cause is confirmed to be [X]. Propose the SMALLEST change that
fixes this exact cause. No bundled refactor. Include 1 test that
reproduces the bug.

# 4. Explain why the bug happened
Summarize in 3 sentences: what the bug is, where the root cause is, and
why this fix is safe - so I can note it in CLAUDE.md.

AIでデバッグするときのよくある間違い

• 最初の修正を信じてしまう。 最初の提案はたいてい症状にパッチを当てます。常に「これは根本原因か、それともエラーが発生する場所にすぎないのか?」と問いましょう。
• トレースを一部しか貼らない。 最後のエラー行だけを渡すと地図が途切れ、AIは推測を強いられ、そして誤ります。
• 原因が明確になる前にAIに修正させる。 当てずっぽうの修正はバグを覆い隠したり、別のどこかで新たなバグを生んだりします。
• AIが原因をハルシネーションする可能性を無視する。 AIは非常に自信ありげな、しかし誤った推論の連鎖を組み立てられます。だからこそコードで証明させるのです。
• 再現テストを書かない。 安全網なしで修正を出せば、バグは数スプリント後に、誰にも気づかれず戻ってきます。

これらの多くはClaude Code のよくあるエラーと重なります。つまずかないために読んでおく価値があります。セキュリティ関連のバグは、専用のClaude Code によるセキュリティ監査のワークフローに切り分けましょう。

あらかじめ用意された根本原因スキルでデバッグを高速化する（AgentKit）

6ステップのワークフローを毎回打ち直したくないなら、AgentKit Engineer Kit には、まさにこの考え方をパッケージ化した体系的なデバッグ skill が付いています。パッチへ飛びつく代わりに、修正を提案する前に根本原因の証明を強制します。Claude Code より「賢い」わけではありません。ただ調査の規律を標準化し、検証のステップを忘れないようにしてくれるのです。Engineer Kit の価格は $99 です（サイトに継続課金の記載はありません）。この記事のワークフローがあなたの働き方に合うなら、Claude Code 向け Engineer Kit をチェック — 20%オフ、いまなら $79.20 して、すぐに使い始められます。

よくある質問（FAQ）

AIは自分で根本原因を修正しますか?

自動ではしません。完全なスタックトレースを渡し、正しいファイルを指し示し、修正の前に調査させれば、AIは正しい原因をたどれます。検証のステップを飛ばすと、たいてい根本ではなく症状にパッチを当てます。

スタックトレースはどのくらいAIに貼るべきですか?

最後の1行だけでなく、トレース全体を貼りましょう。上位の呼び出しフレームは、AIが発生源まで逆向きにたどるための地図です。失敗の瞬間まわりのログと、それを再現するコマンドも含めてください。

AIでのデバッグは ChatGPT を使うのとどう違いますか?

ChatGPT はたいてい、チャットボックスに貼り付けたスニペットしか読みません。Claude Code はプロジェクトの中で動くエージェントで、自分でファイルを開き、リポジトリを検索し、テストを実行します。だから狭いコンテキストで推測する代わりに、複数のファイルをまたいでバグをたどれます。

Claude Code は Windows でデバッグできますか?

はい。ak CLI と Claude Code は Windows、macOS、Linux でネイティブに動きます。この記事の6ステップのワークフローはOSに依存しません。変わるのは、バグを再現するコマンドがあなたのスタックに応じて変わることだけです。

AIは修正中に私のコードを壊すことがありますか?

原因が明確になる前にAIに修正させれば、そのリスクはあります。最小の修正を求め、受け入れる前に差分を注意深くレビューし、安全網として再現テストを常に用意しておくことで、リスクを減らせます。

複数ファイルにまたがるバグにはどのツールが最適ですか?

層をまたぐバグ（コントローラからサービス、リポジトリへ）には、Claude Code のようにコードベース全体を読めるエージェントが必要です。貼り付けたスニペットしか受け取らないツールでは、ファイル間で断片をつなぎ合わせるのに苦労します。

まとめと次のステップ

ひと言でいえば、まず根本原因を見つけ、修正は次。AIでのデバッグの力は、手早いパッチを求めることではなく、Claude Code を調査役に変えることにあります。調査させ、仮説を証明させ、それから初めてテスト付きで最小の修正を適用させるのです。修正のあとは、AIにコードをレビューさせ、リグレッションを防ぐために先にテストを書くTDDスタイルを検討する価値があります。この規律を、すぐ使えるワークフローとして標準化したいなら、AgentKit を試してみてください（リンク経由で20%オフ）。