Claude Codeにバグ修正を頼んだのに、いつまでたっても直らない。それどころか、動いていた別の場所まで壊れてしまった。そんな経験はありませんか。私も最初は「ここバグってるから直して」と雑に投げて、Claudeが見当違いのコードを書いては戻し、書いては戻しの無限ループにハマっていました。
原因はシンプルで、AIに渡す情報と進め方を間違えていたからです。Claude Codeは正しい手順で使えば、バグの根本原因をかなりの精度で突き止めてくれます。逆に、いきなり「直して」だけだと、症状だけ見て的外れな修正を量産します。
この記事では、私が実際に試行錯誤して身につけたClaude Codeのバグ対応のコツを、5つの原則と具体的な5ステップのワークフローにまとめました。読み終わるころには、「直らない」とイライラする時間がぐっと減るはずです。
Claude Codeのバグ対応で最初に押さえる結論
Claude Codeのバグ対応で成果を分けるのは、たった2つです。「いきなり直してと言わない」ことと、「探索→計画→実装→検証の順で進める」こと。この2つを守るだけで、修正の精度は体感で何倍も変わります。
なぜここが結論かというと、Claude Codeはチャットボットではなく、自分でファイルを読みコマンドを実行する「エージェント」だからです。指示の出し方ひとつで、賢くもなれば暴走もします。
最初の一手を間違えると、あとはずっと尻拭いに追われます。逆に入り口さえ正しければ、あとはClaudeが勝手に調べて直してくれます。
いきなり「直して」と言わないのが鉄則
「このバグ直して」は最悪の指示です。Claudeは原因を理解しないまま、それっぽいコードを書き始めます。Anthropicの公式ベストプラクティスでも、まず関連ファイルを読ませて計画を立てさせ、その計画を確認してから実装に入る流れが推奨されています。急がば回れ、です。
探索→計画→実装→検証の4フェーズで進める
公式が勧める王道の流れが、この4フェーズです。まず探索でコードを理解させ、次に修正計画を立てさせ、承認してから実装、最後にテストで検証する。研究と実装を切り分けると、間違った問題を解いてしまう事故を防げます。バグ対応はこの型に乗せるだけで安定します。
なぜ「このバグ直して」だと直らないのか
雑な指示でバグが直らないのには、明確な理由が2つあります。AIが症状しか見ていないことと、修正を繰り返すうちにClaudeの「記憶」が汚れていくことです。この2つを知っておくと、なぜ自分の指示が空振りしていたのかが腑に落ちます。
放置すると地味に怖いのが、トークンの浪費です。曖昧な指示は試行錯誤を増やし、無駄なやり取りでコンテキストもコストも食いつぶします。1回の指示で的確に伝えることが、結果的にいちばんの節約になります。直らないだけでなく、財布にも優しくないわけです。
AIは症状しか見ず根本原因を外す
「ログインできない」とだけ伝えると、Claudeはログイン画面まわりだけをいじります。でも本当の原因がトークン更新の処理にあったら、永遠に直りません。症状と原因はしばしば別の場所にあります。だからこそ、原因を推測させる前に十分な情報を渡す必要があります。
何度も修正でコンテキストが汚れる罠
Claudeは会話の全履歴を「コンテキスト」として保持します。失敗した修正を何度も重ねると、その失敗の痕跡が履歴に溜まっていきます。公式も指摘していますが、コンテキストが満杯に近づくほどClaudeの判断力は落ちます。直らない修正の積み重ねが、さらに直らない状況を生む悪循環です。
バグ対応を成功させる5つの原則
ここからが本題です。Claude Codeでバグを的確に直すための原則を5つに絞りました。どれも難しくなく、明日から使えるものばかりです。全部を完璧にやる必要はなく、まずは1番のエラー情報の渡し方だけでも効果を実感できます。
この5原則は、公式ベストプラクティスと実践者のワークフローから、特に効果の大きいものを抜き出したものです。順番にもこだわりました。情報を渡し、計画させ、根本に対処し、テストで守り、知見を残す。バグ対応の一連の流れそのままになっています。
エラーとスタックトレースは丸ごと渡す
いちばん大事な原則です。エラーメッセージを要約せず、スタックトレースごと生のまま貼り付けてください。実践者の報告では、最初のメッセージで完全な情報を渡せば、8割のバグが3往復以内で解決するとされています。情報の出し惜しみは、遠回りのもとです。
# ログファイルの中身をそのままClaudeに渡す例
cat error.log | claude複雑なバグはPlan Modeで先に計画する
原因が読めない複雑なバグでは、まずPlan Modeを使います。Plan Modeなら、Claudeはファイルを読んで分析するだけで、勝手にコードを書き換えません。アプローチを承認するまで変更が入らないので、動いているコードを壊す事故を防げます。慎重に進めたい場面の強い味方です。
症状ではなく根本原因に対処させる
「エラーを消して」ではなく「根本原因に対処して、エラーを抑制しないで」と明示します。これを言わないと、Claudeはエラーをtry-catchで握りつぶすような、その場しのぎの修正をしがちです。根本原因という言葉をプロンプトに入れるだけで、修正の質が変わります。
修正後は必ず回帰テストを書かせる
修正したら、そのバグを再現する回帰テストをセットで書かせます。テストはバグの記録になり、再発を防ぎ、修正が正しいことの証明にもなります。
Claudeに「テストを書いて、実行して、通ることを確認して」と頼めば、合格するまで自分で直し続けてくれます。検証ループを任せられるのが強みです。
直った原因はCLAUDE.mdに記録する
同じバグを二度踏まないために、解決した原因と対処をCLAUDE.mdに残します。CLAUDE.mdは全セッションの冒頭で読み込まれる特別なファイルです。
落とし穴やプロジェクト固有の癖を書いておけば、次から同じミスを未然に防げます。未来の自分への申し送りだと思って書いておきましょう。
実践：5ステップのデバッグワークフロー
原則を踏まえて、実際のバグ対応を5ステップに落とし込みます。「情報収集→仮説→証拠→確定→修正」の流れです。診断なしの修正はただの当てずっぽう。当てずっぽうはまたテストが必要になるだけです。順を追って原因を詰めていきましょう。
| ステップ | やること | ゴール |
|---|---|---|
| 1 | 情報収集 | 状況を整理する |
| 2 | 仮説生成 | 原因候補を並べる |
| 3 | 証拠収集 | 仮説を検証する |
| 4 | 原因確定 | 1文で言い切る |
| 5 | 修正とテスト | 最小限で仕上げる |
ステップ1 情報を集めて状況を整理する
最初に、エラーメッセージ・スタックトレース・直近のgit logを揃えてClaudeに渡します。関連するコードパスだけを読ませ、無関係なファイルは触らせません。ここで全体像を雑に渡すとコンテキストが膨らむので、的を絞るのがコツです。
ステップ2 原因の仮説を優先度つきで出させる
いきなり修正させず、「考えられる原因を、可能性が高い順に挙げて」と頼みます。修正ではなく仮説のリストを先に作るのがポイント。複数の可能性を俯瞰できると、思い込みで1つの原因に飛びつく失敗を避けられます。最初の提案を鵜呑みにしないのも大切です。
このエラーの原因として考えられるものを、
可能性が高い順に並べて挙げてください。
まだコードは修正しないでください。ステップ3 証拠を集めて仮説を検証する
各仮説を確かめる診断を実行します。ログ出力を足したり、特定の変数を検索したり、再現する失敗テストを書いたり。Claudeに証拠を集めさせ、どの仮説が正しいかを絞り込みます。推測を事実に変える工程で、ここを飛ばすと結局やり直しになります。
ステップ4 根本原因を1文で確定する
集めた証拠をもとに、「根本原因を1文で説明して」と求めます。1文で言い切れないなら、まだ理解が足りない証拠です。原因がぼやけたまま修正に進むと、また症状つぶしに逆戻り。ここで原因をはっきり言語化できれば、修正はほぼ終わったも同然です。
ステップ5 最小限の修正とテストで仕上げる
確定した根本原因に対して、最小限の変更で修正します。あれもこれもと直すと、新しいバグの温床になります。修正後は原則4の通り回帰テストを書き、テストスイートを通して仕上げ。最後に説明的なメッセージでコミットまで頼めば、一連の流れが完結します。
バグ対応がうまくいかない時の対処法
手順通りやっても、どうしても直らない時はあります。そんな時に粘り続けるのは逆効果です。汚れたコンテキストを抱えたまま続けるより、思い切ってリセットしたほうが早く解決します。撤退も立派な戦略です。
2回直して直らなければ/clearでやり直す
同じバグを2回直して直らなかったら、/clearでコンテキストを一度リセットします。失敗の痕跡で散らかった長い会話より、学んだことを盛り込んだ新しいプロンプトでやり直すほうが、ほぼ確実に早く片づきます。負けを認めて仕切り直す勇気が大事です。
調査はサブエージェントに任せる
大量のファイルを調べる必要がある時は、サブエージェントに任せます。サブエージェントは別のコンテキストで調査し、結果の要約だけを返してくれます。メインの会話が大量のファイル内容で汚れずに済むので、本筋の修正に集中できます。コンテキスト節約の切り札です。
よくある質問（FAQ）
Claude Codeのバグ対応について、よく聞かれる疑問をまとめました。気になるところだけ拾い読みしてもらえれば大丈夫です。
Claude Codeに最初に渡すべき情報は？
エラーメッセージとスタックトレースを、要約せず生のまま渡すのが基本です。加えて直近のgit logと、関連するコードのファイル名を伝えると精度が上がります。情報が揃っているほど、無駄な往復が減ります。
Plan Modeはいつ使えばいい？
原因が読めない複雑なバグや、複数ファイルにまたがる修正で使います。逆にタイプミス修正など差分を1文で説明できる小さな変更では、Plan Modeは不要です。慎重さとスピードのバランスで使い分けましょう。
何度直しても直らない時はどうする？
2回失敗したら/clearでコンテキストをリセットし、学んだことを含めた新しいプロンプトでやり直します。失敗が溜まった会話を続けるより、仕切り直すほうが速いです。粘りすぎは禁物です。
修正後にテストは本当に必要？
はい、回帰テストは書くべきです。テストはバグの記録になり、再発防止と修正の正しさの証明を同時に果たします。Claudeに任せれば、テストが通るまで自動で直し続けてくれるので、手間もそれほどかかりません。
同じバグを繰り返さないコツは？
解決した原因と対処をCLAUDE.mdに記録します。全セッションで読み込まれるので、次から同じ落とし穴を避けられます。プロジェクト固有の癖や注意点を書いておくと、チーム全体の助けにもなります。
Claude Codeのバグ対応で開発が変わる
私自身、雑に「直して」と投げていた頃は、Claudeとケンカするように何度もやり直していました。でも、エラーを丸ごと渡してPlan Modeで計画させる流れに変えてから、バグ対応のストレスが激減しました。AIに丸投げするのではなく、調べ方をうまく仕込むイメージです。
大事なのは、Claude Codeを「魔法の修正ボタン」ではなく「優秀だけど指示待ちの後輩」として扱うこと。情報をきちんと渡し、計画を確認し、根本原因に向き合わせる。この当たり前を徹底するだけで、バグ対応の景色は変わります。
【バグ対応の5原則 早見表】
1. エラーとスタックトレースは丸ごと渡す
2. 複雑なバグはPlan Modeで先に計画する
3. 症状ではなく根本原因に対処させる
4. 修正後は必ず回帰テストを書かせる
5. 直った原因はCLAUDE.mdに記録する
まずは次のバグで、エラーログを丸ごと貼り付けるところから始めてみてください。たったそれだけで、Claudeの返答の的確さが変わるのを実感できるはずです。直らないと悩む時間を、別の楽しい開発に使いましょう。
