SpyBara
Go Premium

debug-your-config.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 21 additions and 22 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

設定をデバッグする

CLAUDE.md、設定、hooks、MCP サーバー、またはスキルが機能していない理由を診断します。/context、/doctor、/hooks、/mcp を使用して、実際に読み込まれた内容を確認します。

Claude が指示を無視したり、設定した機能が表示されない場合、通常の原因はファイルが読み込まれなかった、予期した場所とは異なる場所から読み込まれた、または別のファイルがそれをオーバーライドしたことです。このガイドでは、Claude Code が実際に読み込んだ内容を検査して、どれが当てはまるかを絞り込む方法を示します。

インストール、認証、接続の問題については、代わりに トラブルシューティング インストールとログイン を参照してください。

コンテキストに読み込まれた内容を確認する

/context コマンドは、現在のセッションのコンテキストウィンドウを占めるすべてのものを表示します。カテゴリ別に分類されます：システムプロンプト、システムツール、MCP ツール、カスタムサブエージェント（読み込み元を含む）、メモリファイル、スキル、会話メッセージです。まず実行して、CLAUDE.md、ルール、またはスキルの説明が存在するかどうかを確認します。/context のスキルセクションには、バンドルされたスキルも含まれています。これは /skills には表示されません。

特定のカテゴリの詳細については、専用コマンドで確認してください：

コマンド 表示内容
/memory ユーザーとプロジェクトスコープ全体のメモリファイルの場所。各ファイルをエディタで開くオプション、オートメモリフォルダへのアクセス、およびオートメモリトグル
/skills プロジェクト、ユーザー、プラグインソースから利用可能なスキル
/hooks アクティブなフック設定
/mcp 接続された MCP サーバーとそのステータス
/permissions 現在有効な許可と拒否ルール
/doctor セットアップチェック：インストール状態、無効な設定ファイル、未使用の拡張機能、同じディレクトリ内の重複する サブエージェント 名、および提案される修正
/debug [issue] セッションのデバッグログを有効にし、Claude にログ出力と設定パスを使用して診断するよう促します
/status アクティブな設定ソース（マネージド設定が有効かどうかを含む）

メモリファイルが /context の内訳に見つからない場合は、その場所を CLAUDE.md ファイルの読み込み方法 と照らし合わせて確認してください。サブディレクトリの CLAUDE.md ファイルは、セッション開始時ではなく、Claude が Read ツールでそのディレクトリ内のファイルを読むときにオンデマンドで読み込まれます。

/context がファイルが読み込まれたことを確認しても Claude が特定の指示に従わない場合、問題はファイルが読み込まれたかどうかではなく、指示の書き方である可能性が高いです。CLAUDE.md は、新しいチームメンバーに与えるような指示に適しています。例えば、プロジェクト規約、ビルドコマンド、ファイルの場所などです。

指示が複数の方法で解釈できるほど曖昧な場合、2 つのファイルが矛盾した指示を与える場合、またはファイルが長くなって個々のルールの注意が減る場合、遵守は低下します。効果的な指示を書く は、遵守を高く保つ特異性、サイズ、構造パターンをカバーしています。

解決された設定を確認する

設定はマネージド、ユーザー、プロジェクト、ローカルスコープ全体でマージされます。マネージド設定が存在する場合は常に優先されます。その他の場合、より近いスコープが、ローカル、プロジェクト、ユーザーの順序でより広いスコープをオーバーライドします。一部の設定は、コマンドラインフラグまたは 環境変数 で設定することもでき、これは別のオーバーライドレイヤーとして機能します。設定が適用されないように見える場合、設定した値は通常、別のスコープまたは環境変数によってオーバーライドされています。

無効な設定ファイルを見つけるには、ターミナルから claude doctor を実行してください。セッションを開始せずに、読み取り専用のインストールと設定の診断をプリントします。セッション内で完全なチェックアップを実行する場合は、/doctor を実行してください。これは修正を提案し、適用する前に確認を求めます。

/status を実行して、マネージド設定が有効かどうかを含む、どの設定ソースがアクティブかを確認します。特定のキーに対して Claude Code がどのスコープを使用するかを理解するには、設定の優先順位 を参照してください。

MCP サーバーを確認する

/mcp を実行して、すべての設定されたサーバー、その接続ステータス、および現在のプロジェクトに対して承認したかどうかを確認します。サーバーは正しく定義されていても、いくつかの一般的な理由でツールを提供しない場合があります：

  • .mcp.json のプロジェクトスコープサーバーは 1 回限りの承認が必要です。プロンプトが却下された場合、/mcp から承認するまでサーバーは無効のままです。
  • 起動に失敗したサーバーは /mcp で失敗として表示されます。command または args の相対ファイルパスは頻繁な原因です。これらは .mcp.json の場所ではなく、Claude Code を起動したディレクトリに対して解決されるためです。
  • 接続されているが 0 個のツールをリストするサーバーは正常に起動していますが、ツールリストを返していません。/mcp から 再接続 を選択します。カウントが 0 のままの場合は、claude --debug=mcp を実行してサーバーの stderr をデバッグログ（~/.claude/debug/<session-id>.txt）で確認します。

