Claude Code /doctorの使い方—fキーで環境を診断して直す

Claude Code の調子がおかしいとき、最初に打つのが /doctor です。v2.1.205 でこのコマンドは診断だけで終わらず、その場で修正までこなすようになりました。/checkup という別名も増えています。

/doctor が見るもの、/status が見るもの

Claude Code には状態を確かめるコマンドが複数あり、どれを打つか迷います。公式ドキュメントの「何か問題がある場合。」セクションが役割を分けています。

/doctor はインストールと設定を検証する

コマンド一覧表での /doctor の説明はこうです。「Claude Code のインストールと設定を診断および検証します。結果はステータスアイコン付きで表示されます」。見る対象は、インストール状態と自動アップデートの可否、settings.json の解析結果、managed settings の不正エントリなど。壊れている箇所をアイコンで並べます。

/status はバージョンと接続性を映す

/status は別物です。公式の説明は「設定インターフェース（ステータスタブ）を開いて、バージョン、モデル、アカウント、および接続性を表示します」。異常を探すのではなく、今の状態を映す窓口。Claude が応答中でも開けるので、長い応答を止めずにモデルや接続を確かめられます。ログインが切れかけていないか、想定どおりのモデルで動いているかを見たいときは /status。設定が壊れていないかを疑うときは /doctor。/doctor が異常検出と修正、/status が現状確認、と役割が逆を向いています。

/debug と /feedback の棲み分け

同じセクションには「/doctor と /debug はインストールとランタイムの問題を診断し、/feedback はセッションコンテキストが添付されたバグを報告します」とあります。診断系が2つ、報告系が1つ。手元で直すのか、Anthropic に送るのかで分かれます。

コマンド	見るもの	その場で直せるか
/status	バージョン・モデル・アカウント・接続性	×（表示のみ）
/doctor（/checkup）	インストールと設定の異常	○（f キー）
/debug	ランタイムの問題	×
/feedback	バグ報告を Anthropic へ送信	×

f キーで診断から修正へ

v2.1.205（2026年7月8日リリース）での中身の変化がここです。従来の /doctor は不調を並べるだけでした。今は並べた問題に f を押すと、Claude が修正に入ります。

診断結果を出してから f を待つ

セッション内で /doctor を打つと、数秒でフラットツリー形式のレポートが出ます。各行の頭にステータスアイコン。正常・警告・異常がひと目で分かります。

> /doctor

Claude Code Setup Checkup                          v2.1.205

Installation
  OK   claude installed at /opt/homebrew/bin/claude
  OK   auto-update available
Configuration
  OK   ~/.claude/settings.json parsed
  WARN 3 unused skills loaded (~4.2k tokens)
  WARN local CLAUDE.md duplicated against checked-in CLAUDE.md
Hooks
  WARN PostToolUse hook averaged 1.8s over the last 20 runs

Press f to let Claude fix the reported issues.

この出力で分かるのは、致命的な故障はなく、コンテキストを食う設定が3件残っている状態。ここで f を押します。

修正は必ず確認をはさむ

f を押しても変更が黙って走ることはありません。公式表の言葉どおり「f を押して Claude に報告された問題を修正させます」で、Claude は修正案を出してから適用の可否を聞いてきます。

Fixing reported issues...

  1. Remove 3 unused skills from ~/.claude/skills/   [apply?]
  2. Dedup local CLAUDE.md (12 duplicated lines)      [apply?]
  3. Disable slow PostToolUse hook                    [apply?]

Approve which changes? (1,2,3 / all / none)

承認した番号だけが適用されます。壊す前に止まる作りなので、f を押しても環境が勝手に書き換わることはありません。all でまとめて通すか、1,3 のように選んで通すかを、その場で決められます。

Applied 3 fixes.
  - Removed 3 unused skills        (-4.2k tokens at startup)
  - Deduped local CLAUDE.md        (-12 lines)
  - Disabled slow PostToolUse hook

Run /context to see the updated breakdown.

適用の結果まで数字で返ります。起動時に積んでいた約4.2kトークンがそのまま浮く計算。何がどれだけ軽くなったかを /context で確かめる導線まで出ます。

/checkup は同じコマンドの別名

/checkup と /doctor は等価です。v2.1.205 で追加されたエイリアスで、打った先の挙動は変わりません。

名前が2つある理由は使うタイミングの違いです。/doctor は不調が出てから駆け込む医者、/checkup は壊れる前に受ける健康診断。トラブル時は /doctor、点検なら /checkup と打ち分けられます。

何が自動で直せるのか

f で直せるのはコードのバグではなく、設定まわりの掃除です。放っておくとコンテキストを削り、応答を鈍らせる類の負債。

コンテキストを食う未使用スキル・MCP・プラグイン

使っていないスキル・MCP・プラグインは、起動のたびに定義がコンテキストへ積まれます。/doctor はこれを検出して整理を提案します。何が窓を埋めているかは Claude Code /contextの読み方 と突き合わせると確認できます。

CLAUDE.md の重複と肥大化

