2026年9月28日時点の結論。「設定したのに効かない」は、ほぼ次の3つのどれかに落ちる。(1) ファイルが読み込まれていない、(2) 読み込まれているが別の場所の値に上書きされている、(3) 読み込まれていて上書きもされていないが、書き方がその機能の想定と違う。最初にやることは原因の推測ではなく /context を打つことだ。/context はいまのセッションのコンテキストウィンドウを占めているものを、システムプロンプト・ツール・MCPツール・サブエージェント・メモリファイル・スキル・会話と分けて出す。ここに目的のファイルが出ていなければ(1)、出ているなら(2)か(3)に進む。この分岐を先にやるかどうかで、調査時間が10分と2時間に分かれる。
公式ドキュメントは、この切り分けのために /context、/doctor、/hooks、/mcp を含む8つの確認コマンドを用意している（Anthropic「Debug your configuration」（2026年9月確認））。以下は、そのコマンド群を「どの順番で、何を見るために打つか」に並べ直したものだ。
この記事の要点
- 最初の1手：
/contextを打つ。CLAUDE.md・ルール・スキルの説明文がそもそも読み込まれているかを、推測ではなく一覧で確認する。 - 読み込まれていた場合：問題は「読み込み」ではなく「書き方」か「上書き」に移る。
/statusで有効な設定ソースを、claude doctorで弾かれた項目を見る。 - フック：
/hooksに出てこないなら読まれていない。出るのに発火しないならmatcherの書式（配列にしない・|で区切る・大文字小文字は区別される）を疑う。 - MCP：
.mcp.jsonはリポジトリ直下に置き、サーバーはmcpServersキーの下に書く。settings.jsonにmcpServersを書いても読まれない。 - スキル：
.claude/skills/name.mdではなく.claude/skills/name/SKILL.mdというフォルダ構成にする。 - 最短の二分探索：
claude --safe-modeで全カスタマイズを切って起動する。直れば原因は自分の設定側、直らなければ設定の外側。 - 対象読者：
CLAUDE.md・settings.json・フック・MCP・スキルを自分で書いている開発者、チームの設定を配っている開発リード。 - 今日やること：症状が出るプロジェクトで
/context→/status→claude doctorの3つを順に打ち、この記事の早見表に当てはめる。
前提｜「効かない」は3つのどれか
同じ「効かない」でも、打つべきコマンドが違う。まず自分の症状をこの3つに割り当てる。
(1) 読み込まれていない：ファイルの置き場所、ファイル名、フォルダ構成が想定と違う。/context・/skills・/hooks・/mcp の一覧に出てこないので、見ればすぐ分かる。
(2) 上書きされている：読み込まれてはいるが、別のスコープの設定ファイル、コマンドライン引数、環境変数が同じキーを設定している。/status と claude doctor で追う。
(3) 書き方が想定と違う：読み込まれていて上書きもされていないのに動かない。フックの matcher、権限ルールの書式、CLAUDE.md の指示の曖昧さがここに入る。
公式ドキュメントの整理
公式ドキュメントも「原因はたいてい、ファイルが読み込まれなかったか、想定と違う場所から読み込まれたか、別のファイルが上書きしたかのいずれか」と整理している（Anthropic「Debug your configuration」（2026年9月確認））。インストールや認証、接続そのものの問題はこの3分類の外なので、別のページを見る。
手順1｜/context で読み込まれたものを一覧で見る
/context は現在のセッションでコンテキストウィンドウを占めているものを、カテゴリ別に出す。システムプロンプト、システムツール、MCPツール、カスタムサブエージェント（それぞれの読み込み元つき）、メモリファイル、スキル、会話メッセージが並ぶ。
ここで確認するのは1点だけだ。目的のファイルが、その一覧に出ているかどうか。出ていなければ、内容をいくら直しても変わらない。
カテゴリ別に深掘りするコマンド
/context で当たりを付けたら、そのカテゴリ専用のコマンドで詳細を見る。
| コマンド | 出るもの |
|---|---|
/memory |
ユーザー・プロジェクト両スコープのメモリファイルの場所。各ファイルをエディタで開ける |
/skills |
プロジェクト・ユーザー・プラグイン由来の利用可能なスキル |
/hooks |
有効なフック設定 |
/mcp |
接続済みMCPサーバーとその状態 |
/permissions |
いま効いている allow / deny ルールの解決結果 |
/doctor |
インストール状態、無効な設定ファイル、未使用の拡張、同一ディレクトリ内の重複サブエージェント名の点検と修正案 |
/debug [issue] |
セッションのデバッグログを有効にし、ログと設定パスから診断させる |
/status |
有効な設定ソース。管理設定が効いているかどうかを含む |
/context のスキル欄にはバンドル済みスキルも含まれる。/skills には出ないものがここには出るので、両方見ておくと差分が分かる。
サブディレクトリのCLAUDE.mdは起動時には読まれない
/context にメモリファイルが出ていない時、よくあるのがこれだ。サブディレクトリの CLAUDE.md は、Claude がそのディレクトリ内のファイルを Read ツールで読んだ時にオンデマンドで読み込まれる。セッション開始時ではないし、そこにファイルを書いたり作ったりした時でもない（Anthropic「How Claude remembers your project」（2026年9月確認））。起動直後に一覧へ出ないのは仕様どおりで、故障ではない。
手順2｜読み込まれていた時は「書き方」を疑う
/context に CLAUDE.md が出ているのに、Claude が特定の指示に従わない。この場合、問題は読み込みではなく指示の書き方にある可能性が高い。
公式ドキュメントは、遵守率が落ちる条件を3つ挙げている。指示が複数の解釈を許すほど曖昧なとき、2つのファイルが矛盾した指示を出しているとき、ファイルが長くなりすぎて個々のルールに注意が向かなくなったときだ。CLAUDE.md が向いているのは、新しく入ったチームメイトに渡すような案内、つまりプロジェクトの慣習、ビルドコマンド、ファイルの置き場所である。
保証が必要なものはCLAUDE.mdに書かない
ここは設計の分かれ目なので押さえておきたい。CLAUDE.md と権限設定は別の問題を解く。CLAUDE.md はプロジェクトの流儀を伝えて良い判断をさせるためのもので、権限とフックは Claude が何を判断しようと関係なく制限を強制するためのものだ。「絶対に起きてはいけない」ことを書く場所は CLAUDE.md ではない。
CLAUDE.md の粒度と分量の設計は、CLAUDE.md設計・運用ガイドで扱っている。
手順3｜/status と claude doctor で設定値を突き合わせる
設定ファイルは管理設定（managed）、ユーザー、プロジェクト、ローカルのスコープをまたいでマージされる。管理設定があればそれが最初に適用され、残りは近いスコープが広いスコープを上書きする。順番はローカル、プロジェクト、ユーザーだ。さらにコマンドラインフラグと環境変数が別の上書き層として働く（Anthropic「Settings files and precedence」（2026年9月確認））。
値が効いていない時は、たいてい別のスコープか環境変数に負けている。
2つの doctor を使い分ける
claude doctor はターミナルからセッションを起動せずに実行し、インストールと設定の診断を読み取り専用で出す。無効な設定ファイルを探すのはこちらが速い。セッションの中で /doctor を実行すると、修正案の提示と適用前の確認までやってくれる。
/status は有効な設定ソースを見せる。ここに出るのは「どのファイルを読んだか」であって「どのキーがどのファイル由来か」ではない点に注意する。キー単位の優先順位は設定ファイルの階層表で追うことになる。階層そのものの整理はsettings.json設定完全ガイドにまとめてある。
~/.claude.json に書いても効かない
見落としやすい罠がこれだ。~/.claude.json はアプリの状態とUIのトグルを持つファイルで、permissions・hooks・env の置き場所ではない。これらは ~/.claude/settings.json に書く。名前が似ているだけの別ファイルで、ここを取り違えると「グローバルに設定したのに全プロジェクトで無視される」という症状になる。
手順4｜フックはmatcherの書式で落ちている
/hooks を実行すると、現在のセッションに登録されている全フックがイベント別に並ぶ。自分が定義したフックがここに出てこないなら、読まれていない。フックは設定ファイルの "hooks" キーの下に書くもので、独立したファイルには書かない。プロジェクトやユーザー設定に「フック専用ファイル」は存在せず、独立した hooks/hooks.json を読むのはプラグインだけだ。
出るのに発火しない時の4つの書式ミス
/hooks に出るのに動かないなら、原因はほぼ matcher にある。
- 配列で書いた：
matcherはスキーマエラーになる。Claude Code は設定エラーの通知を出し、そのユーザー・プロジェクト・ローカル設定ファイル全体を拒否する。claude doctorが検証失敗を報告し、そのファイルのフックは/hooksに1つも出なくなる。 - 区切り文字を間違えた：
matcherは1本の文字列で、複数のツール名は|で区切る。たとえば"Edit|Write"と書く。,も同じ意味で扱われるが、v2.1.191 より前ではカンマが正規表現として評価されて何にも一致しなかったため、そのバージョン以前を使うなら|を使う。 - 小文字で書いた：一致は大文字小文字を区別する。ツール名は
Bash、Edit、Write、Readのように先頭が大文字だ。"bash"は何にも一致しない。 - ツール名を綴り間違えた：一致するものが無いマッチャになり、エラーも出ないまま黙って失敗する。
管理設定の中に配列の matcher があった場合は挙動が変わる。Claude Code はそのファイルの hooks キーごと丸ごと落とすので、そのファイルのフックは全部効かなくなる。ファイルの他の設定は生き残り、落としたキーは claude doctor が一覧に出す。
保存してから反映されるまで
settings.json を編集すると、ファイルが安定するまでの短い待ちを挟んで、動いているセッションにそのまま反映される。セッション開始後に作ったファイルでも、プロジェクトの .claude/ フォルダ自体をセッション中に作った場合でも読み込まれる。再起動は要らない。数秒たっても /hooks が古い定義のままなら、/hooks をもう一度実行して表示を更新する。
それでも発火しないなら、claude --debug で起動してツール呼び出しを起こす。デバッグログに各イベント、照合されたマッチャ、フックの終了コードと出力が記録される。整形・通知系のフック設計そのものはClaude Code Hooks実践ガイドで扱っている。
手順5｜MCPは置き場所とキー名で9割決まる
/mcp を実行すると、設定済みの全サーバー、接続状態、現在のプロジェクトで承認済みかどうかが出る。定義が正しくてもツールが出てこない理由は、公式ドキュメントが挙げているものだけで次のとおりだ。
- 承認プロンプトを閉じた：
.mcp.jsonのプロジェクトスコープのサーバーは一度きりの承認が要る。プロンプトを閉じてしまうと、/mcpから承認するまで無効のままになる。 - 起動に失敗している：
/mcpに failed と出る。commandやargsの相対パスが多い。相対パスは.mcp.jsonの場所ではなく Claude Code を起動したディレクトリを基準に解決されるためだ。ローカルのスクリプトは絶対パスで書く。npxやuvxのようにPATH上にある実行ファイルはそのままでよい。 - 接続済みだがツールが0個：起動はしたがツール一覧を返していない。
/mcpから Reconnect を選ぶ。0のままならclaude --debug=mcpを実行し、~/.claude/debug/<session-id>.txtのデバッグログでサーバーの標準エラー出力を読む。
置き場所とキー名を間違えた時
置き場所の間違いも定番だ。プロジェクトのMCP設定はリポジトリ直下の .mcp.json に置き、サーバーは mcpServers キーの下に書く。.claude/ の中に置いた場合、VS Code の mcp.json のようにトップレベルの servers キーの下に書いた場合、どちらも読み込まれない。settings.json に mcpServers キーを書いても読まれないので、ユーザースコープで持ちたいなら claude mcp add --scope user を使う（Anthropic「Connect Claude Code to tools via MCP」（2026年9月確認））。
環境変数がサーバーに渡らない時は、サーバーの .mcp.json エントリ内に env を書く。ここに書いた値は起動時の環境やワークスペース信頼に依存しない。
手順6｜スキルは「出ない」と「呼ばれない」を分ける
スキルの症状は2つに割れる。分けずに調べると遠回りになる。
/skills に出てこない：ファイルの置き方が違う。.claude/skills/name.md ではなく、フォルダの中に SKILL.md を置く形にする。つまり .claude/skills/name/SKILL.md だ。
/skills に出るのに Claude が呼ばない：スキルのフロントマターに disable-model-invocation: true が入っているか、description が自分の頼み方と噛み合っていない。/skills のバッジを見て、”user-only” ラベルが付いていれば Claude は自分から呼ばない（Anthropic「Extend Claude with skills」（2026年9月確認））。
サブエージェントがCLAUDE.mdを無視する時
サブエージェント側の症状も、原因が決まっている。組み込みの Explore エージェントと Plan エージェントは CLAUDE.md を読まない。カスタムサブエージェントは、定義が omitClaudeMd を設定していない限り、メインの会話と同じように読み込む。
対処は経路で変わる。Explore や Plan なら、委譲するプロンプトの中でその指示を書き直す。omitClaudeMd を設定しているサブエージェントなら、そのフィールドを外す。それ以外のカスタムサブエージェントなら、重要な指示をエージェントファイルの本文に置く。本文はそのエージェントのシステムプロンプトになるからだ（Anthropic「Create custom subagents」（2026年9月確認））。
スキルの作り方そのものはClaude Code Skills作成ガイドにある。
手順7｜–safe-modeとまっさらな設定で二分探索する
ここまでで絞れない時は、当てずっぽうをやめて二分探索に切り替える。
claude --safe-mode は、すべてのカスタマイズを無効にしてセッションを起動する。CLAUDE.md、スキル、プラグイン、フック、MCPサーバー、カスタムコマンドとエージェントが対象だ。認証、モデル選択、組み込みツール、権限は通常どおり動く。セーフモードで症状が消えるなら、原因はその無効化された面のどれかであり、手順1から手順6の的を絞った確認に戻れる。
セーフモードでも組織の管理フックと設定ポリシーは適用されたままになる。管理下のプラグイン、スキル、CLAUDE.md、MCPサーバーはオフになる。
設定そのものが疑わしい時のクリーンセッション
セーフモードでも症状が残る、あるいは設定ファイル自体が怪しいなら、いつもの設定を何も読まないセッションと比べる。CLAUDE_CONFIG_DIR を空のディレクトリに向けて ~/.claude 配下を丸ごと迂回し、.claude フォルダも .mcp.json も CLAUDE.md も無いディレクトリから起動する。
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
このクリーンセッションにはユーザー・プロジェクトの設定、フック、MCPサーバー、プラグイン、メモリが1つも無い。初回起動ではテーマ選択から始まる初回セットアップ画面が出る。出たなら、クリーンな設定ディレクトリが効いている証拠だ。同じディレクトリで2回目以降に起動すると、オンボーディング状態がそこに保存されているので画面は出ない。
2点だけ注意がある。組織が管理設定を配布している場合は、それだけは適用されたままになる。Claude Code は MDM プロファイル、レジストリポリシー、設定ディレクトリの外にある managed-settings.json を読むからだ。もう1つ、ログインを求め直される。
ここで症状が消えるなら、原因は実際の ~/.claude かプロジェクトの .claude のどこかにある。ファイルを一時ディレクトリにコピーする、あるいは自分のプロジェクトから起動するという形で1つずつ戻し、どれが犯人かを特定する。クリーンセッションでも症状が残るなら、原因はユーザー設定とプロジェクト設定の外側にある。/status で管理設定が効いているかを確認し、Claude Code に影響する環境変数を探す。
症状から引く早見表
急いでいる時はここから引く。公式ドキュメントの「よくある原因」表から、設定が効かない系の項目を抜き出したものだ。
| 症状 | 原因 | 直し方 |
|---|---|---|
| フックが一度も発火しない | matcher が文字列ではなくJSON配列 |
1本の文字列にし、複数ツールは \| で区切る（例 "Edit\|Write"） |
| フックが一度も発火しない | matcher の値が小文字（例 "bash"） |
一致は大文字小文字を区別する。Bash・Edit・Write・Read と書く |
| フックが一度も発火しない | フックを settings.json ではなく独立ファイルに定義した |
設定ファイルの "hooks" キーの下に定義する |
| グローバルに設定した権限やフックが無視される | ~/.claude.json に書いた |
permissions・hooks・env は ~/.claude/settings.json に書く |
settings.json の値が無視される |
同じキーが settings.local.json にある |
settings.local.json が settings.json を上書きし、両者が ~/.claude/settings.json を上書きする |
スキルが /skills に出ない |
.claude/skills/name.md になっている |
.claude/skills/name/SKILL.md のフォルダ構成にする |
| スキルは出るのに呼ばれない | disable-model-invocation: true、または description が頼み方と噛み合っていない |
/skills のバッジを見る。”user-only” なら自動では呼ばれない |
サブディレクトリの CLAUDE.md が無視される |
起動時ではなくオンデマンドで読み込まれる | そのディレクトリのファイルを Read ツールで読んだ時に読み込まれる |
| セッション終了時の後処理が動かない | SessionEnd フックが未設定 |
settings.json に SessionEnd フックを追加する |
.mcp.json のMCPサーバーが読み込まれない |
ファイルが .claude/ の下にある、またはサーバーが servers キーの下にある |
リポジトリ直下の .mcp.json に置き、mcpServers キーの下に書く |
settings.json の mcpServers が出てこない |
settings.json は mcpServers キーを読まない |
.mcp.json に書くか claude mcp add --scope user を使う |
| MCPサーバーが特定のディレクトリから起動しない | command や args が相対パス |
ローカルのスクリプトは絶対パスで書く |
Bash(rm *) のdenyが /bin/rm を止めない |
Bashルールはコマンド文字列に一致するもので、実行ファイルを見ていない | PreToolUseフックかサンドボックスで担保する |
最後の行は性質が違うので補足する。これは設定が効いていないのではなく、Bashの deny ルールでできることの範囲の問題だ。確実に止めたいなら、権限ルールではなくフックかサンドボックス側で受ける。権限ルールの設計はClaude Code権限設計ガイドを参照してほしい。
想定の切り分け例（実測値ではありません）
以下は手順の流れを見せるための想定であり、特定の企業や計測結果ではない。
読み込まれていない側の想定
想定1：チームに配ったフックが自分の環境だけ動かない。 /hooks を打つとイベント一覧にそのフックが出ない。読まれていないと判断し、claude doctor を実行する。設定ファイルの検証失敗が報告されていた。matcher を配列で書いていたため、そのファイル全体が拒否されていた。"Edit|Write" の文字列に直して保存すると、再起動せずに /hooks へ出てきた。
想定2：MCPサーバーのツールが会話に出てこない。 /mcp を打つと、サーバーは一覧にあるが failed になっている。command に ./scripts/server.js と相対パスを書いていた。Claude Code を別ディレクトリから起動していたため解決に失敗していた。絶対パスに直して /mcp から Reconnect を選ぶと、ツール数が0から増えた。
書き方と二分探索の想定
想定3：CLAUDE.md に書いたコミット規約を守らない。 /context を打つとメモリファイル欄に CLAUDE.md は出ている。読み込み側ではないと判断し、書き方を見る。同じリポジトリの別の CLAUDE.md に矛盾した指示があった。片方に寄せると従うようになった。
想定4：どこから調べるか分からない。 claude --safe-mode で起動すると症状が消えた。原因は自分のカスタマイズ側だと確定する。/context に戻り、スキルとサブエージェントの読み込み元を1つずつ見ていく。
今日やる3つ
- 症状が出るプロジェクトで
/contextを打ち、目的のファイルが一覧に出ているかどうかだけを見る。出ていなければ置き場所の問題、出ていれば書き方か上書きの問題と確定させる。 claude doctorをターミナルから実行し、無効な設定ファイルと弾かれた項目が無いかを確認する。ここで出る検証失敗は、フックやスキルの「黙って動かない」の原因になっていることが多い。claude --safe-modeで一度起動して、症状が自分の設定由来かどうかを二分する。この1回で調査範囲が半分になる。
あわせて読みたい
- Claude Code settings.json設定完全ガイド：設定ファイルの階層と優先順位、権限やモデル指定の書き方。
- CLAUDE.md設計・運用ガイド：読み込まれているのに守られない時の、指示の粒度と分量の設計。
- Claude Code Hooks実践ガイド：整形・テスト・通知をフックに載せる時の構成。
- Claude Code Skills作成ガイド：
SKILL.mdのフロントマターと説明文の書き方。 - Claude Code権限設計ガイド：allow / ask / deny の組み合わせと、フックで担保すべき境界。
- Claude Code MCP実践ガイド：
.mcp.jsonの構成とサーバーの自作。
よくある質問
まず打つべきコマンドは何ですか
/context です。いまのセッションに何が読み込まれているかをカテゴリ別に出すので、「読み込まれていない」のか「読み込まれているが効いていない」のかが1回で分かれます。ここを飛ばして内容を直し始めると、読み込まれていないファイルを直し続けることになります。
/doctor と claude doctor は何が違いますか
claude doctor はターミナルから実行し、セッションを起動せずにインストールと設定の診断を読み取り専用で出します。/doctor はセッションの中で実行し、点検に加えて修正案を提示し、適用前に確認を取ります。無効な設定ファイルを探すだけなら claude doctor が速いです。
settings.json を編集したら再起動が必要ですか
要りません。Claude Code は設定ファイルを監視していて、ファイルが安定するまでの短い待ちを挟んで動いているセッションに反映します。セッション開始後に作ったファイルや、セッション中に作ったプロジェクトの .claude/ フォルダも読み込まれます。/hooks の表示が古いままなら、/hooks をもう一度実行して更新してください。
~/.claude.json に権限を書いたのに効きません
~/.claude.json はアプリの状態とUIのトグルを持つファイルで、permissions・hooks・env の置き場所ではありません。これらは ~/.claude/settings.json に書きます。名前が似た別のファイルです。
「Yes, and don’t ask again」を選んだのに毎回聞かれます
その選択はローカルファイルに allow ルールとして保存されますが、ローカルの allow はプロジェクトや管理設定の ask ルールより優先されません。VS Code拡張では承認カードで保存先ファイルを選べて、プロジェクトの共有ファイルを選べば全員に効きます。CLIではローカルファイルにしか書かれません。
サブディレクトリの CLAUDE.md が読まれていないようです
仕様どおりです。サブディレクトリの CLAUDE.md は、Claude がそのディレクトリ内のファイルを Read ツールで読んだ時に読み込まれます。起動時ではなく、そこにファイルを書いたり作ったりした時でもありません。
セーフモードでも症状が消えません
原因がユーザー設定とプロジェクト設定の外側にあります。/status で管理設定が効いているかを確認し、Claude Code に影響する環境変数を探してください。組織が配布する管理設定は、セーフモードでもクリーンな設定ディレクトリでも適用されたままになります。
スキルが /skills に出ているのに呼ばれません
フロントマターに disable-model-invocation: true が入っているか、description が自分の頼み方と噛み合っていないかのどちらかです。/skills のバッジに “user-only” と出ていれば、Claude は自分からは呼びません。
運営元 Uravation よりこの事例を自社の業務で試す場合のテーマ選定・評価・本番移行の確認項目を、無料のチェックリストにまとめています。 Claude Code業務自動化PoCチェックリストを受け取る（無料）
参考・出典
- Anthropic「Debug your configuration」（/context・/doctor・/hooks・/mcp・–safe-mode・よくある原因表・2026年9月28日確認）
- Anthropic「Settings files and precedence」（設定ファイル4種とマージ順・2026年9月28日確認）
- Anthropic「Hooks reference」（matcher の書式とデバッグ出力・2026年9月28日確認）
- Anthropic「Connect Claude Code to tools via MCP」（.mcp.json の置き場所と承認・2026年9月28日確認）
- Anthropic「How Claude remembers your project」（CLAUDE.md の読み込みタイミング・2026年9月28日確認）
- Anthropic「Extend Claude with skills」（SKILL.md の配置と呼び出し条件・2026年9月28日確認）
- Anthropic「Create custom subagents」（omitClaudeMd と起動時に読み込まれるもの・2026年9月28日確認）
- Anthropic「Configure permissions」（allow / ask / deny の組み合わせ順序・2026年9月28日確認）
- Anthropic「Environment variables」（CLAUDE_CONFIG_DIR・2026年9月28日確認）
- Anthropic「Claude Code: Best practices for agentic coding」（CLAUDE.md の書き方の指針・2026年9月28日確認）
- JSON Schema Store「claude-code-settings.json」（settings.json の公開スキーマ・2026年9月28日確認）