設定場所とスコープルールについては、MCP を参照してください。

Hooks を確認する

/hooks を実行して、現在のセッションに登録されているすべてのフックをイベント別にグループ化して一覧表示します。定義したフックが表示されない場合、それは読み込まれていません：hooks は設定ファイルの "hooks" キーの下に置かれ、スタンドアロンファイルではありません。

フックが表示されても発火しない場合、通常の原因はマッチャーです。以下の間違いがないか確認してください：

  • matcher フィールドは、複数のツール名をマッチするために | を使用する単一の文字列です。例えば "Edit|Write" です。, セパレータは同等であるため、"Edit,Write" は同じツールをマッチします。v2.1.191 より前では、カンマは正規表現評価にフォールスルーし、マッチャーは一致しないため、v2.1.191 をまだ使用していない場合は | を使用してください。
  • ツール名のスペルミスはマッチャーが何もマッチしないため、フックはサイレントに失敗します。
  • 配列値はスキーマエラーです：Claude Code は設定エラー通知を表示し、ユーザー、プロジェクト、またはローカル設定ファイル全体を拒否し、claude doctor は検証失敗を報告し、そのファイルからのフックは /hooks に表示されません。管理設定では、Claude Code はそのファイルを含む hooks キー全体をファイルから削除するため、そのファイルのフックは適用されません。ファイルの他の設定は引き続き適用され、claude doctor は削除されたキーをリストします。

settings.json を編集すると、短いファイル安定性遅延後に実行中のセッションで変更が有効になります。セッション開始後にプロジェクトの .claude/ フォルダを作成した場合でも、再起動する必要はありません。v2.1.257 より前では、Claude Code はセッション開始後に作成された .claude/ フォルダの編集を検出しませんでした。

保存後数秒経っても /hooks が古い定義を表示している場合は、/hooks を再度実行してビューをリフレッシュしてください。

/hooks がフックを表示しても発火しない場合、次のステップはフック評価をライブで監視することです。claude --debug でセッションを開始し、ツール呼び出しをトリガーします。デバッグログは各イベント、チェックされたマッチャー、フックの終了コードと出力を記録します。ログ形式については フックをデバッグする を、一般的な失敗パターンについては hooks トラブルシューティング を参照してください。

クリーン設定に対してテストする

claude --safe-mode で開始します。これにより、CLAUDE.md、skills、plugins、hooks、MCP サーバー、カスタムコマンド、エージェントを含むすべてのカスタマイズが無効になった状態でセッションが起動します。認証、モデル選択、組み込みツール、権限は通常通り機能します。セーフモードで問題が消える場合、これらのサーフェスのいずれかが原因です。上記のターゲット化されたチェックを使用して、どれが原因かを特定してください。セーフモードは、組織からのマネージド hooks と設定ポリシーを引き続き適用します。マネージド plugins、skills、CLAUDE.md、MCP サーバーはオフになります。

セーフモードで問題が続く場合、または設定自体が疑わしい場合は、通常のセットアップから何も読み込まないセッションと比較してください。CLAUDE_CONFIG_DIR を空のディレクトリに指定して ~/.claude の下のすべてをバイパスし、.claude フォルダ、.mcp.json、または CLAUDE.md がないディレクトリから起動して、プロジェクト設定もスキップします。

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

クリーンセッションには、ユーザーまたはプロジェクト設定、hooks、MCP サーバー、plugins、またはメモリがありません。最初の起動時には、テーマ選択から始まる最初の実行セットアップ画面が表示されることを想定してください。それらが表示される場合、クリーン設定ディレクトリが有効です。同じディレクトリでの後続の起動では、Claude Code がそこにオンボーディング状態を保存するため、これらの画面はスキップされます。

  • 組織がそれらをデプロイする場合、マネージド設定は引き続き適用されます。Claude Code は MDM プロファイル、レジストリポリシー、および設定ディレクトリの外の場所から managed-settings.json を読み取り、クリーンセッションが認証情報を取得した後、サーバーマネージド設定を再度取得します
  • ログインするよう再度促されます

問題がここで消える場合、原因は実際の ~/.claude またはプロジェクト .claude ファイルのどこかにあります。ファイルを一度に 1 つずつ再導入します。ファイルを一時ディレクトリにコピーするか、プロジェクトから起動して、どれが原因かを見つけます。クリーンセッションで問題が続く場合、原因はユーザーおよびプロジェクト設定の外にあります。/status を実行してマネージド設定が有効かどうかを確認し、Claude Code に影響を与える環境変数を探してから、トラブルシューティングを参照してください。

