CLAUDE.md に書いた指示を Claude が無視する、設定したはずのフックや MCP サーバーが出てこない。こうしたとき原因の多くは「ファイルが読み込まれていない」「想定と違う場所から読み込まれている」「別のファイルに上書きされている」のどれかです。この記事では、公式ドキュメント「Debug your configuration」に沿って、Claude Code が実際に何を読み込んだかを /context・/doctor・/hooks・/mcp などで確かめ、--safe-mode やクリーンな設定ディレクトリで原因を絞り込む手順を説明します。インストールやログイン、接続の問題は対象外で、公式は別ページ「Troubleshoot installation and login」を案内しています。
読み込まれた内容を /context で確認する
最初に実行するのは /context です。現在のセッションのコンテキストウィンドウを占めているものを、システムプロンプト、システムツール、MCP ツール、カスタムサブエージェント（それぞれの読み込み元つき）、メモリファイル、スキル、会話のメッセージといった分類ごとに表示します。自分の CLAUDE.md やルール、スキルの説明文がそもそも入っているかをここで確認します。/context のスキル欄には、/skills には出ない同梱スキルも含まれます。
特定の分類を詳しく見たいときは、次の専用コマンドを続けて使います。
| コマンド | 表示する内容 |
|---|---|
/memory | ユーザー・プロジェクトのスコープにあるメモリファイルの場所（エディタで開ける）、自動メモリのフォルダと有効/無効の切り替え |
/skills | プロジェクト・ユーザー・プラグインから読み込まれた利用可能なスキル |
/hooks | 有効になっているフックの設定 |
/mcp | 接続中の MCP サーバーとその状態 |
/permissions | 現在有効な allow / deny ルールを解決した結果 |
/doctor | インストールの状態、無効な設定ファイル、使われていない拡張、同じディレクトリ内のサブエージェント名の重複、コードベースから導ける内容を書いたコミット済み CLAUDE.md などの点検と修正案 |
/debug [issue] | セッションのデバッグログを有効にし、ログと設定ファイルのパスを使って Claude に原因を診断させる |
/status | 有効な設定ソース（管理設定が効いているかを含む） |
メモリファイルが一覧にない場合
/context の内訳に CLAUDE.md が出てこないなら、置き場所が読み込まれる場所と合っているかをCLAUDE.md の読み込み方と照らし合わせます。サブディレクトリの CLAUDE.md はセッション開始時ではなく必要になった時点で読み込まれるため、開始直後の内訳には出ません。
読み込まれているのに従わない場合
/context で読み込みを確認できたのに特定の指示が守られないなら、問題は「読み込まれたか」ではなく「指示の書き方」にある可能性が高い、と公式は説明しています。CLAUDE.md が得意なのは、新しく入ったチームメイトに伝えるような内容（プロジェクトの規約、ビルドコマンド、ファイルの置き場所など）です。指示が複数の意味に取れるほど曖昧なとき、2つのファイルが矛盾した指示を出しているとき、ファイルが長くなって個々のルールへの注意が薄れたときに、守られにくくなります。
なお、CLAUDE.md と権限は役割が違います。CLAUDE.md は「このプロジェクトではこうする」という判断材料を Claude に渡すもので、権限やフックは Claude の判断に関係なく制限を強制するものです。セキュリティの境界や「絶対に起きてはいけないこと」は、指示ではなく権限やフックで保証します。
設定の優先順位と /status・claude doctor
設定は管理（managed）・ユーザー・プロジェクト・ローカルの各スコープからマージされます。管理設定があれば最優先で適用され、残りは近いスコープほど優先されます。設定ドキュメントの優先順位は高い順に次のとおりです。
- 管理設定（
managed-settings.json、MDM、claude.ai のコンソール） - コマンドライン（
claude --settings） - プロジェクトのローカル設定（
.claude/settings.local.json） - 共有プロジェクト設定（
.claude/settings.json） - ユーザー設定（
~/.claude/settings.json）
一部の設定はコマンドラインのフラグや環境変数でも指定でき、これらも上書きの層になります。設定が効いていないように見えるときは、たいてい別のスコープか環境変数に上書きされています。
無効な設定ファイルを探す
ターミナルで claude doctor を実行すると、セッションを始めずに、インストールの状態と設定ファイルの検証エラーなどを読み取り専用で表示します。修正案を出して適用前に確認を求める、より踏み込んだ点検はセッション内の /doctor で行います。
claude doctorどの設定ソースが有効か、管理設定が効いているかはセッション内で /status を実行して確認します。キーごとの扱いは設定と権限の記事も参考になります。
MCP サーバーとフックを確認する
MCP サーバー
/mcp を実行すると、設定されたすべてのサーバーについて接続状態と、現在のプロジェクトで承認済みかどうかが表示されます。定義が正しくてもツールが使えない主な理由は次のとおりです。
- 承認していない:
.mcp.jsonのプロジェクトスコープのサーバーは1回の承認が必要です。確認を閉じてしまった場合は、/mcpから承認するまで無効のままです。 - 起動に失敗している:
/mcpで failed と表示されます。よくある原因はcommandやargsの相対パスで、.mcp.jsonの場所ではなく Claude Code を起動したディレクトリを基準に解決されます。 - 接続済みなのにツールが0個: サーバーは起動したもののツール一覧を返していません。
/mcpで Reconnect を選び、それでも0ならclaude --debug=mcpで起動して、デバッグログ~/.claude/debug/<session-id>.txtでサーバーの標準エラー出力を確認します。
--debug のカテゴリ指定は --debug='mcp,startup' のように = 付きの形でだけ効き、空白区切りで書くとフィルタなしのデバッグモードになります（CLI リファレンスより）。MCP の設定場所はMCP の記事で説明しています。
フックが一覧に出ない
/hooks は現在のセッションに登録されたフックをイベントごとに一覧表示します。定義したフックが出てこないなら、Claude Code が読み込んでいません。次の原因を確認します。
- フックを独立したファイルに書いている。フックは設定ファイルの
"hooks"キーの下に書きます。 matcherの値を配列にしている。対話セッションの開始時とclaude doctorで無効な設定として表示されます。配列がPreToolUseかPermissionRequestの下にあると、そのファイルのほかのフックも読み込まれません。
フックは出るのに動かない
この場合はたいてい matcher が原因です。
- 複数のツール名に一致させるには、1つの文字列の中で
|を使います（例:"Edit|Write"）。v2.1.191 以降は,も同じ意味になりますが、それより前のバージョンではカンマが正規表現として評価されて何にも一致しないため、まだ v2.1.191 未満なら|を使います。 - ツール名の綴りを間違えると、何にも一致しない matcher になり、フックは黙って動きません。
settings.json の編集は、ファイルが安定するまでの短い待ち時間のあと、実行中のセッションに反映されます。セッション開始後にファイルやプロジェクトの .claude/ フォルダ自体を作った場合も再起動は不要です（v2.1.257 より前は、開始後に作った .claude/ フォルダの編集は検出されませんでした）。保存後に /hooks が古い定義のままなら、数秒おいてもう一度 /hooks を実行して表示を更新します。
それでも動かないときは、claude --debug でセッションを始めてツール呼び出しを起こし、評価の様子を見ます。デバッグログには各イベント、照合された matcher、フックの終了コードと出力が記録されます。
--safe-mode とクリーンな設定で切り分ける
まず --safe-mode で起動する
claude --safe-mode は、カスタマイズを無効にした状態でセッションを始めます。無効になるのは次のものです。
CLAUDE.md- スキル、プラグイン、フック
- MCP サーバー
- カスタムコマンドとエージェント
- カスタムの出力スタイル
- カスタムのキーバインド
claude --safe-mode認証、モデル選択、組み込みツール、権限は通常どおり動きます。CLI リファレンスでは、ワークフロー、カスタムテーマ、ステータスライン、LSP サーバー、自動メモリなども読み込まれないと説明されており、組み込みツールまで絞る --bare とは別物です。safe mode で問題が消えれば、原因は無効にしたもののどれかに絞れたので、前の2章の確認方法でひとつずつ調べます。
safe mode でも、組織の管理フックと管理設定のポリシーは適用されます。一方、管理プラグイン、管理スキル、管理 CLAUDE.md、管理 MCP サーバーは無効になります。
何も読み込まないセッションと比べる
safe mode でも問題が残る場合や、設定そのものが疑わしい場合は、普段の設定を何も読み込まないセッションと比べます。CLAUDE_CONFIG_DIR 環境変数を空のディレクトリに向けて ~/.claude 配下をすべて迂回し、.claude フォルダ・.mcp.json・CLAUDE.md のないディレクトリから起動してプロジェクトの設定も外します。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeこのセッションにはユーザー・プロジェクトの設定、フック、MCP サーバー、プラグイン、メモリがありません。初回起動ではテーマ選択から始まる初回セットアップ画面が出ます。これが出れば、クリーンな設定ディレクトリが使われている証拠です。同じディレクトリでの2回目以降は、オンボーディングの状態がそこに保存されるので画面は出ません。注意点は2つです。
- 組織が管理設定を配布している場合は、ここでも適用されます。MDM プロファイル、レジストリのポリシー、
managed-settings.jsonは設定ディレクトリの外から読まれ、サーバー管理設定も認証後に改めて取得されます。 - ログインし直しを求められます。
ここで問題が消えれば、原因は普段の ~/.claude かプロジェクトの .claude のファイルにあります。ファイルを一時ディレクトリにコピーしたり、プロジェクトから起動したりして、ひとつずつ戻しながら特定します。クリーンなセッションでも再現するなら、原因はユーザー・プロジェクトの設定の外です。/status で管理設定の有無を確かめ、Claude Code に影響する環境変数がないかを調べてから、トラブルシューティングのページ（動作が重い・検索が効かないときの記事など）に進みます。
よくある原因と対処の一覧
設定まわりの「おかしい」は、置き場所と書式の決まりに起因するものがほとんどです。不具合を疑う前に、公式の一覧で次の点を確認します。
| 症状 | 原因 | 対処 |
|---|---|---|
| フックが動かない | matcher が JSON 配列になっている | 1つの文字列にして | でつなぐ（例: "Edit|Write"） |
| フックが動かない | v2.1.191 より前で , 区切りを使っている | | を使うか、Claude Code を更新する |
| フックが動かない | matcher が小文字（例: "bash"） | 照合は大文字小文字を区別する。ツール名は Bash・Edit・Write・Read |
| フックが動かない | フックを独立したファイルに書いている | プロジェクトやユーザーの設定に独立したフックファイルはない。settings.json の "hooks" に書く（別ファイル hooks/hooks.json を読むのはプラグインだけ） |
| グローバルに書いた権限やフックが無視される | ~/.claude.json に書いている | ~/.claude.json はアプリの状態と UI の切り替え用。permissions・hooks・env は ~/.claude/settings.json に書く |
settings.json の値が効かない | 同じキーが settings.local.json にある | settings.local.json が settings.json より優先され、どちらも ~/.claude/settings.json より優先される |
スキルが /skills に出ない | .claude/skills/name.md のようにファイルで置いている | フォルダにして中に SKILL.md を置く（.claude/skills/name/SKILL.md） |
| スキルは出るが Claude が使わない | frontmatter に disable-model-invocation: true がある、または説明文が依頼の言い方と合っていない | /skills のバッジを確認。「user-only」なら Claude は自分からは使わない |
| サブディレクトリの CLAUDE.md が無視される | サブディレクトリの分はセッション開始時ではなく必要になった時点で読まれる | 読み込みのタイミングを確認する（v2.1.288 より前は Read ツールで読んだときだけ読み込まれた） |
| サブエージェントが CLAUDE.md に従わない | 組み込みの Explore と Plan は CLAUDE.md を読まない。カスタムサブエージェントも omitClaudeMd を設定していれば読まない | Explore・Plan には委任時のプロンプトで指示を繰り返す。omitClaudeMd は外す。重要な指示はエージェントファイルの本文（システムプロンプトになる）に書く |
| セッション終了時の後処理が動かない | SessionEnd フックがない | settings.json に SessionEnd フックを追加する |
.mcp.json のサーバーが読み込まれない | ファイルが .claude/ の中にある、または VS Code の mcp.json のようにトップレベルが servers | リポジトリのルートに .mcp.json を置き、mcpServers キーの下に書く |
settings.json の mcpServers に書いたサーバーが出ない | settings.json は mcpServers キーを読まない | プロジェクト用はルートの .mcp.json、ユーザー用は claude mcp add --scope user で追加する |
| 追加したプロジェクトの MCP サーバーが出ない | 1回だけの承認プロンプトを閉じた | /mcp で状態を見て承認する |
| MCP サーバーが一部のディレクトリから起動しない | command や args が相対パス | ローカルのスクリプトは絶対パスにする。npx や uvx など PATH 上の実行ファイルはそのままでよい |
| MCP サーバーに必要な環境変数が渡らない | サーバーの設定に書いておらず、Claude Code が stdio サーバーに渡す環境（自身の環境から一部の変数を除いたもの）にもない | .mcp.json のサーバーのエントリに env を書く |
Bash(rm *) の deny が /bin/rm や find -delete を止めない | Bash のルールは実行ファイルではなくコマンド文字列そのものに照合される | 確実に止めたいなら PreToolUse フックかサンドボックスを使う |
スキルに絞った確認手順はスキルが動かないときの記事にまとめています。
本記事は Anthropic 公式ドキュメント「Debug your configuration」に基づく非公式の日本語解説で、フラグと優先順位は CLI リファレンスと「Settings files and precedence」でも確認しています（確認日 2026-10-10）。仕様は更新される場合があるため、利用前にDebug your configurationとCLI referenceをご確認ください。