Claude Codeにバグ修正を頼んだのに、いつまでたっても直らない。それどころか、動いていた別の場所まで壊れてしまった。Claude Codeでよく起きる失敗です。
私も最初は「ここバグってるから直して」と雑に投げて、Claudeが見当違いのコードを書いては戻し、書いては戻しの無限ループにハマっていました。
原因はシンプルで、AIに渡す情報と進め方を間違えていたからです。
Claude Codeは正しい手順で使えば、バグの根本原因をかなりの精度で突き止めてくれます。
逆に、いきなり「直して」だけだと、症状だけ見て的外れな修正を量産します。
この記事では、公式ベストプラクティスと実践者の知見を照らし合わせながら、私が試行錯誤して身につけたバグ対応のコツを5つの原則と5ステップのワークフローに整理しました。
/rewindでの巻き戻しも含めて、今すぐ使える形でまとめています。
この記事でわかること
- Claude Codeにバグ修正を頼むときの正しい指示の出し方
- 「直らないループ」を防ぐ5つの原則
- 根本原因を突き止める5ステップのデバッグ手順
- うまくいかない時のリセット術
PARTS LIST ／目次
Claude Codeのバグ対応で最初に押さえる結論
Claude Codeのバグ対応で成果を分けるのは、たった2つです。「いきなり直してと言わない」ことと、「探索→計画→実装→検証の順で進める」こと。
この2つを守るだけで、修正の精度は体感で何倍も変わります。
なぜここが結論かというと、Claude Codeはチャットボットではなく、自分でファイルを読みコマンドを実行する「エージェント」だからです。
指示の出し方ひとつで、賢くもなれば暴走もします。
最初の一手を間違えると、あとはずっと尻拭いに追われます。逆に入り口さえ正しければ、あとはClaudeが勝手に調べて直してくれます。
いきなり「直して」と言わないのが鉄則
「このバグ直して」は最悪の指示です。Claudeは原因を理解しないまま、それっぽいコードを書き始めます。
Anthropicの公式ベストプラクティスでも、まず関連ファイルを読ませて計画を立てさせ、その計画を確認してから実装に入る流れが推奨されています。急がば回れ、です。
指示を出してから変更を確認・承認するまでの基本の流れは、Claude Code使い方｜導入から実践活用までの「基本の使い方」にまとめています。
探索→計画→実装→検証の4フェーズで進める
公式が勧める王道の流れが、この4フェーズです。まず探索でコードを理解させ、次に修正計画を立てさせ、承認してから実装、最後にテストで検証する。
研究と実装を切り分けると、間違った問題を解いてしまう事故を防げます。バグ対応はこの型に乗せるだけで安定します。
なぜ「このバグ直して」だと直らないのか
雑な指示でバグが直らないのには、明確な理由が2つあります。
AIが症状しか見ていないことと、修正を繰り返すうちにClaudeの「記憶」が汚れていくことです。
この2つを知っておくと、なぜ自分の指示が空振りしていたのかが腑に落ちます。
放置すると地味に怖いのが、トークンの浪費です。曖昧な指示は試行錯誤を増やし、無駄なやり取りでコンテキストもコストも食いつぶします。
1回の指示で的確に伝えることが、結果的にいちばんの節約になります。直らないだけでなく、財布にも痛い出費になります。
AIは症状しか見ず根本原因を外す
「ログインできない」とだけ伝えると、Claudeはログイン画面まわりだけをいじります。でも本当の原因がトークン更新の処理にあったら、永遠に直りません。
症状と原因はしばしば別の場所にあります。だからこそ、原因を推測させる前に十分な情報を渡す必要があります。
何度も修正でコンテキストが汚れる罠
Claudeは会話の全履歴を「コンテキスト」として保持します。失敗した修正を何度も重ねると、その失敗の痕跡が履歴に溜まっていきます。
公式も指摘していますが、コンテキストが満杯に近づくほどClaudeの判断力は落ちます。直らない修正の積み重ねが、さらに直らない状況を生む悪循環です。
バグ対応を成功させる5つの原則
ここからが本題です。Claude Codeでバグを的確に直すための原則を5つに絞りました。どれも難しくなく、明日から使えるものばかりです。
全部を完璧にやる必要はなく、まずは1番のエラー情報の渡し方だけでも効果を実感できます。
この5原則は、公式ベストプラクティスと実践者のワークフローから、特に効果の大きいものを抜き出したものです。順番にもこだわりました。
情報を渡し、計画させ、根本に対処し、テストで守り、知見を残す。バグ対応の一連の流れをそのままなぞっています。
エラーとスタックトレースは丸ごと渡す
いちばん大事な原則です。エラーメッセージを要約せず、スタックトレースごと生のまま貼り付けてください。
最初のメッセージで完全な情報を渡すほど、原因特定までの往復回数は減ります。情報の出し惜しみは、遠回りのもとです。
# ログファイルの中身をそのままClaudeに渡す例
cat error.log | claude本番のログを渡す前に個人情報・認証情報をマスキングする
エラーログを丸ごと渡すのは正しい原則ですが、本番環境のログにはメールアドレス・APIキー・アクセストークンがそのまま残っていることが珍しくありません。
渡す前に、これらの文字列を[REDACTED]などのプレースホルダーに置き換えてから貼り付けてください。
Claude Codeのsandbox機能には認証情報ファイルへの読み取りを遮断する設定（sandbox.credentials）もあります。
注意
この設定はローカルのファイルアクセスを守るものであり、あなたがコピー&ペーストで貼り付けた文字列までは守ってくれません。
丸ごと渡す原則と、機密情報を渡さない原則は両立させる必要があります。
複雑なバグはPlan Modeで先に計画する
Plan Modeとは、Claudeにコードを書き換えさせず、調査と修正計画の提示だけを行わせるモードです。
原因が読めない複雑なバグでは、まずPlan Modeを使います。
Shift+Tabキーを押すたびに通常モード→自動承認モード→Plan Modeの順で切り替わります（/planと直接入力しても切り替え可能です）。
Plan Modeなら、Claudeはファイルを読んで分析するだけで、勝手にコードを書き換えません。
アプローチを承認するまで変更が入らないので、動いているコードを壊す事故を防げます。慎重に進めたい場面の強い味方です。
症状ではなく根本原因に対処させる
「エラーを消して」ではなく「根本原因に対処して、エラーを抑制しないで」と明示します。
この一言を加えないと、Claudeはエラーをtry-catchで握りつぶすような、その場しのぎの修正をしがちです。
根本原因という言葉をプロンプトに入れるだけで、修正の質が変わります。
修正後は必ず回帰テストを書かせる
修正したら、そのバグを再現する回帰テストをセットで書かせます。テストはバグの記録になり、再発を防ぎ、修正が正しいことの証明にもなります。
Claudeに「テストを書いて、実行して、通ることを確認して」と頼めば、合格するまで自分で直し続けてくれます。検証ループを任せられるのが強みです。
直った原因はCLAUDE.mdに記録する
同じバグを二度踏まないために、解決した原因と対処をCLAUDE.mdに残します。
CLAUDE.mdは全セッションの冒頭で読み込まれる特別なファイルです。書き方はCLAUDE.mdとは？rulesとの違い・書き方まで完全ガイドにまとめています。
落とし穴やプロジェクト固有の癖を書いておけば、次から同じミスを未然に防げます。未来の自分への申し送りだと思って書いておきましょう。
実践：5ステップのデバッグワークフロー
原則を踏まえて、実際のバグ対応を5ステップに落とし込みます。「情報収集→仮説→証拠→確定→修正」の流れです。診断なしの修正はただの当てずっぽう。
当てずっぽうはまたテストが必要になるだけです。順を追って原因を詰めていきましょう。
ステップ1 情報を集めて状況を整理する
最初に、エラーメッセージ・スタックトレース・直近のgit logを揃えてClaudeに渡します。
関連するコードパスだけを読ませ、無関係なファイルは触らせません。ここで全体像を雑に渡すとコンテキストが膨らむので、的を絞るのがコツです。
ステップ2 原因の仮説を優先度つきで出させる
いきなり修正させず、「考えられる原因を、可能性が高い順に挙げて」と頼みます。修正ではなく仮説のリストを先に作るのがポイント。
複数の可能性を俯瞰できると、思い込みで1つの原因に飛びつく失敗を避けられます。最初の提案を鵜呑みにしないのも大切です。
このエラーの原因として考えられるものを、
可能性が高い順に並べて挙げてください。
まだコードは修正しないでください。仮説が浅いと感じたら5Whysで深掘りする
「なぜ」を5回繰り返すトヨタ生産方式の5Whys分析は、Claude Codeとの対話にもそのまま使えます。
「なぜこのエラーが出た」への回答に対して、もう一度「では、なぜそうなった」と聞き返す。
この「なぜ」の往復を3〜5回続けると、表面的な症状の奥にある構造的な原因まで掘り下げられます。
1回の質問で終わらせず、Claudeの回答をさらに疑うくらいでちょうどいいです。
仮説が「nullチェック漏れ」で止まっている時は、たいてい「なぜnullチェックが漏れたのか」という一段深い設計上の理由まで届いていません。
ステップ3 証拠を集めて仮説を検証する
各仮説を確かめる診断を実行します。ログ出力を足したり、特定の変数を検索したり、再現する失敗テストを書いたり。
Claudeに証拠を集めさせ、どの仮説が正しいかを絞り込みます。推測を事実に変える工程で、ここを飛ばすと結局やり直しになります。
ステップ4 根本原因を1文で確定する
集めた証拠をもとに、「根本原因を1文で説明して」と求めます。1文で言い切れないなら、まだ理解が足りない証拠です。
原因がぼやけたまま修正に進むと、また症状つぶしに逆戻り。ここで原因をはっきり説明できれば、修正はほぼ終わったも同然です。
ステップ5 最小限の修正とテストで仕上げる
確定した根本原因に対して、最小限の変更で修正します。あれもこれもと直すと、新しいバグの温床になります。
修正後は原則4の通り回帰テストを書き、テストスイートを通して仕上げ。最後に説明的なメッセージでコミットまで頼めば、一連の流れが完結します。
バグ対応がうまくいかない時の対処法
手順通りやっても、どうしても直らない時はあります。そんな時に粘り続けるのは逆効果です。
汚れたコンテキストを抱えたまま続けるより、思い切ってリセットしたほうが早く解決します。撤退も立派な戦略です。
/rewindで巻き戻してから仕切り直す
/rewindは、会話とファイルの変更をチェックポイント単位で巻き戻せる機能です。
入力欄が空の状態でEscキーを2回押すか、/rewindと入力すると一覧が開き、「コードだけ」「会話だけ」「両方」を選んで戻せます。
1回目の修正が的外れだったとわかった時点で、汚れたコンテキストを引きずったまま2回目を試すより先に、失敗した変更だけを/rewindで消してしまうほうが早いです。
ただし戻せるのは会話とClaudeが編集したファイルまでで、外部へのpushやデータベースへの書き込みなど、ファイル編集の外側で起きた副作用までは戻りません。
2回直して直らなければ/clearでやり直す
同じバグを2回直して直らなかったら、/rewindで戻すか、/clearでコンテキストごとリセットします。
ファイルの変更だけを取り消したいなら/rewind、会話の汚れごと一新したいなら/clearと使い分けるとよいでしょう。
失敗の痕跡で散らかった長い会話より、学んだことを盛り込んだ新しいプロンプトでやり直すほうが、ほぼ確実に早く片づきます。
負けを認めて仕切り直す勇気が大事です。
調査はサブエージェントに任せる
大量のファイルを調べる必要がある時は、サブエージェントに任せます。サブエージェントは別のコンテキストで調査し、結果の要約だけを返してくれます。
メインの会話が大量のファイル内容で汚れずに済むので、本筋の修正に集中できます。コンテキスト節約の切り札です。
複数の仮説を同時に調べたいなら、Ctrl+Bでサブエージェントをバックグラウンド実行に回すか、1回の指示で複数のTask呼び出しをまとめて投げると並列に調査させられます。
原因の絞り込みを1つずつ順番に潰すより、まとめて並走させたほうが待ち時間を圧縮できます。
よくある質問（FAQ）
Claude Codeのバグ対応について、よく聞かれる疑問をまとめました。気になるところだけ拾い読みしてもらえれば大丈夫です。
Q1. Claude Codeに最初に渡すべき情報は？
A1. エラーメッセージとスタックトレースを、要約せず生のまま渡すのが基本です。加えて直近のgit logと、関連するコードのファイル名を伝えると精度が上がります。情報が揃っているほど、無駄な往復が減ります。
Q2. Plan Modeはいつ使えばいい？
A2. 原因が読めない複雑なバグや、複数ファイルにまたがる修正で使います。逆にタイプミス修正など差分を1文で説明できる小さな変更では、Plan Modeは不要です。慎重さとスピードのバランスで使い分けましょう。
Q3. 何度直しても直らない時はどうする？
A3. 2回失敗したら/rewindで失敗した変更だけを巻き戻すか、/clearでコンテキストごとリセットし、学んだことを含めた新しいプロンプトでやり直します。失敗が溜まった会話を続けるより、仕切り直すほうが速いです。粘りすぎは禁物です。
Q4. /rewindと/clearはどう使い分ける？
A4. ファイルの変更だけを取り消したいなら/rewind、会話の汚れも含めて一新したいなら/clearを使います。/rewindはチェックポイントを使って、会話とClaudeが編集したファイルを前の状態へ戻せます。ただしpushやデータベースへの書き込みなど、ファイル編集の外側で起きた副作用までは戻せません。
Q5. 修正後にテストは本当に必要？
A5. はい、回帰テストは書くべきです。テストはバグの記録になり、再発防止と修正の正しさの証明を同時に果たします。Claudeに任せれば、テストが通るまで自動で直し続けてくれるので、手間もそれほどかかりません。
Q6. 同じバグを繰り返さないコツは？
A6. 解決した原因と対処をCLAUDE.mdに記録します。全セッションで読み込まれるので、次から同じ落とし穴を避けられます。プロジェクト固有の癖や注意点を書いておくと、チーム全体の助けにもなります。
Claude Codeのバグ対応で開発が変わる
SES時代は、原因不明のバグを半日がかりで追いかけるのが当たり前でした。ログにprint文を埋め込んでは再現を待ち、ソースコードを一行ずつ目で追う。
あの頃AIがあれば、と思うことがあります。今はClaude Codeにログを丸ごと渡せば、早ければ数分で「これが原因です」まで辿り着きます。
私自身、雑に「直して」と投げていた頃は、Claudeとケンカするように何度もやり直していました。
でも、エラーを丸ごと渡してPlan Modeで計画させる流れに変えてから、バグ対応のストレスが激減しました。
AIに丸投げするのではなく、調べ方をうまく仕込むイメージです。
大事なのは、Claude Codeを「魔法の修正ボタン」ではなく「優秀だけど指示待ちの後輩」として扱うこと。
情報をきちんと渡し、計画を確認し、根本原因に向き合わせる。この当たり前を徹底するだけで、バグ対応の景色は変わります。
【バグ対応の5原則 早見表】
1. エラーとスタックトレースは丸ごと渡す
2. 複雑なバグはPlan Modeで先に計画する
3. 症状ではなく根本原因に対処させる
4. 修正後は必ず回帰テストを書かせる
5. 直った原因はCLAUDE.mdに記録するまずは次のバグで、エラーログを丸ごと貼り付けるところから始めてみてください。たったそれだけで、Claudeの返答の的確さが変わるのを実感できるはずです。直らないと悩む時間を、別の楽しい開発に使いましょう。
| REV. | DATE | 内容 |
|---|---|---|
| 4 | 2026-10-16 | 図解を描き直し（図面のデザインにそろえた） |
| 3 | 2026-10-06 | 記載内容の事実確認と修正 |
| 2 | 2026-08-29 | 2026年8月時点の情報で全体を見直し |
| 1 | 2026-06-11 | 初版 |