SpyBara
Go Premium

debug-your-config.md 2026-10-01 23:59 UTC to 2026-10-02 22:59 UTC

This page contains 19 additions and 17 deletions.

2026
Fri 2 22:59

設定をデバッグする

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

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

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

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

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

特定のカテゴリの詳細を確認するには、続けて専用のコマンドを実行します。

コマンド 表示内容
/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 が特定の指示に従わない場合、問題は読み込まれたかどうかではなく、指示の書き方にある可能性が高いです。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 を実行して、現在のセッションに登録されているすべてのフックをイベント別にグループ化して一覧表示します。定義したフックが表示されない場合、Claude Code はそのフックを読み込んでいません。次の原因がないか確認してください：

  • フックがスタンドアロンファイルで定義されている。フックは設定ファイルの "hooks" キーの下に置きます。
  • matcher の値が単一の文字列ではなく配列になっている。Claude Code は、対話型セッションの開始時と claude doctor で、そのエントリを無効な設定として一覧表示します。配列が PreToolUse または PermissionRequest の下にある場合、そのファイルの他のフックも一切読み込まれません。

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

  • matcher フィールドは、複数のツール名をマッチするために | を使用する単一の文字列です。例えば "Edit|Write" です。, セパレータは同等であるため、"Edit,Write" は同じツールをマッチします。v2.1.191 より前では、カンマは正規表現評価にフォールスルーし、マッチャーは一致しないため、v2.1.191 をまだ使用していない場合は | を使用してください。
  • ツール名のスペルミスはマッチャーが何もマッチしないため、フックはサイレントに失敗します。

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 に影響を与える環境変数を探してから、トラブルシューティングを参照してください。

一般的な原因を確認する

ほとんどの設定の問題は、少数の場所とシンタックスのルールに遡ることができます。バグだと思う前に、以下を確認してください。

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

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