Claude Codeの/doctorとclaude doctor・/checkupの違いと自動修正の範囲

Claude Codeの/doctorは、セッション内で診断して直せるセットアップのチェックアップです。/checkupは同じコマンドの別名で、どちらを打っても動作は変わりません。ターミナルで打つclaude doctorは別の入口で、診断を表示するだけで設定は書き換えません。

/doctorはv2.1.205でただの診断コマンドから生まれ変わりました。インストールの不整合やCLAUDE.mdの肥大化を検出するだけでなく、確認を取ったうえで実際に修正まで行います。

Claude Codeの/doctorで何が変わったか

以前の/doctorは読み取り専用の診断画面でした。問題を一覧表示し、fキーを押すとその報告をClaudeに送って会話で修正を依頼する、という間接的な作りです。v2.1.205以降は違います。/doctor自体がインストール状態・設定ファイル・CLAUDE.mdの中身まで踏み込んで検査し、直せる項目には修正案を提示します。実行だけは自動化されません。結果を先に報告し、変更を加える前に必ず確認を求める仕様です。

/checkupはこの新しい/doctorのエイリアスとして追加されました。どちらを打っても同じチェックアップが起動します。覚えやすい方を使えば十分です。

何を検出し、何を自動修正できるか

チェックアップが扱う範囲は、インストールの健全性からコンテキストの無駄遣いまで広がっています。

表の後半4行は、公式が具体的な提案内容まで書いている項目です。いずれも提案止まりで、承諾しない限りClaude Code側の設定やファイルは変更されません。「まず報告、変更は確認後」という順序は、公式のコマンド一覧でもチェックアップ全体の動作として書かれています。

読み取り専用コマンドの事前承認は、何度も拒否されているコマンドが対象です。手元の許可ルールをまとめて整理したい場合は/fewer-permission-promptsで許可プロンプトを自動整理するのようなコマンド単体の整理手段もあり、役割が異なります。

どの入口を選ぶか:症状から引く

/doctorまわりの入口は3つあり、できることが違います。

分け方の目安は症状です。「起動しない・設定が効かない」ならターミナルのclaude doctor、「CLAUDE.mdやskillが重い」ならセッション内の/doctorを使います。「モデルを替えてから指示が効きにくい」ならprompt-auditです。公式のデバッグガイドも、無効なsettingsファイルを探すときはターミナルのclaude doctor、修正案まで欲しいときはセッション内の/doctorと書き分けています。

claude doctorは実際に何を出力するか

ターミナルから直接claude doctorを実行すると、セッションを始めずに診断だけが表示されます。claude doctor --helpの説明は「現在のディレクトリのsettingsファイルをtrustプロンプトなしで読む」というものでした。v2.1.287で確認しています。

