Claude Code の /doctor が診断して直す — 肥大化した設定の健診

スキルもMCPサーバもプラグインも積み上がって、Claude Codeを起動するたびにどれだけコンテキストを食っているのか、正直もう追いきれない。/doctorは、その肥大化を診断して、確認を取ったうえで削るところまで踏み込むコマンドに変わった。

読み取り専用の健康診断だった頃の/doctorを覚えている人ほど、今回の変化に驚くはずだ。放置した古いスキルやCLAUDE.mdの重複が、確認の上でまとめて洗い出される。

何が起きたのか
肥大化した設定に走らせてみる
所見の報告、確認、それから変更
開発者としての実践ポイント
よくある疑問
まとめ

何が起きたのか

Claude Codeの/doctorが、インストール状態を眺めるだけのレポートから、問題を見つけて修正の提案まで出す「診断して直す」コマンドへ進化した。中核の変更が入ったのはv2.1.205、およそ2026-07-08のリリースだ。翌日あたりのv2.1.206では、CLAUDE.mdを削減できる箇所を指摘するチェックが追加された。

あわせて/checkupというエイリアスも用意された。健康診断という語感に寄せた名前で、同じ機能を呼び出す。

診断の対象はざっと次のとおり。インストールの健全性、未使用のスキル・MCPサーバ・プラグインの検出、ローカルCLAUDE.mdとリポジトリにチェックインされた版の重複、コードベースから読み取れる情報を重ねて書いているCLAUDE.md記述、起動を遅くしているフック。コンテキストコストと引き合わせて「これは払うだけの価値があるか」を問う視点が入っているのが今回の勘どころだ。

これまでの/doctorは、バージョンやパスの整合を並べて終わりだった。何が壊れているかは教えてくれても、直すのは全部こちらの仕事だった。今回の版は、壊れている箇所と余っている箇所の両方を挙げ、修正案を添えて「やるか?」まで持ってくる。健康診断で数値を見せられて終わりだったのが、その場で処方箋まで書いてもらえるようになった、くらいの変化だと思っている。

肥大化した設定に走らせてみる

手元の環境も、スキルが数十本、MCPが数個、プラグインもいくつか、という典型的な「盛りすぎ」に傾きやすい。ここで/doctorを呼ぶとどうなるか。

/doctor
# エイリアスでも同じ
/checkup

返ってくる所見は、こんな見え方になる（擬似出力）。

Claude Code Doctor — checkup report

[install]   ok   version 2.1.206, node 22.x
[skills]    warn 3 skills loaded but never invoked this month
                 - legacy-scraper  (~1.8k tokens/session)
                 - old-linter      (~1.2k tokens/session)
[mcp]       warn 1 server connected, 0 tool calls in 30 days
                 - image-gen       (startup +420ms)
[plugins]   warn 2 plugins enabled, no recent usage
[CLAUDE.md] warn local file duplicates 14 lines of checked-in version
            info 6 lines derivable from package.json / tsconfig
[hooks]     warn SessionStart hook averaged 2.3s over last 20 runs

Proposed changes: 5   Apply? this will ask before each edit [y/N]

ポイントは最終行だ。所見を並べた時点では、何も変更していない。トークン消費の見積もりまで添えて「これだけ無駄がある」と示し、修正するかどうかは人間に委ねる。

例えばここに挙がった未使用スキルを数本と休眠MCPを1個外すと、起動時のシステムプロンプトはそのぶん軽くなる。1つあたり毎回数kトークン程度で、単発では誤差のようなものだ。ただ、これが1セッションごと、1日に何十回と積み上がると、モデルが実際の作業に回せる余白がじわりと広がる。肥大した設定は、動かなくなる形では壊れない。静かにコンテキストを食い続けて、じわじわ効率を削るのが厄介なところだ。

使っていないMCPを1個外すと何が起きるか、もう少し具体で見てみる。MCPサーバは接続の時点で、自分が提供するツールの一覧と使い方の説明をシステムプロンプトへ流し込む。一度も呼ばないサーバでも、その説明文は毎回コンテキストに載る。擬似出力に出てきたimage-genなら、ツール定義ぶんのトークンに加えて起動の+420msが毎セッション乗っていた勘定だ。外した後は、この定義文がプロンプトから丸ごと消え、モデルが本題に入る前に読む前置きが短くなる。1回の削減は小さくても、消えるのは接続のたびに毎回で、しかもツール数の多いサーバほど効く。

所見の報告、確認、それから変更

この設計が今回いちばん安心できるところだと筆者は感じている。/doctorは勝手に設定を書き換えない。未使用と判定したスキルを見つけても、まず報告し、適用するかを尋ね、承諾を得てから手を入れる。

