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

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

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

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

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

基本フローの3ステップだけでは、直ったかどうかの確認が人間に残ります。再現条件・原因の絞り込み・修正の検証・回帰テストという4段階それぞれに、渡すべき情報が対応しています。次の節でその全体像を早見表にします。

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

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

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

前提

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

• /goal: Claude Code v2.1.139以降が必要です。ワークスペースの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連携は有効になりません。

claude --chrome

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

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

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

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

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

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

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

1. その場のプロンプト内でテスト結果を貼らせる(最も弱い)
2. /goal に完了条件を1文で渡し、ターンをまたいで自動判定させる
3. Stop hookでテストやlintをスクリプトとして実行し、通るまで完了をブロックする決定論的なゲート
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セッション内で完結します。

回帰テストが通ったあとの仕上げとして、/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がそのまま使われます。

/code-review low --fix

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

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

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

claude --debug "api,hooks"

長いセッションでは、/context を実行すると先頭に「Context exceeds the 200k-token limit by …」という警告が表示されることがあります。この状態のまま送信すると、リクエスト自体は「Prompt is too long」というエラーで失敗します。この場合は /compact で要約するか /clear で仕切り直し、必要な情報だけを再度渡し直します。

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

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

この場合はまず /context でCLAUDE.mdやスキルの説明が読み込まれているかを確認します。次に /doctor でインストールや設定の健全性チェックを走らせます。/doctor は診断結果を先に報告し、確認したうえで修正を適用する設計です。

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

Claude Codeが起動失敗やレート制限などのエラーを出しているときはClaude Codeでよくあるエラーを、MCPサーバーへの接続だけがおかしいときはMCPサーバーに接続できないときの切り分けを参照してください。

よくあるつまずき

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

よくある質問

Stop hookのスクリプトは具体的にどう書きますか

.claude/settings.json の Stop にコマンド型のフックを1つ登録し、実体のスクリプトでテストスイートを実行します。テストが失敗していれば exit 2 を返して完了をブロックし、通っていれば exit 0 で完了を許可します。設定断片とスクリプトの全文は手順4を参照してください。

環境で再現できないバグはどう扱えばいいですか

まず頻度を明記してClaudeに伝えます。常時発生する前提で調査すると、間欠的なバグの原因を見落としやすいためです。そのうえで /debug や --debug でセッションのデバッグログを取得し、次の会話で実際に何が起きていたかを一緒に渡すと、推測に頼らない立て直しがしやすくなります。

回帰テストは何で自動化できますか

/goal に完了条件を1文で渡すと、ターンをまたいで自動判定できます。さらに確実性を上げたいときは、.claude/settings.json にStop hookを登録し、テストスイートを実行するスクリプトで合否を判定させます。

/goalとStop hookはどう使い分けますか

/goal は完了条件を1文の自然言語で渡すだけで済み、判定はClaudeが会話に出した内容を見て行われます。手軽な反面、判定用モデル自身はコマンドを実行しません。Stop hookはスクリプトが実際にテストやlintを実行して合否を判定するため、より確実な決定論的なゲートになります。厳密さが必要な場面ではStop hookを、手早く条件を渡すだけで足りる場面では /goal を使う、という使い分けになります。

/debug と --debug フラグは何が違いますか

/debug はセッション内で使うSkillコマンドで、デフォルトで無効なデバッグログの記録を途中から有効化します。--debug は起動時に付けるフラグで、最初からログを取得でき、カテゴリを絞って出力量を抑えることもできます。

まとめ

Claude Codeでのデバッグは、丸投げでも完全な手動検証でもない中間の運用です。再現条件・症状と推定箇所・完了条件をまとめて渡し、原因調査はサブエージェントに任せ、修正は根本原因を確認してから適用し、最後は /goal やStop hookで回帰確認を自動化する。この4段階を型として持っておくと、同じバグに何度も同じ説明を繰り返す状況を避けやすくなります。

/goal やStop hook以外の運用ルールも含め、Claude Code全体の使い方はClaude Code完全ガイドにまとまっています。