「昨日まで動いていた Claude Code が、今朝から急にエッジケースで挙動が変わった」— こういうときに限って、再現ログを集める前に環境の方に原因があるパターンに何度かぶつかりました。そしてその多くは、/doctor コマンドを最初に叩いていれば数分で切り分けが終わっていました。
この記事は /doctor の出力項目を読み解きながら、実地で「これを見ていれば防げた」と思った典型的なつまずきポイントを振り返るメモです。コマンドの存在自体は公式ドキュメントやヘルプで目にした方も多いと思いますが、出力のどこを真剣に見るべきかは、意外と共有されていないように感じました。
/doctor が報告してくれる4種類の情報
/doctor は Claude Code のインタラクティブセッション中に打つ内部コマンドです。報告される情報はざっくり4系統に分かれます。
- 実行環境: Node バージョン・OS・
claude-codeの CLI バージョン・認証済みアカウント - 設定ファイルのマージ状態: ユーザー設定（
~/.claude/settings.json）、プロジェクト設定（.claude/settings.json）、ローカルオーバーライド（.claude/settings.local.json）がどの優先順でどう統合されているか - MCP サーバーの接続状態: 登録されているサーバー名、起動コマンド、接続成功・失敗・タイムアウトの別
- 権限モード: Plan mode / Accept Edits / Default のどれで起動しているか、
allowedToolsの状態
この4系統のうちどこで「予想と違う値」が出ているかを特定できれば、原因の8割は絞り込めるという手応えがあります。
実際に助けられたシナリオ1: 設定が別プロジェクトで上書きされていた
たとえば pnpm を使いたいのに、セッションを開くと毎回 npm install が走る、というケースがありました。調べてみると、ホームディレクトリで別件のプロジェクトを触ったときに書き込んだ ~/.claude/settings.json の env セクションが残っていて、NPM_CLIENT=npm が全プロジェクトに伝播していました。
# セッションを起動して /doctor を叩き、env の解決結果を確認する
claude
# プロンプトに入ったら
/doctor/doctor の出力には「どの設定ファイルの、どのキーが、最終値として採用されたか」が行単位で出ます。ここで env.NPM_CLIENT の出典が ~/.claude/settings.json になっていれば、ユーザー設定を疑えばよいと分かります。期待される出力の抜粋は次のようになります。
Settings merge:
~/.claude/settings.json env.NPM_CLIENT = "npm" (source)
./.claude/settings.json (no entry)
./.claude/settings.local.json (no entry)
→ effective env.NPM_CLIENT = "npm"
「プロジェクト設定で pnpm にしたつもりだったのに」というときは、プロジェクトの settings.json でキーを明示的に上書きする必要があります。マージ規則は下のレイヤーが勝つ設計なので、プロジェクト側で再宣言するのが素直な解決策です。詳しくは Claude Code settings.json 完全ガイド にまとめています。
実際に助けられたシナリオ2: MCP サーバーが静かに失敗していた
MCP サーバーは設定ミスをしても Claude Code の起動自体は成功するので、気づきにくい失敗モードだと私は感じています。たとえば .claude/mcp.json に書いた Python 製のカスタムサーバーが仮想環境のパスを解決できず、起動直後に落ちていた、という事故に私自身何度か遭いました。
/doctor の MCP セクションは、各サーバーの「接続ステータス」「最初のハンドシェイクまでにかかった時間」「標準エラーに出た行の末尾1〜2行」を見せてくれます。典型的にはこう出ます。
MCP servers:
filesystem ● connected (0.12s)
github ● connected (0.31s)
my-python-agent ✕ failed ModuleNotFoundError: No module named 'agent_core'
notion ⚠ timeout (>10s; still trying)
failed と timeout のどちらに倒れているかで、打つ手は大きく違います。failed はほぼ確実にコマンド自体の失敗なので、claude mcp test my-python-agent を単体で走らせて直接のエラーを見に行きます。timeout は環境変数やネットワーク許可の問題であることが多く、一度落ち着いてプロセスを手で起動してみると原因が見えます。
MCP サーバーの起動自体は問題ないのにフックが動かないときは、/doctor で権限モードを確認した後、Claude Code Hooks が発火しないときのトラブルシューティング の順序に沿って絞り込むとスムーズです。
実際に助けられたシナリオ3: CLI バージョンが古いまま眠っていた
/doctor の一番上のランタイム行は流し読みしがちですが、ここで何度か痛い目を見ました。Node のバージョンがメジャー2つ前のまま、あるいは claude-code を数か月前にグローバルインストールしたきり忘れていた、というケースです。症状としては「設定を直しても直らない」「フックの挙動が仕様と違う」と見えるので、設定ファイル側を掘ってしまうと時間を溶かします。
Runtime:
OS macOS 15.3 (arm64)
Node v18.20.2 (npm 10.5.0)
claude-code v2.0.12 (released 2026-01-09) ⚠ 4 minor versions behind
authenticated you@example.com (workspace: personal)
CLI 行に「behind」の注記が出ていたら、私はそれを赤信号として扱っています。この半年の大きな挙動変更（権限モードのデフォルト、MCP の起動順序まわり）は、半年前の設定で組んだ自動化に効いてくることが多いためです。npm install -g @anthropic-ai/claude-code@latest（お使いのパッケージマネージャーに合わせて）を先に回しておくだけで、トラブルシューティングが一気に進むことがあります。
実際に助けられたシナリオ4: 権限モードの取り違え
「Edit が勝手に走って困る」と相談されて /doctor を見たところ、デフォルトではなく Accept Edits モードで起動していた、というのは意外と多いパターンです。ショートカット経由の起動設定に --permission-mode acceptEdits が残っていた、あるいはシェルのエイリアスに仕込まれていたという物理的な原因が大半でした。
Permission mode: acceptEdits
allowedTools: Read, Edit, Write, Bash(git:*)
denyTools: -
source: command-line flag (--permission-mode acceptEdits)
source まで出してくれるのが /doctor のありがたいところで、「設定ファイルじゃなくて起動コマンドのフラグで上書きされている」と1行で分かります。記憶にないフラグが出ていたら、起動スクリプト・エディタ統合（VS Code 拡張の設定欄など）・シェルのエイリアスを順番に確認していきます。
/doctor の出力をそのまま Claude に渡すという手
自分の目で見てもピンと来ないときは、出力をそのまま Claude に貼って「これは何を意味するか、どこから直すべきか」と聞くのが私の最終手段です。Claude Code 自身がエージェントとして動いているので、会話の流れで「では PowerShell ツール側の設定を当ててみますか」と提案してくれることもあります。関連する Windows 環境固有の落とし穴は Windows で PowerShell ツールに切り替える実用メモ にまとめてありますので、症状に心当たりがある方は先にあちらをご覧ください。
/doctor はログを残す性質のコマンドではないため、後日の再現のために出力をテキストファイルに保存しておくと、サポートに問い合わせるときや自分で数日後に見返すときに助かります。
# tee で画面表示しつつログに残す方法（macOS / Linux）
claude 2>&1 | tee ~/.claude/logs/session-$(date +%Y%m%d-%H%M).log上のワンライナーはログが溜まりすぎるので、/doctor を叩いたあとにセッションを抜ける、という軽い使い方で十分だと考えています。重要なのは「環境をいじった日に /doctor の断面を1つ残しておく」ことで、差分を見ることで次のトラブル解決が早くなります。
最初に試す順番として定着させる
ここまで振り返ってみて、Claude Code でつまずいたときに最初に打つべきコマンドは /doctor だと言い切ってよいのではないでしょうか。スタックトレースを読む前に環境側を1分で点検できるからで、これだけで原因が特定できなくても、絞り込みの手がかりは確実に残ります。
実作業での導線として、次の3ステップを「ほぼ条件反射」で回せるようにしておくと、急なトラブルでも慌てずに済みます。
- セッションに入ったら
/doctorを叩いて4系統を眺める - MCP の
failed/timeoutがあれば、原因種別に応じて手で確認 - 設定ファイルのマージ結果が予想と違うなら、プロジェクトの
settings.jsonで上書き
今日すぐにできる一歩としては、普段使っているシェルエイリアスやスクリプトから claude を起動して、/doctor の出力を一度きちんと読んでみることをおすすめします。予想通りの設定になっているはずが、意外なレイヤーから混入している値が見つかることがあります。より踏み込んだ設定の読み解き方については Claude Code settings.json 完全ガイド が入り口として役立ちますし、Bash ツール側で詰まる症状には Claude Code の Bash 実行エラー対処ガイド が具体的で参考になります。
設定トラブルの切り分け