本文へ移動
Claude Tips

設定のデバッグ

CLAUDE.md・設定・フック・MCP サーバー・スキルが効かないとき、/context や /doctor で実際に読み込まれた内容を確かめて原因を絞る手順と、よくある原因の一覧です。

Claude が指示を無視する、設定した機能が現れない、というときの原因は、たいていファイルが読み込まれていない、想定と別の場所から読み込まれた、別のファイルに上書きされた、のどれかです。このページでは、Claude Code が実際に何を読み込んだかを調べて、どれに当たるか絞る手順をまとめます。インストール・認証・接続の問題は インストールとログイン、性能や固まる問題は トラブルシューティング を見てください。

  • まず /context で、CLAUDE.md・ルール・スキルの説明が文脈に入っているかを確かめます
  • 設定は管理・ユーザー・プロジェクト・ローカルで統合され、環境変数やフラグが上書きすることもあります
  • フックは /hooks、MCP サーバーは /mcp で状態を見ます
  • 切り分けには、カスタマイズをすべて無効にする claude --safe-mode が使えます

文脈に何が読み込まれたか見る#

/context は、現在のセッションで文脈ウィンドウを占めているものを、カテゴリ別に出します。system prompt・システムのツール・MCP のツール・カスタムのサブエージェント（読み込み元つき）・メモリのファイル・スキル・会話のメッセージです。最初にこれを実行して、CLAUDE.md・ルール・スキルの説明が、そもそも入っているかを確かめます。/context のスキルの項には、/skills が出さない組み込みスキルも入ります。

特定のカテゴリの詳細は、専用のコマンドで見ます。

コマンド 表示するもの
/memory ユーザーとプロジェクトのスコープにまたがるメモリファイルの場所。それぞれをエディタで開ける。auto memory のフォルダーと、auto memory の切り替えにも入れる
/skills プロジェクト・ユーザー・プラグインから使えるスキル
/hooks 有効なフックの設定
/mcp 接続した MCP サーバーとその状態
/permissions 現在有効な、解決済みの許可・拒否のルール
/doctor 環境の点検。インストールの状態・不正な設定ファイル・使われていない拡張・同じディレクトリでのサブエージェント名の重複・コードベースから Claude が導ける、チェックイン済みの CLAUDE.md の内容を見て、修正案を出す
/debug [issue] そのセッションのデバッグログを有効にし、ログの出力と設定のパスで診断するよう Claude に促す
/status 有効な設定の出どころ。管理設定が効いているかも分かる

メモリのファイルが /context の内訳に無いときは、置き場所を CLAUDE.md とメモリ の読み込みの規則と照らします。サブディレクトリの CLAUDE.md は、起動時でなく、Claude がそのディレクトリのファイルに Read・Write・Edit ツールを使ったあとに、必要に応じて読み込まれます。

/context でファイルが読み込まれたと確認できたのに、特定の指示に従わないなら、読み込みでなく、指示の書き方が原因の可能性が高いです。CLAUDE.md は、新しいチームメイトに渡すような指針（プロジェクトの規約・ビルドのコマンド・ファイルの置き場所）に向きます。従う率が下がるのは、複数の解釈ができるほどあいまいな指示、2つのファイルの指示が食い違う、ファイルが長くなって個々のルールへの注意が薄れる、といったときです（具体性・サイズ・構成の型は CLAUDE.md とメモリ を見てください）。

補足

CLAUDE.md と権限は、別の問題を解きます。CLAUDE.md は、プロジェクトのやり方を伝えて、Claude に良い判断をさせるものです。権限ルール と フックのリファレンス は、Claude が何を決めても制限を強制します。「ここではこうする」は CLAUDE.md、セキュリティの境界や絶対に起きてはいけないこと（指針でなく保証が要るもの）は、権限かフックを使います。

解決後の設定を確かめる#

設定は、管理・ユーザー・プロジェクト・ローカルのスコープをまたいで統合されます。管理設定があれば、最初に適用されます。それ以外では、近いスコープが広いスコープを上書きします（ローカル、プロジェクト、ユーザーの順）。コマンドラインのフラグや 環境変数一覧 も、もう1つの上書きの層として使える設定があります。設定が効かないように見えるときは、設定した値が、別のスコープか環境変数に上書きされているのが普通です。

  • 不正な設定ファイルを探すには、ターミナルで claude doctor を実行します。セッションを始めずに、読み取り専用で、インストールと設定の診断を出します
  • 修正案を出して、適用前に確認する完全な点検には、セッション内で /doctor を実行します
  • /status で、有効な設定の出どころ（管理設定が効いているか）を確かめます
  • あるキーにどのスコープが使われるかは、設定ファイルの仕組み を見てください

MCP サーバーを確かめる#