一般的な原因を確認する

ほとんどの設定の問題は、小さな場所とシンタックスルールのセットに遡ります。バグを想定する前にこれらを確認してください：

症状 原因 修正
フックが発火しない matcher が JSON 配列ではなく文字列である 複数のツールをマッチするために | を含む単一の文字列を使用します。例えば "Edit|Write" です。マッチャーパターン を参照してください。
フックが発火しない matcher が v2.1.191 より前のバージョンでセパレータとして , を使用しています Claude Code v2.1.191 以降は , をリスト区切り文字として | のように扱います。以前のバージョンではコンマをリテラル文字として評価するため、"Edit,Write" は何もマッチしません。代わりに | を使用するか、Claude Code をアップグレードしてください。
フックが発火しない matcher 値が小文字です。例えば "bash" マッチングは大文字と小文字を区別します。ツール名は大文字です：Bash、Edit、Write、Read。
フックが発火しない Hooks がスタンドアロンファイルではなく settings.json に定義されていません プロジェクトまたはユーザー設定用のスタンドアロン hooks ファイルはありません。settings.json の "hooks" キーの下に hooks を定義します。プラグイン のみが別の hooks/hooks.json を読み込みます。フック設定 を参照してください。
グローバルに設定された権限、hooks、env が無視されます 設定が ~/.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 をオーバーライドします。設定の優先順位 を参照してください。
スキルが /skills に表示されません スキルファイルがフォルダ内ではなく .claude/skills/name.md にあります SKILL.md を含むフォルダを使用します：.claude/skills/name/SKILL.md。
スキルが /skills に表示されますが Claude が呼び出しません スキルのフロントマターに disable-model-invocation: true があるか、その説明がリクエストの言い方と一致しません /skills のバッジを確認します：「user-only」ラベルは Claude が独自にトリガーしないことを意味します。スキル呼び出し を参照してください。
サブディレクトリの CLAUDE.md 指示が無視されているように見えます サブディレクトリファイルはセッション開始時ではなくオンデマンドで読み込まれます Claude が Read ツールでそのディレクトリ内のファイルを読むときに読み込まれます。起動時ではなく、ファイルを書き込みまたは作成するときではありません。CLAUDE.md ファイルの読み込み方法 を参照してください。
サブエージェントが CLAUDE.md 指示を無視します 組み込みの Explore および Plan エージェントは CLAUDE.md をスキップします。カスタムサブエージェントはメイン会話と同じ方法で読み込みます Explore または Plan の場合、委譲プロンプトで指示を再度述べてください。カスタムサブエージェントの場合、重要な指示をエージェントファイル本体に入れます。これはエージェントのシステムプロンプトになります。起動時に読み込まれるもの を参照してください。
クリーンアップロジックがセッション終了時に実行されません SessionEnd フックが設定されていません settings.json に SessionEnd フックを追加します。フックイベントリスト を参照してください。
.mcp.json の MCP サーバーが読み込まれません ファイルが .claude/ の下にあるか、サーバーが VS Code の mcp.json のように、トップレベルの servers キーの下にあります。代わりに mcpServers を使用してください プロジェクト MCP 設定はリポジトリルートの .mcp.json に置かれます。.claude/ 内ではなく、mcpServers キーの下にサーバーがあります。MCP 設定 を参照してください。
settings.json の mcpServers の下に追加された MCP サーバーが表示されません settings.json は mcpServers キーを読み込みません プロジェクトサーバーをリポジトリルートの .mcp.json で定義するか、claude mcp add --scope user を実行してユーザースコープサーバーを追加します。MCP 設定 を参照してください。
プロジェクト MCP サーバーが追加されても表示されません 1 回限りの承認プロンプトが却下されました プロジェクトスコープサーバーは承認が必要です。/mcp を実行してステータスを確認し、承認します。
MCP サーバーが一部のディレクトリから起動に失敗します command または args が相対ファイルパスを使用しています ローカルスクリプトには絶対パスを使用します。npx または uvx のような PATH 上の実行可能ファイルはそのまま機能します。
MCP サーバーが予期された環境変数なしで起動します サーバーの設定エントリがそれらを設定していません。また、Claude Code が stdio サーバーに渡す環境にもありません：独自の環境から、サブプロセスから削除する変数 を差し引いたもの サーバーの .mcp.json エントリ内でサーバーごとの env を設定します。これは起動環境またはワークスペーストラストに依存しません。
Bash(rm *) 拒否ルールが /bin/rm または find -delete をブロックしません プレフィックスルールは基になる実行可能ファイルではなく、リテラルコマンド文字列をマッチします 各バリアントの明示的なパターンを追加するか、PreToolUse フック または サンドボックス を使用して、ハード保証を取得します。

各設定サーフェスの完全なリファレンスについては、専用ページを参照してください：