意図的に壊したsettingsファイルでどう見えるかを、一時ディレクトリ(HOMEも差し替え済みで、手元の~/.claudeには触れていません)で試しました。.claude/settings.jsonの中身は閉じていない{ "permissions": だけです。

mkdir -p proj/.claude && echo '{ "permissions": ' > proj/.claude/settings.json
cd proj && claude doctor

出力の主要部分は次のとおりです(パスは省略表記にしてあります)。

Claude Code doctor
 
Running: native (2.1.287)
Platform: darwin-arm64
Auto-updates: enabled
Auto-update channel: latest
 
Invalid settings
- ./proj/.claude/settings.json: Invalid or malformed JSON
 
Remote Control
Remote Control requires a claude.ai subscription. Run claude auth login to sign in with your claude.ai account.
- Not signed in to claude.ai
- Remote Control availability could not be verified (no server response this session)
 
For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

読み取れることが3つあります。

• 壊れたJSONは「Invalid settings」の節にファイルのパスつきで出ます。どのファイルが原因かが、セッションを開く前に分かります
• 実行方式(native)・バージョン・auto-updateのチャンネルが先頭に並びます
• Remote Controlの利用条件は、未サインインだと不足項目が箇条書きで出ます。この節は、インストールの健全性やsettingsの検証とは別の項目として、CLIの診断に含まれます

最後の1行は、フルチェックアップへの案内です。この出力は診断のみで、設定ファイルは書き換えられません。環境によってはこのほかに警告が付き、今回の実行ではPATHに~/.local/binが無いことなどが「warnings」として表示されました。警告の中身は実行する環境に依存するので、実機の画面で見るのが確実です。

「インストールが壊れていないか確認したいだけで、対話は始めたくない」という場面向けの入口です。

インストール方式の判定とskillのコスト

「重複・残留インストール」の検出は、同じ場所にファイルが増えているかどうかより踏み込んだ判定を行います。ネイティブインストール、Homebrew、npmグローバル、mise・asdfのようなバージョンマネージャー経由のインストールは、実体の置き場所もシンボリックリンクの向きも異なります。過去には、mise・asdf管理下のインストールをネイティブインストールと誤って判定する不具合がありました。シンボリックリンクの解決を誤り、Homebrewとnpmグローバルを取り違える不具合もありました。どちらも修正済みです。v2.1.206ではHomebrewのインストールについて、settingsのチャンネルではなくcaskのチャンネルと照合してアップデートを確認するよう直されました。

未使用skillの検出では、単純な「使っていない」判定だけでなく、/doctorを実行すると読み込んでいるskill一覧全体のコンテキストコストの見積もりと、そのうちコストの大きい要因が分かります。一覧が予算を超えたときの警告は、デバッグログに出ます。

予算を引き上げたい場合は、skillListingBudgetFraction設定(0.02なら2%)かSLASH_COMMAND_TOOL_CHAR_BUDGET環境変数で上限を調整します。別の手段として、skillOverridesで個別のskillを"name-only"にすると一覧内の占有量が減ります。どのskillを優先して削るかの判断材料として使えます。

使用回数まで含めて見たいときは、v2.1.261で加わった/skill-doctorが別にあります。こちらは各skillのコンテキストコストと使用頻度を出すコマンドで、/doctorの一部ではありません。

CLAUDE.mdの分割とトリムをどう判断するか

CLAUDE.mdまわりの提案は1種類ではありません。まずローカルのCLAUDE.mdとチェックイン済みのCLAUDE.mdが重複している場合、その統合を提案します。個人用の上書きファイルとリポジトリ管理下のファイルが同じ内容を持っていると、どちらが正なのか分かりにくくなるためです。

v2.1.206からはもう一段踏み込み、チェックイン済みCLAUDE.md自体のトリムを提案するようになりました。判断基準は「Claudeがコードベースから導き出せる内容かどうか」です。ディレクトリ構成の説明、依存関係の一覧、アーキテクチャの概観のような、リポジトリを読めば分かる情報は削減候補になります。逆に、ツールの既定動作と異なる注意点、設計判断の理由、チーム独自の規約は残す対象として区別されます。

トリムはゴールではなく、その先にもう一段の整理が続きます。トリム後も残った「常時読み込みされるべきガイダンス」は、skillや、必要なときだけ読み込まれる入れ子のCLAUDE.mdへ移す提案も行います。

CLAUDE.mdの書き方そのものを見直したい場合はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンも参考になります。

/doctor prompt-auditで指示ファイルの古い記述を洗い出す

v2.1.283で/doctor prompt-audit(/checkup prompt-auditも同じ)が加わりました。通常のチェックアップの代わりに、CLAUDE.md・skill・サブエージェント・commandsなどを点検するモードです。古いモデル向けに書かれた指示、存在しないファイルやコマンドへの参照、互いに矛盾するファイルを探します。結果は修正案つきの報告で返り、ファイルが変わるのは適用を頼んだときだけです。

既定の対象はCLAUDE.md、CLAUDE.local.md、AGENTS.mdです。加えて、.claude/と~/.claude/の下にあるrules・skills・commands・サブエージェント・output stylesも見ます。1つのファイルやディレクトリだけに絞るなら、/doctor prompt-audit .claude/skills/deployのようにパスを渡します。

注意点が1つあります。prompt-auditは同梱の/claude-apiskillを経由して動きます。そのため、skillOverridesでこのskillを切っているときや、disableBundledSkillsが有効なときは使えません。「/doctorはdisableBundledSkillsでも残る」という次節の例外は、prompt-auditには及ばない点に注意が要ります。

v2.1.205前後で何が変わったか

/doctorの性格は一度に変わったわけではなく、段階的に拡張されてきました。

v2.1.205より前の/doctorは、あくまで人間かClaudeが後から手を動かす前提の「レポート係」でした。v2.1.205でその境界が動き、レポートと修正提案が1つのコマンドに統合されています。v2.1.206以降の変更は、この統合済みのチェックアップに検出項目を積み増していく形で進んでいます。

disableBundledSkillsでも/doctorは消えない

/doctorはv2.1.205からbundled skillの一種として実装されています。disableBundledSkillsは、Claude Codeに同梱されたbundled skillをまとめて無効化する設定です。これを設定していても、/doctorだけは例外的にタイプ可能なまま残ります。/code-reviewや/loopのような他のbundled skillが軒並み使えなくなっても、セットアップの問題を診断する手段だけは残しておく、という設計です。環境変数のCLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1でも同じ扱いになります。

それでも/doctor自体を隠したい場合は、DISABLE_DOCTOR_COMMAND環境変数を1にするか、skillOverridesに"doctor": "off"を指定します。DISABLE_DOCTOR_COMMANDは/doctorと/checkupの両方を隠し、ターミナルのclaude doctorには影響しません。v2.1.205より前は、この変数が隠していたのは旧来の診断画面のコマンドでした。公式の説明によると、セッション内で診断を使わせたくない管理配布の環境で役立ちます。

別名の扱いにも癖があります。管理設定(managed settings)や--settingsで渡したファイルでは、checkupのような別名をキーにしたskillOverridesが元のskillにも効きます。ただし、別名経由でできるのはより制限する方向だけで、見える側に戻す設定はできません。skillの可視性そのものをまとめて管理したい場合はClaude Code /skillsコマンドの使い方でトークン数や可視性の切り替えを扱っています。

まとめ

/doctorはv2.1.205を境に、診断だけの画面から、確認を挟んで修正まで進めるチェックアップになりました。コマンド全体の見取り図はClaude Codeスラッシュコマンド一覧にあります。