Claude Codeデバッグの精度は、渡す情報の質で決まる

Claude Codeでバグを直すとき、精度を左右するのは指示の書き方より渡す情報の順序と量です。再現コマンド・エラーメッセージの原文・間欠的かどうかを最初に渡すだけで、原因特定にかかる往復の回数は大きく変わります。この記事では再現・原因特定・修正の検証・回帰テストの4段階に分け、それぞれで人間側が何を渡すと速く正確になるかを手順として示します。

Claude Codeに渡す情報でデバッグ速度が変わる

「バグを直して」とだけ渡すと、Claude Codeは公式の基本フローどおりに動きます。エラーをそのまま共有し、修正案をいくつか提示し、選んだ修正を適用する。この3ステップ自体は難しくありません。

問題はその先です。Claude Codeは作業が完了したように見えると手を止めます。テストやビルドのような実行可能なチェックを渡さない限り、「見た目で完了している」ことだけが判断材料になり、検証は結局人間が担うことになります。ここが丸投げと指示の出し方の分かれ目です。

基本フローの3ステップだけでは、直ったかどうかの確認が人間に残ります。渡す情報は、次の4段階それぞれに対応します。

次の節では、渡す情報の中身を早見表にします。

原因特定を速くする情報5点の早見表

Claude Codeへの依頼は、次の5点が揃っているかどうかで往復回数が変わります。

前半3点は再現の精度を、後半2点は原因特定と検証の精度を上げます。実際の依頼文で比べると差がわかりやすくなります。

前提

この記事の手順は、次の条件を満たしている前提で進めます。着手前に確認してください。

• /goal: ワークスペースのtrustダイアログを承認済みで、disableAllHooks や管理設定の allowManagedHooksOnly を有効にしていないことも条件になります。
• /code-review --fixのバックグラウンド実行: v2.1.218以降で既定になります。それより前のバージョンでは現在のセッション内で実行されます。
• --chromeでのブラウザデバッグ: Claude in Chrome拡張のバージョン1.0.36以上と、/login によるログイン認証が必要です。APIキーや長期トークンで認証しているセッションでは有効になりません。

満たしていない項目があれば、該当の手順を読み替えるかバージョンを更新してから進めてください。

手順1: 再現条件をそのまま渡す

最初のやり取りは、Claude Codeにエラーをそのまま見せることから始まります。要約せずに原文を貼るほうが、無関係な情報を削ぎ落として渡すより結果的に速いことが多いです。

npm testを実行するとログインのテストが失敗する。
再現コマンド: npm test -- --grep "login"
発生頻度: 常に失敗する(間欠的ではない)
 
[スタックトレースをそのまま貼り付け]

このあと修正案をいくつか出させ、どれを適用するか人間が選ぶという順序が基本です。いきなり1つの修正を指示するより、選択肢を並べてもらってから選ぶほうが、的外れな修正が本番コードに紛れ込むリスクを減らせます。

大きなコードベースでは、原因の見当をつける前段階として /context でどのファイルやCLAUDE.mdが読み込まれているかを確認しておくと、探索の起点がずれているケースに早く気づけます。

手順2: 原因の絞り込みは調査を切り出して任せる

原因特定でよくある失敗は、ログやファイル全体をそのまま会話に流し込んでコンテキストを圧迫することです。サブエージェントは独自のコンテキストウィンドウを持つため、大量のログ読みやファイル探索を任せ、要約だけをメイン会話に戻させられます。会話が調査結果で埋まらず、直後の修正判断も鈍らずに済みます。

ブラウザ側で起きる不具合には --chrome フラグでClaude in Chrome拡張に接続し、コンソールエラーやDOM状態を直接読ませる方法もあります(バージョン1.0.36以上・/login によるログイン認証が前提。詳しくは前提を参照)。APIキーや claude setup-token で発行した長期トークンで認証しているセッションでは、--chrome を付けてもChrome連携は有効になりません。v2.1.216より前はこの状態でも有効にでき、拡張への接続が毎回403エラーで失敗していました。

claude --chrome

ここでも渡し方の粒度が結果を左右します。「コンソール出力を全部見て」ではなく、「ダッシュボードを開いてページ読み込み時のコンソールエラーを確認して」のように、着目すべきパターンを絞って伝えるほうが精度が上がります。ログは冗長になりがちで、全量を渡すこと自体が原因特定を遅らせる要因になります。

手順3: 修正案は適用前に検証する

修正案が出たら、そのまま適用する前に一度立ち止まります。Planモードで編集前の計画をレビューできるほか、症状ではなく根本原因を直すよう明示的に依頼すると、その場しのぎの回避策を避けられます。