/mcp で、設定したすべてのサーバー・接続の状態・現在のプロジェクトで承認したかを確認します。サーバーが正しく定義されていても、ツールが出ないことがあります。

  • .mcp.json のプロジェクトスコープのサーバーは、一度だけの承認が要ります。プロンプトを閉じてしまうと、/mcp で承認するまで無効のままです
  • 起動に失敗したサーバーは、/mcp で失敗と表示されます。よくある原因は、command や args の相対パスです。.mcp.json の場所でなく、Claude Code を起動したディレクトリを基準に解決されます
  • 接続済みなのにツールが0個のサーバーは、起動はしているが、ツールの一覧を返していません。/mcp で「Reconnect」を選びます。0のままなら、claude --debug=mcp を実行し、デバッグログ ~/.claude/debug/<session-id>.txt のサーバーの stderr を読みます

設定の場所とスコープの規則は MCP サーバーをつなぐ を見てください。

フックを確かめる#

/hooks で、現在のセッションに登録されたすべてのフックを、イベント別に確認します。定義したフックが出てこないなら、Claude Code が読み込んでいません。次の原因を確認します。

  • フックを単独のファイルに定義している。フックは、設定ファイルの "hooks" キーの下に書きます
  • matcher の値が、1つの文字列でなく配列になっている。対話セッションの開始時と claude doctor で、Claude Code はその項目を無効な設定として一覧します。配列が PreToolUse か PermissionRequest の下にあると、そのファイルのほかのフックも読み込まれません

フックが出ているのに動かないなら、たいてい matcher が原因です。次の間違いを確認します。

  • matcher は、"Edit|Write" のように | で複数のツール名をつなぐ、1つの文字列です。区切りに , を使っても同じ意味になり、"Edit,Write" は同じツールに一致します。v2.1.191 より前は、カンマが正規表現として評価されて何にも一致しなかったので、v2.1.191 より前なら | を使います
  • ツール名のつづりを間違えると、何にも一致しない matcher になり、フックは黙って動きません

settings.json を編集すると、少し待ってファイルが安定したあとに、実行中のセッションへ反映されます。ファイルや、プロジェクトの .claude/ フォルダー自体をセッション開始後に作った場合も同じで、再起動は要りません（v2.1.257 より前は、セッション開始後に作った .claude/ フォルダーの編集を検出しませんでした）。保存して数秒後も /hooks が古い定義のままなら、もう一度 /hooks を実行して表示を更新します。

/hooks にフックが出るのに動かないなら、次はフックの評価を実際に見ます。claude --debug でセッションを始め、ツールの呼び出しを起こします。デバッグログに、各イベント・確認された matcher・フックの終了コードと出力が記録されます。ログの形式は フックのリファレンス、よくある失敗のパターンは フックの使い方 を見てください。

クリーンな設定で試す#

まず claude --safe-mode を試します。CLAUDE.md・スキル・プラグイン・フック・MCP サーバー・カスタムのコマンドとエージェントを含む、すべてのカスタマイズを無効にして、セッションを始めます。認証・モデルの選択・組み込みのツール・権限は普通に動きます。

  • safe mode で問題が消えるなら、それらのどれかが原因です。上の個別の確認で、どれかを探します
  • safe mode でも、組織の管理されたフックと設定のポリシーは適用されます。管理されたプラグイン・スキル・CLAUDE.md・MCP サーバーは無効になります
  • safe mode でも問題が残る、または設定そのものが疑わしいときは、普段の設定から何も読み込まないセッションと比べます。CLAUDE_CONFIG_DIR を空のディレクトリへ向けて ~/.claude 以下をすべて迂回し、.claude フォルダー・.mcp.json・CLAUDE.md の無いディレクトリから起動して、プロジェクトの設定も飛ばします
bash
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
  • クリーンなセッションには、ユーザーとプロジェクトの設定・フック・MCP サーバー・プラグイン・メモリがありません。初回の起動では、テーマの選択から始まる初回のセットアップ画面が出ます。出れば、クリーンな設定ディレクトリが効いています。同じディレクトリでの2回目以降は、オンボーディングの状態がそこに保存されるので、この画面は出ません
  • 組織が管理設定を配っていれば、それは適用されます。Claude Code は、MDM プロファイル・レジストリのポリシー・managed-settings.json を設定ディレクトリの外から読み、認証情報を得たあとのクリーンなセッションでも、サーバー管理設定を再取得します
  • もう一度ログインを求められます

ここで問題が消えるなら、原因は、実際の ~/.claude かプロジェクトの .claude のファイルのどこかにあります。一時ディレクトリへファイルをコピーするか、プロジェクトから起動して、1つずつ戻して探します。クリーンなセッションでも続くなら、原因はユーザーとプロジェクトの設定の外にあります。/status で管理設定が効いているかを確認し、Claude Code に影響する環境変数を探してから、トラブルシューティング を見ます。

よくある原因#

設定まわりの意外な挙動の多くは、場所と書式の少数の決まりに行き着きます。不具合と決めつける前に確認します。