診断ツールが自動で「掃除」までやってしまうと、たまにしか使わないが手放したくないスキルまで巻き込まれかねない。月イチのリリース作業でしか呼ばないMCPが「30日間ゼロ回」と判定されて消される、といった事故は誰でも想像できる。所見を先に見せて人間に決めさせる作りなら、その手の取り違えを踏まずに済む。

CLAUDE.mdの扱いが分かりやすい。ローカルのCLAUDE.mdとチェックイン版が同じ行を持っていれば、その重複を指摘して片方に寄せる提案を出す。さらにv2.1.206からは、package.jsonやビルド設定を読めば分かる内容をCLAUDE.mdにわざわざ書いている箇所を「これは導出できるので削れる」と教えてくれる。設定ファイルの肥大は、こういう「二重に書いた事実」がじわじわ効いて起きる。

具体的に想像してほしい。CLAUDE.mdに「このプロジェクトはTypeScript、ビルドはvite、テストはvitest」と書いてあるとする。これはpackage.jsonの依存関係とvite.config.tsを見れば分かる情報で、Claudeは毎セッション自力で読める。その3行をCLAUDE.mdから外せば、起動のたびに読み込むトークンがそのぶん軽くなる。1回あたりの節約は小さくても、1日に何十回も起動するなら積算は無視できない。

遅いフックの警告も地味に効く。SessionStartのフックが毎回2秒かかっていると分かれば、見直す動機になる。フックは目に見えないところで走るので、こういう計測がないと放置されがちだ。20回の平均で示してくれるから、たまたま遅かったのか常態なのかも判断がつく。

同じ週には、別の防御も入った。auto modeがトランスクリプトの改ざんをブロックするようになった変更（v2.1.205）だ。会話ログを書き換えて挙動を誘導する手口を塞ぐもので、自動運転寄りの使い方をする人ほど効いてくる。設定の掃除とは別の話題だが、同じリリースに安全側の変更がまとまって入ったのは覚えておいて損はない。

ひとつ注意を添えておく。文脈から解決できない変数を含むrm -rfの実行前に確認を挟むガードも存在するが、これの初出はおそらく6月下旬あたりで、今回の週とは別系統の可能性が高い。同じ週の変更として紹介している記事を見かけたら、そこは鵜呑みにせず導入時期を確かめてほしい。筆者も日付は要確認の扱いにしている。

開発者としての実践ポイント

まず素の/doctor（または/checkup）を走らせ、所見だけ受け取る。この段階では設定は変わらないので、気軽に現状把握に使える。
未使用スキル・MCP・プラグインの警告は、トークン見積もりと突き合わせて判断する。月に一度も呼んでいない機能は、外す候補として真剣に検討する。
CLAUDE.mdの重複と導出可能記述の指摘は、承諾する前に差分を読む。プロジェクト固有の意図が込められた行を、機械的に消さないよう気をつける。
遅いフックの警告が出たら、SessionStart系の処理を軽くする。起動のたびに払うコストなので、効果が積み上がる。
変更適用は一括で任せず、編集ごとの確認を有効にして一つずつ承諾する。安全側の運用が結局いちばん速い。
診断は月に一度など間隔を決めて回す。設定は放っておくと増える一方なので、定期健診として習慣にしておくと肥大に気づきやすい。

複数のClaude Codeセッションやエージェントを束ねて運用しているなら、複数AIエージェントを1画面に統合するMission Controlとあわせて読むと、設定の掃除とオーケストレーションの両輪が見えてくる。

よくある疑問

勝手に設定を消されないか。 消されない。/doctorは所見を並べたあとで「適用するか」を尋ね、承諾した項目だけ、それも編集ごとに確認を挟んで手を入れる。黙って書き換える動作は組み込まれていない。所見の一覧を眺めるだけで、何も適用せずに抜けてもいい。

適用した変更は元に戻せるか。 /doctorが触るのは設定ファイルそのものだ。プロジェクトをgitで管理していれば、適用後にgit diffで何が変わったかを見て、気に入らなければ戻せる。心配なら、承諾する前に消える予定の行を自分の目で一度読んでおくと安全だ。CLAUDE.mdの導出可能記述の削減は特に、意図が込もった行を巻き込みやすいので差分の確認をすすめる。

どのくらいの頻度で回せばいいか。 筆者は月に一度を目安にしている。設定は使ううちに増える一方で、週次で回すほどの変化は出ない。新しいスキルやMCPをまとめて入れた直後と、月初の棚卸しのタイミングで走らせると、増えた荷物に気づきやすい。