ビルドが次のエラーで失敗する: [エラーを貼り付け]
修正してビルドが通ることを確認して。根本原因を直し、エラーを握りつぶさないこと。

「根本原因を直す」という一文を添えるだけで、try/catchでエラーを黙らせるような表面的な修正を避けやすくなります。差分が大きい場合は、適用前に別のサブエージェントで /code-review のようなレビューを挟むという選択肢もあります(詳しくは次節)。

手順4: 回帰テストと完了条件で再発を防ぐ

Claude Codeが「直った」と判断する根拠を、人間が最後まで担い続ける必要はありません。検証の強さは、弱いものから順に4段階に分けられます。

/goal はターンごとに小さな判定用モデルが完了条件を評価し、満たすまで自律的にターンを重ねる仕組みです。判定用モデルの既定は、Claude APIを使う場合はHaikuです。サードパーティのプロバイダ経由では既定が異なります。ただし判定はClaudeが会話に出した内容だけを見て行われ、コマンドを自分で実行するわけではありません。条件は「測定可能な終了状態」「どう証明するか」「途中で崩してはいけない制約」の3点で書くと機能しやすくなります。

/goal 自体は権限モードを変更しないため、既定の権限モードのままだとテストコマンド実行のたびに確認が入り「無人での自動判定」にはなりません。無人でターンを回したい場合はauto modeと組み合わせる必要があります。

/goal test/authの全テストが通り、lintもクリーンな状態

さらに強く縛りたい場合は、テストやlintをStop hookでスクリプトとして実行し、失敗時に exit 2 を返すことで完了そのものをブロックできます。似た仕組みにPostToolUseもありますが、こちらはexit 2を返してもすでに実行済みのツールを取り消せず、Claudeにstderrをフィードバックするだけで完了はブロックしません。完了そのものを止めたい場面ではStop hookを使う必要があります。回帰テストの追加とその実行確認をワークフローに組み込みたいときは、テスト駆動開発の手順で失敗するテストを先に書く型と組み合わせると締まりが良くなります。

具体的な設定は次のとおりです。プロジェクト直下の .claude/settings.json にStop hookを1つ登録し、実体のスクリプトでテストスイートを実行します。Stop はマッチャーによる絞り込みに対応していないため、対象を指定するフィールドは不要です。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-tests.sh"
          }
        ]
      }
    ]
  }
}

呼び出し先のスクリプトでテストスイートを実行し、失敗していれば exit 2 を返して完了をブロックします。

#!/bin/bash
if ! npm test; then
  echo "Tests are failing. Fix them before finishing." >&2
  exit 2
fi
 
exit 0

この型を回帰テストの追加まで含めて回すと、根本原因を修正する→再現できていなかった失敗テストを追加する→このStop hookがテストスイート全体を再実行して回帰がないか確認する、という一連の流れが1セッション内で完結します。pytestを使うPythonプロジェクトでは、失敗の記録をセッションをまたいで引き継げるMCPサーバーも選択肢になります(pytestの失敗をMCPサーバーでClaudeに解析させる)。

回帰テストが通ったあとの仕上げとして、/code-review --fix を使うと差分に対する第三者チェックを任せられます。v2.1.218以降はこのレビューが既定でバックグラウンドのサブエージェントとして走り、それより前のバージョンでは現在のセッション内で実行されます。

次のいずれかに当てはまる場合は、バックグラウンドではなくフォアグラウンドで実行されます。

• すでに実行中のレビューを再実行したとき
• -p やAgent SDK経由で非対話的に実行したとき
• 環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に設定しているとき

またバックグラウンドレビューが --fix で加えた変更はセッションのチェックポイントの外側で適用されるため、/rewind では戻せません。取り消したい場合はgitで戻す必要があります。

effortを指定する場合は /code-review low --fix のように、effortの水準をコマンドの先頭に位置引数として渡します。lowやmediumでは確信度の高い指摘に絞られ、high以上はノイズが増える代わりに網羅性が上がります。effortを省略すると、直近に指定した水準(過去のセッションで指定したものを含む)が再利用されます。一度も指定していなければセッションの現在のeffortが使われ、v2.1.223より前は常にセッションの現在のeffortでした。

/code-review low --fix

  -d, --debug [filter]    Enable debug mode with optional category
                          filtering (e.g., "api,hooks" or "!1p,!file")
  --debug-file <path>     Write debug logs to a specific file path
                          (implicitly enables debug mode)

原因を外したときの立て直し方