フック#

症状 原因 対処
フックが動かない matcher が文字列でなく JSON の配列 複数のツールを | でつなぐ1つの文字列にする（例："Edit|Write"）。フックのリファレンス の matcher のパターンを見る
フックが動かない v2.1.191 より前の版で、matcher の区切りに , を使っている v2.1.191 以降は、, を | と同じ区切りとして扱う。それ以前は、カンマを文字として評価し、"Edit,Write" は何にも一致しない。| を使うか、Claude Code を更新する
フックが動かない matcher の値が小文字（例："bash"） 一致は大文字小文字を区別する。ツール名は先頭が大文字：Bash・Edit・Write・Read
フックが動かない settings.json でなく単独のファイルに定義した プロジェクトやユーザーの設定には、単独のフックのファイルが無い。settings.json の "hooks" キーの下に定義する。別の hooks/hooks.json を読むのは プラグインを作って配る だけ
セッション終了時の後始末が走らない SessionEnd フックが設定されていない settings.json に SessionEnd フックを足す（フックのリファレンス のイベント一覧）

設定とメモリ#

症状 原因 対処
全体に設定した権限やフックが無視される 設定を ~/.claude.json に足した ~/.claude.json はアプリの状態と UI の切り替えを持つ。permissions・hooks・env は ~/.claude/settings.json に置く。別の2つのファイル
settings.json の値が無視されたように見える 同じキーが settings.local.json にある settings.local.json が settings.json を上書きし、どちらも ~/.claude/settings.json を上書きする（設定ファイルの仕組み）
サブディレクトリの CLAUDE.md の指示が無視されたように見える サブディレクトリのファイルは、起動時でなく必要に応じて読み込まれる Claude が、そのディレクトリのファイルに Read・Write・Edit ツールを使ったあとに読み込まれる。起動時には読み込まれない。v2.1.288 より前は Read ツールだけが読み込ませた（CLAUDE.md とメモリ）
サブエージェントが CLAUDE.md の指示を無視する 組み込みの Explore と Plan のエージェントは CLAUDE.md を読まない。カスタムのサブエージェントは、定義で omitClaudeMd を設定していない限り、メインの会話と同じに読み込む Explore や Plan には、依頼のプロンプトで指示を言い直す。omitClaudeMd を設定したサブエージェントは、そのフィールドを外す。それ以外のカスタムのサブエージェントは、エージェントのファイルの本文（エージェントの system prompt になる）に重要な指示を置く（サブエージェント）

スキル#

症状 原因 対処
スキルが /skills に出ない スキルのファイルが、フォルダーでなく .claude/skills/name.md にある フォルダーの中に SKILL.md を置く：.claude/skills/name/SKILL.md
/skills に出るのに Claude が呼ばない frontmatter に disable-model-invocation: true がある、または説明が、依頼の言い回しに合っていない /skills のバッジを確認する。「user-only」の表示は、Claude が自分では起動しないという意味（スキル）

MCP#

症状 原因 対処
.mcp.json の MCP サーバーが読み込まれない ファイルが .claude/ の下にある、またはサーバーが mcpServers でなく、VS Code の mcp.json のような最上位の servers キーの下にある プロジェクトの MCP 設定は、.claude/ の中でなくリポジトリのルートに .mcp.json として置き、サーバーは mcpServers キーの下に書く（MCP サーバーをつなぐ）
settings.json の mcpServers に足したサーバーが出ない settings.json は mcpServers キーを読まない プロジェクトのサーバーはリポジトリのルートの .mcp.json に定義するか、ユーザースコープのサーバーは claude mcp add --scope user で足す
プロジェクトの MCP サーバーを足したのに出ない 一度だけの承認プロンプトを閉じた プロジェクトスコープのサーバーは承認が要る。/mcp で状態を見て承認する
特定のディレクトリから MCP サーバーが起動しない command や args が相対のファイルパス ローカルのスクリプトには絶対パスを使う。npx や uvx のように PATH にある実行ファイルは、そのまま使える
MCP サーバーが、期待する環境変数なしで起動する サーバーの設定の項目に設定がなく、Claude Code が stdio サーバーに渡す環境（自身の環境から、サブプロセスで取り除く変数を引いたもの）にも無い サーバーごとの env を、サーバーの .mcp.json の項目の中に設定する。起動時の環境やワークスペースの信頼に依存しない

権限#

症状 原因 対処
Bash(rm *) の拒否ルールが /bin/rm や find -delete を止めない Bash のルールは、元の実行ファイルでなく、コマンド文字列そのものに一致する（権限ルール の Bash のルールの限界） 確実に止めるには、PreToolUse フック（フックの使い方）か サンドボックス を使う

関連するページ#

公式ドキュメント（英語）

2026年10月5日時点の内容をもとに、日本語でまとめています。

ページの一覧