結論：Claude Code は「バグを自動で直す魔法」ではなく「原因の当たりを高速に絞り込むデバッグの相棒」として使うと、調査時間が大きく縮む。エラーを読む・再現する・コードと git 差分を突き合わせる・仮説を検証する、という人間がやっていた往復を一緒に回してくれます。そして 2026年9月時点の Claude Code（v2.1.259）には、Claude Code 自体の不調を切り分ける道具（/doctor・claude --debug・--safe-mode・/context・/mcp・/hooks）が揃っているので、「自分のコードのバグ」と「Claude Code 側の問題」を分けて追えるようになりました。
① エラー/スタックトレースを読ませて原因の当たりをつける：例外メッセージと該当ファイルを渡し、怪しい箇所を3〜5個に絞らせる。
② 再現手順を整理する：いつ・どの入力で・どんな環境で起きるかを言語化し、最小再現コードに落とす。
③ git の最近の変更から犯人を絞る：直近のコミット差分を読ませ、症状と相関する変更を特定する。
④ Claude Code 自体が怪しいときは /doctor → claude --debug のログ → --safe-mode の順で切り分ける。
対象読者：自分の書いたコードや既存プロジェクトのバグ・障害を日常的に調査するアプリ／バックエンドエンジニア、テックリード、SRE。今日できること：手元の1件のバグで「エラー貼り付け→仮説3つ→最小再現→修正→テスト」を1周通す。
※本記事は 2026年9月時点の Claude Code 公式ドキュメント（v2.1.259・2026年9月2日リリース分まで）に基づきます。コマンド・フラグ・エラー文言は公式表記どおりです。仕様は更新されるため、最終挙動は各自の環境で claude --version と公式ドキュメントで確認してください。AI の原因推定は外れることがあります。必ず実際に再現して確かめ、修正は人がレビューする前提で使ってください。また、認証情報や個人情報を含むログをそのまま貼らないでください。
「このバグ、原因どこだろう」とログを上から下まで何度もスクロールする時間。正直、デバッグで一番しんどいのは「直す」工程よりも「どこが壊れているかを突き止める」工程なんです。私もnullが飛んでくる箇所を半日追いかけて、結局3コミット前の小さな変更が犯人だった、みたいなことを何度もやってきました。
Claude Code が効くのは、まさにこの「当たりをつける」フェーズです。エラーメッセージとコードを渡せば、人間が頭の中でやっていた「この例外なら、たぶんこのあたり」という推論を、根拠つきで言語化してくれる。ただし鵜呑みは禁物で、推測を必ず再現で裏取りする運用にすると、調査がぐっと速くなります。この記事では、その手順を7ステップにまとめたうえで、後半では「Claude Code 自体がおかしいとき」の切り分けを現行の公式仕様で整理します。
なぜデバッグに Claude Code を使うのか
デバッグは大きく分けて「①原因を特定する」「②修正する」「③再発を防ぐ」の3工程です。このうち時間を食うのは圧倒的に①で、しかもここで方向を間違えると、関係ないコードを延々と読むことになります。
Claude Code が向いているのは、コードベースを横断して文脈を集めるのが速い点です。スタックトレースに出てくる関数の定義を追い、呼び出し元をたどり、最近の git 差分と突き合わせる──この「探索」を、ターミナルから対話的にやってくれます。Claude Code はプロジェクトのファイルを読み、必要に応じてコマンドを実行できるエージェント型のツールなので、「grep して、関連ファイルを読んで、仮説を出す」までを一気通貫で回せます（公式の概要はClaude Code overviewを参照。2026年9月時点で公式ドキュメントは docs.claude.com から code.claude.com へ移転済みで、旧URLは301で転送されます）。
一方で、Claude Code はあなたのコードが本番でどう動いているかを実際に観測しているわけではありません。だから出てくるのはあくまで「もっともらしい仮説」であって、確定した原因ではない。ここを取り違えると、AI が示した間違った原因を信じて無関係な修正を入れてしまいます。本記事の手順は、すべて「仮説 → 再現で検証」という流れを軸にしています。
全体像：「自分のコードのバグ」と「Claude Code 側の不調」を分けて追う
2026年版で一番変わったのは、デバッグの対象が2層になったことです。ひとつは従来どおり「自分のアプリのバグ」。もうひとつは「Claude Code が期待どおりに動かない」問題で、hooks が発火しない・MCP サーバーが繋がらない・権限やサンドボックスでコマンドが止まる・コンテキストが溢れる、といった症状がここに入ります。後者は公式の Troubleshooting と Debug your configuration が入口になっていて、症状ごとに見るべき場所が決まっています。
| 症状 | まず見る場所 | 本記事の該当節 |
|---|---|---|
| アプリのテストが落ちる・本番で例外が出る | スタックトレース → 最小再現 → git 差分 | ステップ1〜5 |
| 調査で会話が長くなりすぎる | サブエージェントに調査を切り出す | ステップ6 |
| 作業を中断した・ターミナルを閉じた | claude --continue / claude --resume |
ステップ7 |
| 設定が効かない・何が読み込まれたか分からない | /context → /doctor → claude --debug |
Claude Code 自体の切り分け |
| hook が発火しない・hook error が出る | /hooks → matcher → デバッグログ |
hooks の切り分け |
| MCP サーバーが繋がらない・ツールが0件 | /mcp → claude mcp list → claude --debug=mcp |
MCP の切り分け |
| コマンドが勝手に止まる・聞かれずに実行される | パーミッションモード → deny ルール → サンドボックス | 権限・サンドボックス |
Context limit reached が出る |
/context → /compact → /clear |
コンテキスト不足 |
API Error: 5xx / 529 / 429 |
自動リトライ後の表示。Error reference | エラーメッセージ別早見表 |
迷ったら、セッション内で /doctor を打つのが公式の推奨です。claude 自体が起動しないときはシェルから claude doctor を使います。
ステップ1：エラーメッセージとスタックトレースを読ませて当たりをつける
最初にやるのは、生のエラー出力をそのまま渡して、原因の候補を絞らせることです。スタックトレースは情報が多く、人間が目で追うと見落としが出ます。Claude Code に「どのフレームが自分のコードか」「どの行が起点か」を整理させると速い。公式の Common workflows でも、再現コマンド・再現手順・間欠的か常に起きるか、の3点を伝えるのがコツとされています。
プロンプト例（実際の例外を貼り付ける想定）：
以下の例外が本番で出ています。原因の候補を可能性の高い順に3つ挙げ、
それぞれ「確認すべきファイル/関数」と「再現に必要な条件」を書いてください。
断定はせず、確認方法もセットで示してください。
再現コマンド: npm test -- tests/users.test.ts
発生頻度: 常に（同じ入力で100%再現）
TypeError: Cannot read properties of undefined (reading 'id')
at formatUser (src/users/format.ts:42:18)
at UserController.show (src/users/controller.ts:88:24)
at processTicksAndRejections (node:internal/process/task_queues:95:5)ポイントは「断定するな・確認方法をセットで」と明記すること。これを書かないと、AI は1つの原因を自信満々に言い切りがちです。候補を複数出させ、それぞれに検証手順を付けさせることで、こちらが裏取りしやすくなります。
スタックトレースを渡すときは、まず自分のソース行（上の例なら format.ts:42 や controller.ts:88）に注目するよう促すと、フレームワーク内部の行に気を取られずに済みます。テスト出力が長い場合は、対話せずにパイプで渡す手もあります。
npm test 2>&1 | claude -p "このテスト失敗の原因候補を3つ、確認方法つきで"ステップ2：再現手順を整理し、最小再現コードに落とす
原因の当たりがついたら、次は「確実に再現させる」工程です。再現できないバグは直したかどうかも確認できません。ここで Claude Code に再現条件を整理させ、最小再現（minimal reproduction）に落とします。
プロンプト例：
このバグについて、再現に必要な前提を箇条書きにしてください。
- どの入力（値・型・サイズ）で起きるか
- どの環境/設定で起きるか（Node バージョン、env、フラグ）
- 直前にどんな操作・状態があると起きるか
そのうえで、依存を最小化した再現用のテスト関数を1つ書いてください。
外部APIやDBは呼ばず、手元で `node` で実行できる形にしてください。最小再現を1つ作っておくと、修正後にそのコードがエラーを出さなくなったかどうかで、直ったかを機械的に判定できます。手順は次の流れで進めると詰まりにくいです。
- 症状を1文で言語化する（「ユーザー詳細APIで user が null のとき 500 になる」）。
- 再現条件を入力・環境・直前操作の3軸で洗い出す。
- 外部依存を取り除いた最小再現コードを書く。
- その最小再現で本当にエラーが出ることを自分の手で確認する。
4番が大事です。AI が書いた再現コードでエラーが出なければ、まだ条件を捉えきれていないサイン。条件を足して、再現する形に持っていきます。
ステップ3：git の差分と bisect で犯人コミットを絞る
「昨日まで動いていたのに今日壊れた」タイプのバグは、直近の変更が犯人であることが多いです。ここで git の差分を Claude Code に読ませると、症状と相関する変更を見つけやすくなります。
まず手元で直近の差分を出します。
git log --oneline -10
git diff HEAD~5..HEAD -- src/users/そのうえでプロンプト：
直近5コミットの差分を貼ります。今回の症状
「user が undefined のとき format.ts:42 で落ちる」と
関係しそうな変更を、コミット単位で指摘してください。
関係なさそうな変更は除外し、理由も書いてください。ここで Claude Code に git blame 的な視点（「この行はいつ・なぜ変わったか」）を持たせると、ガード句が削られた、型が変わった、デフォルト値がなくなった、といった原因を拾いやすくなります。
コミット数が多くて目視で絞れないときは、二分探索で犯人コミットを機械的に特定する git bisect と組み合わせます。ステップ2で作った最小再現をテストファイルにしておけば、そのまま git bisect run に渡せます。
# 最小再現テストを bisect の判定に使う（失敗＝bad、成功＝good）
git bisect start
git bisect bad HEAD
git bisect good v1.4.0
git bisect run npx vitest run tests/repro-user-null.test.ts
# 終わったら必ず戻す
git bisect resetClaude Code には「このバグを再現するテストを bisect 用に書いて。外部依存なし・終了コードで成否が分かる形で」と頼むと、判定に使えるテストを用意してくれます。bisect 自体は Claude Code に実行させてもよいのですが、git checkout を繰り返す操作なので、作業ツリーが汚れていないことを先に確認してから走らせてください。
ステップ4：仮説を立てて検証する（ログ追加・観測）
原因の候補が出たら、それを「証明」する工程です。ここでやってはいけないのは、AI の仮説をそのまま信じて修正してしまうこと。必ず観測して裏を取ります。
典型は print デバッグ（ログ追加）です。仮説が「user が undefined で渡ってくる」なら、その直前で値を出力して確認します。
// format.ts の該当箇所に一時的に追加
function formatUser(user: User | undefined) {
console.error('[debug] formatUser received:', JSON.stringify(user));
if (!user) {
throw new Error('formatUser: user is undefined'); // ガード句で原因を明確化
}
return { id: user.id, name: user.name };
}プロンプト例：
仮説「controller.ts:88 で user を渡す前に null チェックが抜けている」を
検証したいです。どこに何を出力すれば、この仮説の真偽が分かりますか？
最小限のログ追加箇所を3つ提案してください（本番に残さない前提）。検証で仮説が正しいと分かったら、原因を一文で確定させます（「show ハンドラで repository が null を返した場合の分岐が無く、そのまま format に渡していた」）。仮説が外れたら、ステップ1〜3に戻って候補を入れ替えます。この往復をサボらないことが、誤修正を防ぐ唯一の方法です。
なお、Claude Code の Bash ツールで実行した確認コマンドの出力は、そのまま Claude の文脈に入ります。巨大なログを丸ごと流すと後述の「コンテキスト不足」を招くので、grep や tail -n 50 で絞って渡すか、ファイルに書き出して必要な範囲だけ読ませるのが安全です。
ステップ5：修正したらテストで再発を防ぎ、/rewind で戻れる状態を保つ
原因が確定し、修正できたら、最後に「同じバグが二度と起きない」ための回帰テストを足します。ステップ2で作った最小再現コードが、ほぼそのままテストケースになります。
プロンプト例：
確定した原因
「repository が null を返したとき controller が format に null を渡していた」
に対する回帰テストを書いてください。
- 修正前なら失敗し、修正後なら通るテストにすること
- 正常系と「null が返るケース」の両方をカバーすること
テストフレームワークは Vitest を使います。「修正前なら失敗するテスト」を先に書いて、それが赤になることを確認してから修正を当てる──いわゆる回帰テスト先行の流れにすると、テストが本当にバグを捉えているか担保できます。テスト設計を Claude Code に任せる場合の進め方は、Claude CodeでQA・テスト自動化を加速する実践ガイドとテスト自動生成・TDD実践ガイドも合わせて読むと観点が増えます。
修正を試行錯誤する間は、チェックポイント機能が保険になります。Claude Code はプロンプトごとにファイル編集ツールによる変更のスナップショットを取っていて（直近100件）、/rewind（入力欄が空なら Esc 2回）から「コードと会話を戻す／会話だけ戻す／コードだけ戻す／ここから先を要約する」を選べます。ただしBash コマンドで変えたファイル（rm・mv・cp など）は追跡されず、サブエージェントの編集も原則巻き戻せません（git で戻す）。修正コミットには「原因」「再現条件」「テスト」をメッセージに残しておくと、将来の自分やチームが同じトレースを見たときの調査が速くなります。
ステップ6：調査をサブエージェントに委譲して、メインの文脈を汚さない
大きなコードベースで原因を探すと、ファイルを読むたびにメインの会話のコンテキストが埋まっていきます。公式の Common workflows（Delegate research to subagents）が勧めているのは、探索そのものをサブエージェントに切り出して「結論だけ」を持ち帰らせる型です。
use a subagent to investigate how our auth system handles token refresh日本語なら「サブエージェントに、トークン更新まわりで user が undefined になり得る経路を調べさせて。結論と該当ファイル・行だけ返して」で十分です。サブエージェントは自分専用のコンテキストウィンドウでファイルを読み、要約だけをメインに返します。2026年9月時点の仕様で押さえておくべき点は次のとおりです。
- 組み込みの Explore / Plan は CLAUDE.md を読まない。「vendor/ は無視して」のようなルールを守らせたいなら、委譲するプロンプトに書き直す。カスタムサブエージェントはメインと同じ CLAUDE.md を読む。
- 対話セッションではサブエージェントは既定でバックグラウンド実行になり、権限が必要なツール呼び出しはメイン側にプロンプトが上がってくる。進行中の一覧と完了したものの記録は
/tasksで見られる。 - 一度終わったサブエージェントは再開できる（「さっきの調査の続きで認可ロジックを見て」）。Explore / Plan は一発限り。
調査と修正を毎回同じ型でやらせたいなら、公式ドキュメントに載っているデバッガー用サブエージェントの定義（.claude/agents/debugger.md）をそのまま置くのが早いです。
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Focus on fixing the underlying issue, not the symptoms.サブエージェントの設計全般はClaude Codeサブエージェント並列開発入門にまとめています。
ステップ7：中断した調査を –continue / –resume で続ける
デバッグは一晩またぐことが普通にあります。Claude Code は会話をローカルの記録ファイルに逐次保存しているので、ターミナルを閉じても続きから再開できます。公式 Manage sessions の入口は次の5つです。
| コマンド | 動作 |
|---|---|
claude --continue（-c） |
現在のディレクトリで最後に使った対話セッションを再開 |
claude --resume（-r） |
セッションピッカーを開いて選ぶ |
claude --resume <name> |
名前を付けたセッションを直接再開 |
claude --from-pr <number> |
そのプルリクエストに紐づくセッションだけをピッカーに出す |
/resume |
セッション中に別の会話へ切り替える |
デバッグ用途で効くのは「名前」と「分岐」です。claude -n user-null-bug で名前を付けておけば（途中なら /rename）、翌日 claude --resume user-null-bug で戻れます。別の仮説を試したいが今の会話を壊したくないときは /branch try-guard-clause、またはシェルから claude --continue --fork-session です。
2026年9月時点で公式に明記されている注意点：
claude -p（非対話）や Agent SDK で作ったセッションはピッカーにも--continueにも出ない。セッションIDを控えておきclaude --resume <session-id>で再開する。- セッションIDによる検索は、まず現在のプロジェクト、次にこのマシン上の全プロジェクトを見る（v2.1.223 以降）。見つからなければ
No conversation found with session ID: <session-id>で終了コード1。 - ターミナルから
--continue/--resume <id or name>で再開すると会話・モデル・パーミッションモードが復元される（bypassPermissionsとplanで終わったセッション、ピッカー／/resume経由は復元されない）。 --mcp-configや--add-dirなどの起動フラグは復元されないので再開時にもう一度付ける。記録の保持は既定30日。
Claude Code がフリーズしたときの公式手順もシンプルで、Ctrl+C で中断、それでもだめならターミナルを閉じて同じディレクトリで claude --resume。会話は失われません。--continue と --resume の細かな使い分けはClaude Codeセッション再開の実践で掘り下げています。
Claude Code 自体が怪しいとき：/doctor → –debug → –safe-mode の順で切り分ける
ここからは「Claude Code の挙動がおかしい」ときの話です。公式の Debug your configuration によれば、原因のほとんどは「ファイルが読み込まれていない」「想定と違う場所から読まれた」「別のファイルに上書きされた」のどれかです。だから最初にやるのは推測ではなく「何が実際に読み込まれたか」の確認です。
| コマンド | 分かること |
|---|---|
/context |
今のコンテキストを占めているもの（システムプロンプト・ツール・MCP ツール・サブエージェント・メモリファイル・スキル・会話）。CLAUDE.md が載っているかをまず確認 |
/memory / /skills / /hooks / /mcp / /permissions |
各領域で実際に有効なもの |
/status |
有効な設定ソース（managed settings が効いているか） |
/doctor（別名 /checkup） |
インストール健全性・不正な設定ファイル・未使用の拡張・同一ディレクトリ内のサブエージェント名重複などを点検し、修正案を出す |
/debug [症状] |
そのセッションのデバッグログ記録を有効化し、ログと設定パスをもとに Claude 自身に診断させる |
次に、ログで実際の動きを見ます。claude --debug で起動するとデバッグログが ~/.claude/debug/<session-id>.txt に書かれます（--debug はターミナルには何も表示しません。ファイルを読みます）。場所を固定したいなら claude --debug-file /tmp/claude.log で、別ターミナルから tail -f できます。カテゴリで絞るには --debug='mcp,startup' のように = でつなぎます（空白区切りだとフィルタが効かず、単にデバッグモードになるだけ）。
# ログを固定パスに書き、別ターミナルで追いかける
claude --debug-file /tmp/claude.log
tail -f /tmp/claude.log
# MCP まわりだけ記録したい
claude --debug=mcp
# hook のマッチング詳細まで欲しいとき
CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose claude --debugそれでも切り分けられないときは、設定を全部外した状態で再現するかを見ます。claude --safe-mode（または CLAUDE_CODE_SAFE_MODE=1）は CLAUDE.md・スキル・プラグイン・hooks・MCP サーバー・カスタムコマンド/エージェントなどをすべて無効にして起動します（認証・モデル選択・組み込みツール・権限は通常どおり）。セーフモードで問題が消えれば、原因はそのどれかなので、上の表のコマンドで1つずつ戻して特定します。組織の managed settings はセーフモードでも適用される点に注意してください。
セーフモードでも再現する、あるいは設定ファイル自体が疑わしいなら、CLAUDE_CONFIG_DIR を空ディレクトリに向けて「何も読まない」セッションを作ります。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude初回セットアップ画面（テーマ選択）が出れば、クリーン設定が効いている目印です。ここでも再現するなら原因はユーザー/プロジェクト設定の外にあるので、/status で managed settings の有無と環境変数を疑い、Troubleshooting の性能・安定性の節へ進みます。
hooks が発火しない・壊れているときの切り分け
hooks は「設定したのに動かない」相談が一番多い領域です。公式ドキュメント（Hooks reference と Automate actions with hooks）が挙げている原因は、ほぼ次の表に収まります。
| 症状 | 原因 | 直し方 |
|---|---|---|
/hooks に出てこない |
hooks を単独ファイルに書いている | プロジェクト/ユーザー設定に独立した hooks ファイルは無い。settings.json の "hooks" キー配下に書く（別ファイル hooks/hooks.json を読むのはプラグインだけ） |
| グローバルに書いた hooks/permissions/env が無視される | ~/.claude.json に書いた |
~/.claude.json はアプリ状態用。~/.claude/settings.json に書く（別ファイル） |
| 出てくるのに発火しない | matcher が小文字（"bash"） |
大文字小文字を区別する。Bash・Edit・Write・Read |
| 出てくるのに発火しない | matcher を配列で書いた |
スキーマエラー扱いで、その設定ファイル全体が拒否される。"Edit|Write" のように1つの文字列で書く（, 区切りは v2.1.191 以降で同義） |
PreToolUse hook error: ... が出る |
スクリプトが想定外の非0終了 | サンプルJSONをパイプして手元で実行し、終了コードを見る（下記） |
| JSON を出しているのに効かない | シェルプロファイルの echo が先頭に混ざり、stdout が { で始まらない |
if [[ $- == *i* ]]; then echo ...; fi のように対話シェルだけで出力する |
| Stop hook で Claude が止まらず、最後に警告 | 8回連続ブロックの上限に到達 | 入力の stop_hook_active が true なら exit 0 する。上限は CLAUDE_CODE_STOP_HOOK_BLOCK_CAP |
hook スクリプト単体のテストは、Claude Code が渡す JSON を自分で流し込むのが確実です。
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $? # 終了コードを確認ここで押さえておきたい仕様が「終了コードの意味」です。ブロックできるのは exit 2 だけで、Unix 慣習の exit 1 は「非ブロッキングのエラー」として扱われ、動作はそのまま進みます（transcript に Failed with non-blocking status code: 付きの通知が出る）。ポリシーとして止めたい hook なら必ず exit 2 にし、理由は stderr に書きます。
#!/bin/bash
# rm を止める PreToolUse hook（公式ドキュメントの例）
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")
if [[ "$command" == rm* ]]; then
echo "Blocked: rm commands are not allowed" >&2
exit 2 # ブロック
fi
exit 0 # 判断なし：通常の権限フローに任せる「command not found」が出るときは絶対パスか ${CLAUDE_PROJECT_DIR} でスクリプトを指し、chmod +x を忘れない。クォート問題を避けたければ "args": [] を付けて exec 形式にします。
hook が「本当に走ったのか」は Ctrl+O の transcript ビューか、claude --debug のログ（どの hook がマッチし、終了コードと stdout/stderr が何だったか）で見ます。
2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] Hook PostToolUse:Write (PostToolUse) success:
hook-ranもうひとつ、デバッグ運用で見落としがちなのが hook のタイムアウトです。command 型の既定は10分（UserPromptSubmit は30秒）で、超えると出力ごと破棄されて「判断なし」になります。PreToolUse がタイムアウトしてもツール呼び出しは止まらず通常の権限フローに流れるので、テスト実行のような重い処理を hook に入れるなら timeout フィールドで明示的に延ばしてください。hooks の実装パターン自体はClaude Code Hooks実践ガイドにまとめています。
MCP 接続のトラブルシュート
デバッグ中に「DB を直接引きたい」「GitHub の Issue を読みたい」と MCP サーバーを足すことが増えました。繋がらないときの手順は、公式 Connect to MCP servers の Troubleshooting 節と MCP の Managing your servers 節が正です。まず状態を見る：
# シェルから：設定済みサーバーと接続状態
claude mcp list
claude mcp get <name>
# セッション内：状態確認・再接続・認証・有効/無効
/mcp
/mcp reconnect <server>
/mcp disable <server>状態は ✔ Connected・! Needs authentication・✘ Failed to connect・✘ Connection error・⏸ Pending approval（プロジェクトサーバー未承認）などで表示されます。v2.1.219 以降、Failed to connect には HTTP ステータスやサーバーのエラー文が付き、claude mcp get では Issue: 行に出るので、まずここを読みます。
| 症状 | 原因 | 直し方 |
|---|---|---|
/mcp が No MCP servers configured |
別プロジェクトで claude mcp add した／設定ファイルの場所が違う |
local スコープはプロジェクトに紐づく。--scope user で追加するか、正しい場所（~/.claude.json と <project>/.mcp.json）を編集。~/.claude/.mcp.json や ~/.claude/mcp.json は読まれない |
.mcp.json のサーバーが一切ロードされない |
.claude/ 配下に置いた／トップキーが servers（VS Code 形式） |
リポジトリ直下に .mcp.json、キーは mcpServers |
settings.json の mcpServers が無視される |
settings.json はそのキーを読まない |
プロジェクトは .mcp.json、ユーザーは claude mcp add --scope user |
| 追加したのに出てこない | プロジェクトサーバーの一回限りの承認プロンプトを閉じた | /mcp で承認する |
| あるディレクトリからだけ起動失敗 | command / args が相対パス |
起動ディレクトリ基準で解決されるので絶対パスにする（npx / uvx のような PATH 上のものはそのままで可） |
起動時に Connection timed out |
初回の npx ダウンロードが30秒の既定を超えた |
MCP_TIMEOUT=60000 claude（ミリ秒） |
| Connected なのにツールが0件 | 起動はしたがツール一覧を返していない | /mcp で Reconnect。変わらなければ claude --debug=mcp で起動し、~/.claude/debug/<session-id>.txt のサーバー stderr を読む |
HTTP サーバーなら、URL に到達できるかを curl で切り分けます。
curl -I https://mcp.sentry.dev/mcp
# 404/405 → サーバーは生きている（多くの MCP エンドポイントは POST のみ）
# 401/403 → 認証が必要。/mcp のブラウザ認証か --header "Authorization: Bearer <token>"
# 無応答 → URL かネットワークを疑うstdio サーバーなら、設定したコマンドをそのままターミナルで実行して、起動して入力待ちになるか（サーバー自体は正常）、エラーで落ちるか（Node.js やブラウザが無い等）を見ます。起動するのに繋がらない場合は、claude mcp get <name> の表示と手で打ったコマンドを見比べます（claude mcp add でサーバーコマンド前の -- を忘れると別のコマンドが登録されます）。
接続後に効いてくる仕様も2つ。MCP ツールの出力は10,000トークンで警告、既定25,000トークンで打ち切り（MAX_MCP_OUTPUT_TOKENS で上限変更）なので、DB から巨大な結果を引くと切れます。クエリ側で絞ってください。もうひとつ、メイン会話の MCP ツール呼び出しが2分を超えると自動的にバックグラウンドタスクへ移り（v2.1.212 以降）、結果は後から通知で届きます。「待っているのに返ってこない」ように見えるときは /tasks を確認します。stdio サーバーはローカルプロセスなので切断後に自動再接続されず、/mcp から手で繋ぎ直します。MCP の設定の考え方全体はClaude Code MCP実践ガイドを参照してください。
権限・サンドボックス起因で失敗するときの切り分け
「テストコマンドが毎回止められる」「逆に聞かれずに実行された」という相談が増えたのは、既定が変わったからです。Permission modes によれば、Pro / Max / Team プランでは v2.1.228 以降、ターミナルの新規セッションの組み込み既定が auto モード（分類器が安全性を判定し原則すべて実行）です。モード値 default は UI 上「Manual」で、v2.1.200 以降は manual という別名でも指定できます。
セッションがどのモードで始まるかは、次の優先順で決まります。
--permission-modeフラグ、または--dangerously-skip-permissions- 設定ファイルの
permissions.defaultMode。ただし.claude/settings.json/.claude/settings.local.json（プロジェクト側）に書いた"auto"と"bypassPermissions"は効かない。autoを既定にしたいなら~/.claude/settings.jsonに書く - 組み込みの既定（プラン・実行環境で決まる）
# 調査だけさせたい：読み取りと分類器承認のコマンドのみ
claude --permission-mode plan
# 全部確認しながら進めたい
claude --permission-mode manual
# 権限まわりの切り分け用に、有効な allow/deny ルールを見る
/permissionsここで覚えておきたい原則は「deny ルールはどのモードでも効く（bypassPermissions でも）」「allow ルールは bypassPermissions では意味がない」「Bash(rm *) のような接頭辞ルールはコマンド文字列に対する字面一致であって、/bin/rm や find -delete は止められない」の3つ。確実に止めたいものは PreToolUse hook かサンドボックスで守ります。--dangerously-skip-permissions は root や sudo では拒否されるので、コンテナで無人実行するなら非 root ユーザーで動かします。
auto モード特有のエラーもあります。<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. は分類器側の一時的な失敗で、数秒待って再試行すれば通ることがほとんどです（作業ディレクトリ内の読み取り・検索・編集は分類器を通らず動き続けます）。Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details なら再試行するか claude --debug でログを見ます。
サンドボックスで落ちるコマンドの典型
サンドボックス外では通るコマンドが中で失敗する定番は、Sandboxing の Troubleshooting にまとまっています。
| 症状 | 対処 |
|---|---|
| host-not-allowed でネットワークが拒否される | プロンプトで許可すると、そのホストが許可リストに追加されて次回から中で動く |
jest が固まる／落ちる |
watchman が非互換。jest --no-watchman |
gh・gcloud・terraform が macOS で TLS 検証に失敗 |
Go 製 CLI の既知問題。excludedCommands に入れてサンドボックス外で実行 |
docker が失敗 |
非互換。docker * を excludedCommands へ |
git merge / git checkout が unable to unlink old |
保護パスや denyWrite 配下の置換で失敗。Claude がサンドボックス外での再実行を提案するので承認するか、別ターミナルで自分が実行 |
サンドボックス違反はコマンド結果に「どのパス／ホストが拒否されたか」として返るので、Claude はそれを見て dangerouslyDisableSandbox 付きで再実行を提案することがあります。再実行は通常の権限フロー（Manual なら確認、auto なら分類器判定）を通ります。この抜け道自体を塞ぐなら "allowUnsandboxedCommands": false。地味な罠は $TMPDIR で、サンドボックス内のコマンドはセッション専用の一時ディレクトリを向くため、一時ファイルを共有するなら作業ディレクトリ配下に書きます。権限設計の全体像はClaude Code権限設計ガイド、サンドボックスの設定手順はClaude Codeサンドボックスで安全に自動実行にまとめています。
コンテキスト不足・肥大化の切り分け
長いデバッグセッションで必ず当たる壁がコンテキストです。対話中に Context limit reached · /compact or /clear to continue と出たら、会話と添付ファイルがモデルのコンテキストウィンドウを超えています（-p の出力や記録ファイルでは Prompt is too long）。公式 Error reference の対処を、デバッグ作業向けに並べ替えるとこうなります。
/contextで何が食っているかを見る（システムプロンプト・ツール定義・MCP ツール・メモリファイル・会話）。超過している場合は先頭にContext exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.のような警告行が出る。- 多ターンの会話なら
/compact。焦点を指示できるので、/compact keep only the plan and the diffのように「計画と差分だけ残せ」と書くと、巨大なログ出力を落としつつ調査の骨格を保てる。 - 使っていない MCP サーバーを
/mcp disable <name>で外す。ツール定義がコンテキストから消える。サブエージェントは親の MCP ツール定義をすべて引き継ぐので、委譲する前に外しておくと効果が大きい。 - それでも無理なら
/clear。前の会話は残っていて/resumeで戻れる。
やっかいなのが自動コンパクションのループです。Autocompact is thrashing: the context refilled to the limit... は、圧縮には成功したのに直後のファイル読み込みやツール出力がまた上限まで埋める、を数回繰り返した状態で、Claude Code は無駄な API 呼び出しを避けるために自動リトライを止めます。公式の復旧手順は4つ：巨大ファイルを行範囲や関数単位で読ませる／大きな出力を落とす焦点付き /compact／大きなファイルを扱う作業をサブエージェントに移す／不要なら /clear。デバッグでは「ログファイルを丸ごと Read させた」が原因の大半なので、grep -n で行番号を当ててから該当範囲だけ読ませます。
関連して、/compact が Not enough messages to compact. を返すのは1回の巨大な貼り付けで埋まった状態（貼る量を減らして始め直す）、Error during compaction: Conversation too long. は要約を置く空きすら無い状態で、Esc を2回押して数メッセージ戻ってから再度 /compact するのが公式の手順です。
「重い・固まる」系は別の話で、CPU・メモリが高いときの公式手順は、/compact をこまめに使う・大きなタスクの間で再起動する・ビルド成果物を .gitignore に入れる・claude --safe-mode でプラグイン/MCP/hook を切り分ける、の4つです。検索や @file がファイルを見つけないときは同梱の ripgrep が動いていない可能性があり、システムの rg を入れて USE_BUILTIN_RIPGREP=0 を設定し、claude doctor の Search 行で確認します。
よくあるエラーメッセージ別の対処早見表
ここでは、公式 Error reference から「デバッグ作業中に実際に遭遇しやすいもの」だけを抜き出して並べます。文言は 2026年9月時点の公式表記です。
| 表示 | 意味 | 対処 |
|---|---|---|
API Error: 500 Internal server error |
API 側の一時的な障害。あなたのプロンプトや設定は原因ではない | status.claude.com を確認して1分待ち、try again と打つ（元のメッセージは会話に残っている）。続くなら /feedback |
API Error: Repeated 529 Overloaded errors |
全ユーザー横断で容量逼迫。使用量上限とは無関係 | 数分待つか、/model で別モデルへ。容量はモデル別 |
Request timed out |
既定10分の要求タイムアウト超過 | 再試行、作業を小さく分ける、遅い回線なら API_TIMEOUT_MS（ミリ秒）を上げる |
Context limit reached · /compact or /clear to continue |
コンテキスト超過 | 前節の手順 |
Autocompact is thrashing: ... |
自動圧縮の直後に再び上限まで埋まるループ | 巨大ファイルを分割して読む／焦点付き /compact／サブエージェント化／/clear |
No conversation found with session ID: ... |
指定IDの記録が無い（誤記・保持期限（既定30日）切れ・別マシン・重複コピー） | claude --resume のピッカーで Ctrl+A を押して全プロジェクトから探す |
Failed to resume the conversation. |
選んだセッションの記録を読めなかった（終了コード1） | 表示されたとおり claude --resume <session-id> で再試行、だめなら新規セッション |
Error: Claude Code process exited with code 1（VS Code / SDK） |
ラッパーが見た終了コードだけで、本当の原因は別 | 同じプロジェクトでターミナルから claude を起動して本物のエラーを見る。claude doctor も実行 |
pkill: refusing to run — this pattern matches the Claude CLI process |
Bash ツール内の pkill -f が Claude Code 自身に当たった（Linux のみ・v2.1.214 以降） |
パターンを絞るか pkill -P $$ ... で自分の子プロセスに限定 |
<hook name> hook error（非ブロッキング） |
hook が非0終了、または JSON の検証／パースに失敗。動作は進んでいる | hooks の節。JSON は文字列連結でなく jq などで組み立てる |
表にないメッセージは、Claude Code に「このエラーの公式ドキュメントの説明は？」と聞くのが早いです。Claude Code は自分のドキュメントへ組み込みでアクセスできる、と公式 Troubleshooting にも書かれています。
チームの調査手順を CLAUDE.md に固定する
個人で速くなったら、次はチームで再現性を持たせます。デバッグの定石（どのログを見るか、再現環境の立ち上げ方、貼ってはいけない情報）を CLAUDE.md に書いておくと、Claude Code が毎回その前提で調査してくれます。
# デバッグの進め方（このリポジトリの約束）
- 例外調査はまず src/ 配下の自前コード行から見る
- 再現は scripts/repro.ts に最小ケースを書いてから直す
- 修正には必ず回帰テストを add する
- ログを読むときは grep で行番号を当ててから、該当範囲だけ Read する
- ログに含めてはいけないもの: トークン, Cookie, 個人情報, 本番URL
- 本番ログを貼るときは値をマスクしてから渡すCLAUDE.md はプロジェクトメモリとして Claude Code が自動で読み込む仕組みで、置き場所や記法は公式のHow Claude remembers your projectに整理されています。2026年版で押さえておきたい公式の注意が2つあります。ひとつは、サブディレクトリの CLAUDE.md はセッション開始時ではなく、Claude がそのディレクトリのファイルを Read ツールで読んだときに読み込まれること（書き込みや新規作成では読まれない）。「効いていない」ように見える正体はたいていこれです。もうひとつは、CLAUDE.md は「うちではこうする」を伝えるもので、絶対に起きてはいけないことの保証は permissions と hooks で作るという役割分担。「本番URLを叩くな」を CLAUDE.md に書くだけでは保証にならないので、deny ルールや PreToolUse hook で止めます。設計の考え方はClaude Code 実践テクニック完全ガイドとCLAUDE.md設計・運用ガイドでも触れています。
よくある失敗パターンと対策
最後に、実際にやらかしがちな落とし穴を ❌→⭕ で整理します。
❌ AI の原因推定をそのまま信じて修正する
⭕ 仮説は必ず再現・ログで裏取りしてから直す。Claude Code が出すのは「確定した原因」ではなく「もっともらしい候補」です。検証なしの修正は、別のバグを生むだけになりがちです。
❌ 再現できないまま「直った気」になる
⭕ 直す前に必ず再現させ、修正後にそれが消えることを確認する。再現できないバグは、修正の成否を判定できません。最小再現を1つ作るのが最短ルートです。
❌ 本番ログをそのまま貼って機密情報を渡す
⭕ トークン・Cookie・個人情報・内部URLはマスクしてから渡す。デバッグ用のログには想像以上に秘密情報が混ざっています。貼る前に値を置換するか、再現に必要な最小限だけ抜き出してください。
❌ いきなり広く修正して原因を曖昧にする
⭕ 1コミット＝1原因に絞る。複数箇所を同時に変えると、何が効いたのか分からなくなり、再発時に追えません。git 差分を小さく保つほど、次の調査が楽になります。
❌ hook を exit 1 で終わらせて「止めたつもり」になる
⭕ ブロックは exit 2 だけ。exit 1 は非ブロッキングのエラーとして動作が進みます。matcher の配列指定・小文字のツール名・~/.claude.json への誤記も同じ「発火しない」症状になるので、/hooks と claude --debug のログで事実を見る。
❌ claude --debug を打ってターミナルを眺め続ける
⭕ --debug はターミナルに出しません。~/.claude/debug/<session-id>.txt を読むか、--debug-file でパスを固定して tail -f する。MCP だけなら --debug=mcp。
❌ 設定が効かない原因をコードのせいにする
⭕ 先に /context で「読み込まれているか」を見る。読み込まれているのに従わないなら書き方（曖昧・矛盾・長すぎ）の問題。読み込まれていないなら場所と優先順位（settings.local.json ＞ settings.json ＞ ユーザー設定）の問題。--safe-mode で消えるなら拡張のどれか。
よくある質問（FAQ）
Claude Code のデバッグログはどこに出ますか？
claude --debug で起動すると ~/.claude/debug/<session-id>.txt に書かれます。ターミナルには表示されません。claude --debug-file <path> で出力先を固定でき、セッション途中なら /debug で記録を開始できます。
/doctor と claude doctor は何が違いますか？
セッション内の /doctor はインストール・設定・拡張・コンテキスト使用量を点検し、修正案を出して確認後に適用できる総合チェックです（別名 /checkup）。シェルから実行する claude doctor はセッションを起動せずに読み取り専用の診断だけを表示します。claude 自体が起動しないときは後者を使います。
MCP サーバーが Connected なのにツールが0件です。どうすれば？
起動はしたもののツール一覧を返していない状態です。/mcp のサーバーメニューから Reconnect を選び、それでも0件なら claude --debug=mcp で起動してデバッグログのサーバー stderr を読みます。相対パス・環境変数の欠落・トークンの空白混入が典型的な原因です。
hooks を設定したのに /hooks に表示されないのはなぜですか？
プロジェクト・ユーザー設定には独立した hooks ファイルが無く、settings.json の hooks キー配下だけが読まれます。~/.claude.json に書いた場合も読まれません。JSON の末尾カンマやコメントも無効化の原因になります。保存後数秒待って /hooks を再実行してください。
ターミナルを閉じてしまった調査は続けられますか？
同じディレクトリで claude --continue を実行すれば最後の対話セッションが再開され、claude --resume で一覧から選べます。claude -p で作ったセッションは一覧に出ないので、セッションIDを控えて claude --resume <session-id> を使います。記録は既定で30日保持されます。
まとめ：当たりは AI、確定は再現で。Claude Code 側は「何が読み込まれたか」から
Claude Code でデバッグが速くなるのは、「直す」工程ではなく「どこが壊れているかを絞る」工程です。エラーとスタックトレースを読ませて候補を出し、再現で裏を取り、git 差分と bisect で犯人を特定し、テストで再発を止める。探索はサブエージェントに切り出し、途中で止めても --continue で戻る。この往復を一緒に回すと、半日かかっていた原因調査が現実的に短くなります。
そして Claude Code 自体がおかしいときは、推測せずに /context → /doctor → claude --debug のログ → --safe-mode の順で「何が実際に読み込まれ、何が起きたか」を見る。hooks は exit 2 と matcher、MCP は claude mcp list の Issue: 行、権限はモードの優先順位と deny ルール、コンテキストは /context と焦点付き /compact──見る場所さえ決まっていれば、切り分けは数分で終わります。
大事なのは、AI の推測を確定情報として扱わないこと。当たりは AI に任せ、確定は必ず自分の手で再現して取る。この一線さえ守れば、デバッグの相棒として十分に頼れます。今日、手元の1件のバグで「エラー貼り付け→仮説3つ→最小再現→修正→回帰テスト」を1周だけ通してみてください。次のバグから、調査の入り方が変わります。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載を7回執筆。Claude Code を使った開発・デバッグの現場知見を発信している。
参考・出典
- Troubleshooting — Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Debug your configuration — Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Common workflows（Fix bugs efficiently・Delegate research to subagents）— Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Hooks reference（Debug hooks・Exit code output）— Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Automate actions with hooks（Limitations and troubleshooting）— Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Connect Claude Code to tools via MCP — Claude Code 公式ドキュメント／Connect to MCP servers（Troubleshooting）（参照日: 2026-09-03）
- CLI reference — Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Permission modes — Claude Code 公式ドキュメント／Sandboxing（Troubleshooting）（参照日: 2026-09-03）
- Manage sessions — Claude Code 公式ドキュメント／Checkpointing（参照日: 2026-09-03）
- Create custom subagents — Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Error reference — Claude Code 公式ドキュメント（参照日: 2026-09-03）
- How Claude remembers your project（CLAUDE.md）— Claude Code 公式ドキュメント（参照日: 2026-09-03）
- Claude Code changelog（v2.1.259・2026年9月2日）（参照日: 2026-09-03）
- Best practices for Claude Code — Claude Code 公式ドキュメント（参照日: 2026-09-03）