手元の CLAUDE.md とチェックイン済みの CLAUDE.md が同じ行を持つと、同じ指示を二重に読ませることになります。/doctor は重複を排除し、肥大化した root の CLAUDE.md をネストした CLAUDE.md やスキルへ分割する案も出します。1ファイルに全ルールを詰め込んだ状態から、ディレクトリごとに分けた形へ寄せる提案です。

before:
  CLAUDE.md                 (280 lines, all rules in one file)

after:
  CLAUDE.md                 (32 lines, project overview only)
  backend/CLAUDE.md         (Go の規約)
  frontend/CLAUDE.md        (TypeScript の規約)
  .claude/skills/release/   (リリース手順を skill 化)

分割後は、そのディレクトリで作業しているときだけ該当ルールが読まれます。root の CLAUDE.md は毎回全文がコンテキストへ入るため、無関係な規約を抱えたまま膨らませない構えです。運用の考え方は Claude Code memoryとは？CLAUDE.mdとの違い が近いです。

遅い hook と本体アップデート

実行のたびに時間を食う hook は無効化を提案されます。先ほどの診断で出た「PostToolUse hook が直近20回で平均1.8秒」がその例。ツール呼び出しのたびに待たされるので、体感の遅さに直結します。

ほかに、本体を最新版へ更新、auto モードの有効化、頻繁に拒否している読み取り専用コマンドの事前承認まで含みます。毎回 ls や cat を拒否 → 承認とくり返しているなら、/doctor がその履歴を見て allow ルールへ回す提案を出します。確認のクリック回数が減る分、作業が途切れにくくなります。

対象	提案される修正	効いてくる場面
未使用スキル/MCP/プラグイン	読み込みから外す	起動時のトークン削減
CLAUDE.md	重複排除・分割	指示の二重読み込み解消
遅い hook	無効化	ツール実行の待ち短縮
本体バージョン	最新へ更新	既知バグの回避

起動すらしないときは claude doctor

セッションに入れなければ /doctor は打てません。その場合はシェルから直接叩けます。

セッションの外から診断する

claude doctor

Claude Code Setup Checkup                          v2.1.205

Installation
  OK   claude v2.1.205 (up to date)
  ERR  ~/.claude/settings.json: unexpected token at line 14
Configuration
  ERR  managed settings blocked: invalid "permissions" entry

2 errors found. Run `claude doctor` inside a session and press f to fix.

settings.json を手で編集して壊すと、まさにこの unexpected token が出ます。起動に失敗する原因を、Claude Code 本体を立ち上げずに特定できます。

アイコンの読み方

v2.1.205 で表示はフラットツリーに統一されました。行頭のアイコンは正常・警告・異常の3段階。異常が1つでもあれば、まずそこから潰します。警告はコンテキストや速度の負債で、急がなくても効いてくる部類です。

スキルを積みすぎたら棚卸しに使う

壊れてからではなく、定期的に回して設定を軽く保つのが /checkup の使いどころです。スキルやプラグインは足すのは一瞬でも、外すのは忘れがち。棚卸しの起点として使えます。

/context と合わせてコンテキストを見る

スキルや MCP を増やすほど、起動直後に消費するトークンが膨らみます。20個を超えたあたりで /doctor をかけたところ、半年前に試して放置したスキルが未使用として5件並びました。整理の提案を /context の内訳と照らすと、どれを外せば窓が空くかがそのまま見えます。

ここで f を押して未使用分を外すと、次回起動時のトークンがその場で軽くなります。どのスキルが何トークン積んでいるかは /context の読み方 で内訳が取れるので、/doctor の提案と数字で裏を取れます。

壊れてから直すより、点検で先に削る

設定の負債は、放っておいても悪化するだけで自然には減りません。次の対比が分かりやすいはずです。

• アンチパターン: 応答が遅くなってから原因を手探り。hook を1つずつ止めて切り分ける
• OK: 週に一度 /checkup を回し、遅い hook と未使用スキルをまとめて片づける

新しいプラグインを入れた直後に /checkup を回せば、増えた定義がどれだけコンテキストを食うかその場で分かります。

よくある質問

/doctor と /checkup、どちらを打てばいい？

どちらでも同じです。v2.1.205 で /checkup が別名として増えただけで、実体は1つ。トラブル時は /doctor、定期点検は /checkup と気分で選べます。

f を押すと環境が勝手に書き換わる？

いいえ。Claude は修正案を提示し、どれを適用するか聞いてきます。承認した項目だけが反映されるので、意図しない変更は起きません。

settings.json を壊した後も使える？

使えます。セッションに入れないなら、シェルから claude doctor を実行してください。不正なエントリの行番号まで出るので、手で直す当たりがつきます。

まとめ

• /doctor はインストールと設定を診断し、f キーで報告された問題を修正する
• /checkup は v2.1.205 で増えた同じコマンドの別名。挙動は変わらない
• /status は状態表示のみ、/debug はランタイム診断、/feedback はバグ報告と役割が分かれる
• 直せるのは未使用スキル・MCP・プラグインの整理、CLAUDE.md の重複排除と分割、遅い hook の無効化、本体更新
• セッションに入れないときはシェルから claude doctor
• 修正は必ず確認をはさむため、承認した項目だけが適用される