Claude Codeは、ターミナルから対話的にコードの読み書きやリファクタリング、テスト実行までを任せられるAIエージェントツールです。個人開発者だけでなく、社内のDX推進担当者やIT管理職が「開発チームの生産性向上ツール」として導入を検討するケースも増えています。しかし実際に使い始めると、MCPサーバーが繋がらない、CLAUDE.mdの指示が反映されない、突然重くなる・フリーズするといった「なぜか動かない」状況に直面することが少なくありません。
こうしたトラブルの多くは、ツール自体の不具合ではなく、設定ファイルの置き場所や読み込みタイミングの誤解、承認手順の見落としといった、原因さえ分かれば数分で解決できるものです。本記事では、Anthropicの公式トラブルシューティングドキュメントをもとに、現場でよく遭遇する問題と具体的な解決手順を整理しました。
まず実行すべき3つの診断コマンド
トラブルが起きたとき、原因を推測する前にまず確認すべきなのが「Claude Codeが実際に何を読み込んでいるか」です。感覚で設定ファイルを疑う前に、以下のコマンドで事実を確認する習慣をつけると解決が早くなります。
/doctor：インストールと設定の健康診断
/doctorはインストール状態、無効な設定ファイル、未使用の拡張機能、重複したサブエージェント名などを自動でチェックし、修正案を提示してくれるコマンドです。ユーザーが確認した上でのみ修正が適用されるため、安心して実行できます。ターミナルから直接claude doctorを実行すると、セッションを開始せずに読み取り専用の診断結果だけを確認することも可能です。
/context：読み込まれた設定を可視化する
/contextは、システムプロンプト、MCPツール、カスタムサブエージェント、メモリファイル、スキルなど、現在のセッションのコンテキストウィンドウに何が入っているかをカテゴリー別に表示します。CLAUDE.mdやスキルが反映されていないと感じたら、まずこのコマンドで「そもそも読み込まれているか」を確認してください。
/mcp・/status：連携状況と設定の優先順位を確認する
/mcpは接続中のMCPサーバーとその状態、プロジェクトごとの承認状況を表示します。/statusは、管理者設定・ユーザー設定・プロジェクト設定・ローカル設定のうちどれが有効になっているかを確認でき、「設定したはずの値が反映されない」ケースの多くはこのスコープの優先順位のズレが原因です。
MCPサーバーが接続できない・ツールが表示されないときの対処法
MCP（Model Context Protocol）サーバーの連携は、外部ツールやデータソースをClaude Codeから利用するための仕組みですが、つまずきやすいポイントでもあります。
よくある3つの原因
1つ目は、プロジェクトスコープのサーバーを.mcp.jsonに定義した際に必要な「初回承認」が完了していないケースです。承認プロンプトを誤って閉じてしまうと、サーバーは無効なままになります。2つ目は、commandやargsに相対パスを指定してしまうケースです。相対パスは.mcp.jsonのあるディレクトリではなく、Claude Codeを起動したディレクトリを基準に解決されるため、起動場所によって失敗することがあります。3つ目は、サーバーが「接続済み」と表示されているのにツール数がゼロのままというケースで、これはサーバー自体は起動しているもののツール一覧を返せていない状態です。
解決手順
まず/mcpでサーバーごとの状態を確認し、承認待ちのものがあれば承認します。相対パスが疑われる場合は、ローカルスクリプトのcommand・argsを絶対パスに書き換えてください（npxやuvxのようにPATH上にある実行コマンドはそのままで問題ありません）。ツール数がゼロのままの場合は、/mcpから「Reconnect」を選び、それでも改善しなければclaude --debug=mcpで起動し、~/.claude/debug/以下に出力されるデバッグログでサーバー側のエラー出力（stderr）を確認します。また、サーバーに渡すはずの環境変数が反映されない場合、Claude Codeがstdioサーバーに渡す環境からは一部の変数が意図的に除外されているため、.mcp.jsonのサーバー定義内で個別にenvを指定する必要がある点にも注意してください。
設定・hooks・CLAUDE.mdが反映されないときの対処法
「設定したのに効かない」という相談の大半は、ファイルの置き場所か記法のミスに起因します。
設定ファイルの置き場所を間違えていないか
意外に多いのが、permissionsやhooks、envを~/.claude.jsonに書いてしまうミスです。このファイルはアプリの状態やUIのトグルを保持するためのもので、これらのキーは~/.claude/settings.jsonに書く必要があります。また、.mcp.jsonは.claude/フォルダの中ではなくリポジトリのルート直下に置く必要があり、置き場所を誤ると読み込まれません。
hooksのmatcherが一致しない典型パターン
hooksが登録されているのに発火しない場合、matcherフィールドの記法を疑ってください。複数のツール名を指定する際はカンマではなく|区切りが基本で（バージョン2.1.191以降はカンマも同様に扱われます）、ツール名はBashやEditのように大文字始まりでなければマッチしません。小文字で書いてしまうと静かに一致しないため、/hooksで登録内容を確認し、claude --debugでイベントごとのマッチ結果を確認するのが確実です。
サブディレクトリのCLAUDE.mdが読み込まれないケース
プロジェクト直下ではないサブディレクトリに置いたCLAUDE.mdは、セッション開始時には読み込まれず、Claude Codeがそのディレクトリ内のファイルをReadツールで読んだタイミングで初めて読み込まれる仕様です。ファイルを作成しただけでは読み込まれない点は誤解しやすいポイントです。
パフォーマンス低下・フリーズへの対処
CPU・メモリ使用量が高いとき
大規模なコードベースを扱う際に負荷が高くなることがあります。/compactでコンテキストを定期的に圧縮する、ビルドディレクトリを.gitignoreに追加する、といった基本対応に加えて、claude --safe-modeで起動し、プラグインやMCPサーバー、hooksが原因かどうかを切り分ける方法が有効です。改善しない場合は/heapdumpでヒープスナップショットを取得できますが、このファイルには会話内容や認証情報が含まれるため、公開のGitHub Issueには診断用JSONファイルのみを添付するよう注意が必要です。
オートコンパクトのスラッシング
「Autocompact is thrashing」というエラーは、コンテキストの自動圧縮は成功しているものの、直後に大きなファイル出力などでコンテキストが再び埋まってしまう状態を指します。大きなファイルは範囲を絞って読む、/compact keep only the plan and the diffのように焦点を絞って圧縮する、あるいは大きな作業をサブエージェントに任せて別のコンテキストウィンドウで実行する、といった対応で回避できます。
インストール・ログインでつまずいたときは
command not found: claudeはPATHが通っていないことが原因であることがほとんどです。インストールスクリプトがsyntax error near unexpected token '<'のようなエラーを返す場合は、ネットワーク経由でHTMLエラーページを取得してしまっている可能性があります。ログインループや403 Forbidden、Amazon BedrockやGoogle CloudのAgent Platform、Microsoft Foundryの認証情報に関するエラーは、いずれも公式のインストール・ログイントラブルシューティングページに個別の対処法がまとまっています。
クリーンな環境で切り分ける
原因の見当がつかない場合は、claude --safe-modeでCLAUDE.md・スキル・プラグイン・hooks・MCPサーバーなどのカスタマイズを全て無効化したセッションを試すのが近道です。それでも再現する場合は、CLAUDE_CONFIG_DIRに空のディレクトリを指定し、.claudeフォルダや.mcp.jsonが存在しない場所から起動することで、ユーザー設定・プロジェクト設定を一切読み込まないまっさらな状態と比較できます。ここで問題が再現しなければ、原因は自分の設定側にあると分かるため、ファイルを1つずつ戻しながら特定していきます。
まとめ：トラブルシューティングの基本フロー
Claude Codeのトラブルは「症状に応じたページを見つける→診断コマンドで事実を確認する→原因を1つずつ切り分ける」という流れで解決できるものがほとんどです。感覚で設定ファイルを疑ったり再インストールを繰り返したりする前に、/doctor・/context・/mcp・/statusをまず実行する習慣をつけることで、多くの問題は自己解決できます。組織として導入する場合も、こうした一次情報ベースの切り分け手順を社内のナレッジとして残しておくと、サポート対応の負荷を大きく減らせるはずです。
