中小DXラボ のツール

Claude Code の設定が効かないときの確かめ方

公開: ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

結論

  • Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)の設定が効かないときは、まず /context で実際に読み込まれた内容を確認します。
  • 原因は、読み込まれていない、別の場所から読み込まれた、別の設定に上書きされた、のどれかであることが多いとされています。優先順位、フックの matcher、MCP の承認などを順に確認します。
  • 見当がつかないときは claude --safe-mode や、空のディレクトリとクリーンな設定ディレクトリでの起動で、問題が続くかを切り分けます。

まず読み込まれた内容を確認する

公式ドキュメントによると、指示が無視される、設定した機能が出てこないといった場合は、ファイルが読み込まれていない、想定と別の場所から読み込まれた、別のファイルに上書きされた、のどれかであることが多いとされています。

最初に /context を実行します。現在のセッションでコンテキストウィンドウ(AI が一度に参照できる情報の枠)を占めるものを、システムプロンプト、MCP ツール、メモリファイル、スキル、会話メッセージなどに分けて表示します。CLAUDE.md やスキルの説明が載っているかを確認できます。詳しく見たい項目には、次のコマンドを使います。

  • /memory: メモリファイルの場所を表示します。
  • /skills: 使えるスキルを表示します。
  • /hooks: 有効なフック設定を表示します。
  • /mcp: MCP サーバーと接続状態を表示します。
  • /permissions: 有効な allow と deny のルールを表示します。
  • /doctor: 設定ファイルの不正などを点検し、修正案を出します。
  • /status: 有効な設定の読み込み元と、managed settings の有無を表示します。

サブディレクトリの CLAUDE.md は必要になったときに読み込まれるため、/context の内訳には出ません。読み込まれているのに従わないときは、曖昧な指示、ファイル間の矛盾、ファイルの長さが原因になりやすいとされています。決して起きてはならないことには、CLAUDE.md ではなく permissions や hooks を使います。

出典: Debug your configuration

設定の優先順位と置き場所を確認する

公式ドキュメントでは、設定は managed、user、project、local の各スコープ(適用範囲)で統合されると説明されています。managed settings がある場合は最初に適用され、それ以外は local、project、user の順に近い範囲が優先されます。コマンドラインのフラグや環境変数も、もう一段の上書き層です。

不正な設定ファイルは、ターミナルで claude doctor を実行すると読み取り専用で診断できます。修正案の提示と適用前の確認までは、セッション内の /doctor で行います。

  • permissions、hooks、env を ~/.claude.json に書いても効きません。このファイルはアプリの状態用で、これらは ~/.claude/settings.json に書きます。
  • settings.local.json は settings.json を上書きし、どちらも ~/.claude/settings.json を上書きします。

出典: Debug your configuration

フックが出てこない・動かないとき

/hooks で、現在のセッションのフック(ツール実行の前後などで自動的に動かす処理)が一覧表示されます。定義したのに出てこなければ、読み込まれていません。

  • 単独のファイルに書いている: フックは設定ファイルの "hooks" キーの下に書きます。別ファイルの hooks/hooks.json を読むのはプラグインだけです。
  • matcher が配列になっている: 不正な設定として表示され、PreToolUse か PermissionRequest の下なら、そのファイルの他のフックも読み込まれません。

表示されるのに動かないときは、matcher を確認します。

  • 複数のツールは単一の文字列に | でつなぎ、例えば "Edit|Write" とします。
  • , 区切りは v2.1.191 以降で同じ意味になります。それより前では一致しないため、| を使います。
  • ツール名は大文字小文字を区別します。Bash、Edit、Write、Read のように先頭は大文字です。つづりを間違えると何にも一致せず、静かに失敗します。

原因が分からなければ claude --debug で起動してツール呼び出しを起こすと、確認された matcher やフックの終了コードがログに残ります。

執筆時点(2026年10月)の公式ドキュメントでは、settings.json の編集は少しの待ち時間のあと、再起動なしで実行中のセッションに反映されるとされています。ただし v2.1.257 より前は、セッション開始後に作られた .claude/ フォルダの編集を検出しませんでした。

出典: Debug your configuration

MCP サーバーのツールが出てこないとき

/mcp で、サーバー、接続状態、現在のプロジェクトで承認済みかを確認します。定義が正しくてもツールが出ない主な理由は次のとおりです。

  • .mcp.json のプロジェクトスコープのサーバーは、一度だけの承認が必要です。確認を閉じると、/mcp から承認するまで無効のままです。
  • 起動に失敗するときは、command や args の相対パスが多い原因です。.mcp.json の場所ではなく、Claude Code を起動したディレクトリが基準になります。ローカルのスクリプトにはフルパスを使います。
  • connected なのにツールが 0 件なら、/mcp で Reconnect を選びます。変わらなければ claude --debug=mcp を実行し、デバッグログにあるサーバーの stderr を読みます。

置き場所にも注意します。プロジェクトの設定は .claude/ の中ではなくリポジトリのルートの .mcp.json に、mcpServers キーの下で書きます。settings.json は mcpServers キーを読みません。

出典: Debug your configuration

クリーンな設定で切り分ける

原因が絞れないときは claude --safe-mode で起動します。CLAUDE.md、スキル、プラグイン、フック、MCP サーバー、カスタムコマンドやエージェントなどが無効になり、認証、モデル選択、組み込みツール、権限は通常どおり動きます。問題が消えれば、無効にした項目のどれかが原因です。組織の managed hooks と設定ポリシーは safe mode でも適用されます。

それでも続くときは、自分の設定を持たないセッションで再現を確認します。まず Claude Code が動いていないシェルで、空のディレクトリを作って移動します(Bash または Zsh の例です)。

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty

次に、同じシェルで新しい設定ディレクトリを指定し、--setting-sources user でプロジェクト設定を無効にして起動します。初回は初期設定画面が出ます。

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

最後に問題を再現させます。消えたなら原因はユーザーかプロジェクトの設定にあるため、~/.claude.json と ~/.claude のファイルを1つずつコピーして調べます。続くなら、/status で managed settings を確認し、シェルの環境変数も確認します。

出典: Debug your configuration

よくある質問

settings.json を編集したら、Claude Code の再起動は必要ですか?

公式ドキュメントによると、少しの待ち時間のあと実行中のセッションに反映されるため、再起動は不要です。ただし v2.1.257 より前は、セッション開始後に作られた .claude/ フォルダの編集を検出しません。保存後も /hooks が古い定義のままなら、もう一度 /hooks を実行して表示を更新します。

出典: Debug your configuration

設定した値が別の設定に上書きされていないかは、どう調べますか?

/status で有効な設定の読み込み元と managed settings の有無を確認します。公式ドキュメントでは、managed settings が先に適用され、それ以外は local、project、user の順に近い範囲が優先されると説明されています。環境変数やコマンドラインのフラグも上書き層になります。不正な設定ファイルは claude doctor で調べられます。

出典: Debug your configuration

.mcp.json に書いた MCP サーバーが出てこないのはなぜですか?

公式ドキュメントでは、一度だけの承認を閉じたままにしていないか、.mcp.json がリポジトリのルートにあり mcpServers キーの下に書かれているかを確認するとされています。起動に失敗する場合は、command や args の相対パスも原因になります。まず /mcp で状態を確認してください。

出典: Debug your configuration

関連する無料ツール

Claude Code つまずき早見表: Windows で Claude Code を使うときに起きやすい症状を、原因と対処で引ける早見表です。

参考(執筆時点)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。