Claude Codeが最初に出した診断が外れることは珍しくありません。ここで会話を続けたまま訂正を重ねるのは得策ではありません。同じ問題を1セッション内で2回訂正しても直らない場合、会話は失敗した試行錯誤で埋まっており、そのまま続けても新しい視点は出にくくなります。/clear で仕切り直し、これまでにわかった条件を盛り込んだより具体的なプロンプトで再スタートするほうが早く収束します。

再スタート時に持ち込む材料として有効なのがデバッグログです。/debug はセッション途中からでもデバッグログの記録を有効化できるSkillコマンドで、問題を一言添えると分析の焦点を絞れます。最初からログを取りたい場合は起動時に --debug を付け、= でつないだ形でカテゴリを絞ると出力量を抑えられます。空白区切りで書くと絞り込みは効かず、デバッグモードが有効になるだけです。

claude --debug="api,hooks"

コンテキストが上限に達するとリクエストは「Prompt is too long」で失敗します。自動圧縮に失敗すると「Prompt is too long · automatic compaction failed:」と出ます。やり取りが1往復しかないと「A single-exchange conversation cannot be compacted」です。どちらでも /clear で仕切り直し、必要な条件だけを渡し直します。

Claude Code自体が不調なときは切り分けが違う

ここまではユーザーが書いたアプリケーションコードのバグを対象にしてきました。一方で、指示を無視する・Hookが発火しない・MCPサーバーに繋がらないといった不調は、Claude Code自体の設定や実行環境の問題であり、切り分け方が異なります。配置や書式の見落としから辿る切り分け手順はClaude Code設定が反映されない原因の探し方にまとめています。

この場合はまず /context でCLAUDE.mdやスキルの説明が読み込まれているかを確認します。次に /doctor でインストールや設定の健全性チェックを走らせます。/doctor は重複インストール・PATHの問題・読み込めない設定ファイルのほか、使われていないスキルやMCPサーバーと遅いhookも調べます。

原因の当たりがつかないときは、すべてのカスタマイズを無効化した claude --safe-mode で再現するかどうかを見ます。切り分けの基本はここです。safe modeで問題が消えるなら、CLAUDE.md・Hooks・MCP・プラグインのいずれかのカスタマイズが原因だとわかります。どの層かまではsafe mode単体では絞り込めないため、/context(CLAUDE.mdやスキルの読み込み状況)・/hooks・/mcp を個別に確認します。なお組織が管理設定で配布しているhookやポリシーはsafe modeでも無効化されない点に注意してください。

メモリ使用量そのものが高くセッションが重くなっている場合は、/heapdumpでヒープスナップショットと診断用JSONを書き出せます。.heapsnapshotには会話全体と資格情報が含まれるため共有せず、報告には-diagnostics.jsonだけを添付します。報告・自己調査の手順はClaude Codeの/heapdumpでメモリ使用量の高さを診断するで扱っています。

Claude Codeが起動失敗やレート制限などのエラーを出しているときはClaude Codeでよくあるエラーを、MCPサーバーへの接続だけがおかしいときはMCPサーバーに接続できないときの切り分けを参照してください。切り分けた結果Claude Code自体のバグだと分かったら、/bugや/feedbackでセッションの文脈を添えて報告できます。同意画面と送信内容、サードパーティ接続時のローカルアーカイブの扱いはClaude Codeのバグ報告とフィードバック送信(/bug /feedback)にまとめています。

よくあるつまずき

• ログを全部渡してしまう: コンソール出力やログファイルを丸ごと貼ると、かえって着目点がぼやけて精度が落ちます。見てほしいパターンを絞って伝えるほうが結果は安定します。
• コンテキストを圧迫したまま続ける: 大量のファイル読み込みやログ貼り付けでコンテキストウィンドウが埋まると、後半のやり取りの精度が落ちます。/compact や /clear の使いどころを意識しておくと防げます。
• 完了条件を曖昧にしたまま/goalを使う: /goal の判定はClaudeが会話に出した内容だけを見て行われ、コマンドを自分で実行して確かめるわけではありません。「lintがクリーン」のように、Claude自身の出力で示せる条件にしないと機能しません。
• ブラウザデバッグ中にJSダイアログを見落とす: alert や confirm のようなJavaScriptダイアログが開いたままだと、ブラウザ操作そのものがブロックされ、Claudeの操作が届かなくなります。

まとめ

丸投げと手動検証の中間に立つには、渡す情報の質と、完了を判定する仕組みの強さを別々に選びます。直す対象がアプリのコードならこの記事の4段階を、Claude Code自体の不調なら --safe-mode での切り分けを起点にしてください。Pythonのメモリリークのように計測値を渡す例は、tracemallocとmemrayの出力を渡す手順にあります。再現から修正までの型をプラグインで借りるなら、debugスキルの手順もあります。