何のためのものか
起動後に起きるパフォーマンス・安定性・検索の問題への対処。「何が悪いか分からない」時間を短くするのが目的なので、覚えるのは順番だけでよい。
触る
- どれに当たるか不明なときは
/doctor。 インストール・設定・拡張・コンテキスト使用量を自動チェックし、確認のうえ適用できる修正を提案する claudeが起動しないときはシェルからclaude doctor- MCP サーバーの状態は
/mcp
入れる
症状から入口を選ぶ。
| 症状 | まずやること |
|---|---|
| 高 CPU / メモリ、遅い | /compact でコンテキストを減らす、大きなタスクの合間に再起動する |
| 設定が反映されない、hooks が発火しない | 設定のデバッグへ（/doctor で検証エラーを見る） |
| 自分のカスタマイズが怪しい | claude --safe-mode で再起動して切り分ける |
| ハング・フリーズ | Ctrl+C でキャンセル、駄目ならターミナルを閉じて claude --resume |
| 検索がファイルを見つけない | 同梱の ripgrep を疑う |
再起動しても会話は失われない。 同じディレクトリで claude --resume すれば再開できる。
効かせる
原因別の手当てを持っておく。
コンテキストが埋め直される（Autocompact is thrashing）
自動 compact は成功したのに、ファイルやツール出力が直後に何度もコンテキストを埋め直した状態。順に、大きなファイルを行範囲や関数単位で読ませる → 落とす対象を指定して /compact keep only the plan and the diff → 大きなファイルの作業を subagent へ移す → 不要なら /clear。
メモリが下がらない
/heapdump を実行する（コマンドメニューに出ないので全文を入力する）。~/Desktop に heap snapshot と診断 JSON が出て、会話には resident set size や JS heap の内訳が表示される。報告する場合は -diagnostics.json のみを GitHub issue に添付する。
検索が当たらない
同梱の ripgrep が動いていない可能性がある。プラットフォームの ripgrep を入れて USE_BUILTIN_RIPGREP を 0 にし、claude doctor の Search 行が OK (bundled) ではなくシステム ripgrep のパスを示すことを確認する。
落とし穴
Not enough messages to compact.は失敗ではない。 要約するにはターン数が少なすぎるという意味で、大きな貼り付け 1 回でコンテキストが埋まった場合にも起こる- 大きなテーブルの「切れ」は表示だけ。 200 行を超える Markdown テーブルは先頭 200 行の表示になるが、テーブル全体は会話に残り
/copyは全行をコピーする - WSL で検索が不完全でも
claude doctorは Search を OK と表示する。 ファイルシステムをまたぐ読み取り性能の問題なので、範囲を狭めるかプロジェクトを/home/に置く - エディタの統合ターミナルで文字化けするときは GPU レンダラーが原因のことが多い。
/terminal-setupがterminal.integrated.gpuAccelerationを"off"にする - インストールやログインの問題はこのページの範囲外。別ページ（Troubleshoot installation and login / Error reference）を見る