> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 設定をデバッグする

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

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

インストール、認証、接続の問題については、代わりに [トラブルシューティング インストールとログイン](/docs/ja/troubleshoot-install) を参照してください。

<h2 id="see-what-loaded-into-context">
  コンテキストに読み込まれた内容を確認する
</h2>

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

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

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

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

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

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

<Note>
  CLAUDE.md と権限は異なる問題を解決します。CLAUDE.md は Claude にプロジェクトの仕組みを伝えるため、良い決定を下します。[権限](/docs/ja/permissions) と [hooks](/docs/ja/hooks) は Claude が何を決定するかに関わらず制限を強制します。CLAUDE.md は「ここではこのようにしています」に使用します。権限または hooks は、セキュリティ境界と、保証が必要な絶対に起こってはいけないことに使用します。
</Note>

<h2 id="check-resolved-settings">
  解決された設定を確認する
</h2>

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

`/doctor` を実行して設定とインストールを確認します。無効な設定ファイル、重複したインストール、未使用の拡張機能、および {/* min-version: 2.1.206 */}チェックイン済みの `CLAUDE.md` コンテンツ Claude がコードベースから導出できるものなど、検出した内容をレポートし、確認後にのみ適用される修正を提案します。`CLAUDE.md` トリムチェックには Claude Code v2.1.206 以降が必要です。v2.1.205 より前では、`/doctor` は読み取り専用の診断画面を開き、`f` を押すとレポートが Claude に送信されて修正されました。

ターミナルから、`claude doctor` はセッションを開始せずに、読み取り専用のインストールと設定の診断をプリントします。

`/status` を実行して、マネージド設定が有効かどうかを含む、どの設定ソースがアクティブかを確認します。特定のキーに対してどのスコープが優先されるかを理解するには、[スコープの相互作用方法](/docs/ja/settings#how-scopes-interact) を参照してください。

<h2 id="check-mcp-servers">
  MCP サーバーを確認する
</h2>

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

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

設定場所とスコープルールについては、[MCP](/docs/ja/mcp) を参照してください。

<h2 id="check-hooks">
  Hooks を確認する
</h2>

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

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

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

`settings.json` への編集は、短いファイル安定性遅延後に実行中のセッションで有効になります。再起動する必要はありません。保存後数秒経っても `/hooks` が古い定義を表示している場合は、`/hooks` を再度実行してビューをリフレッシュしてください。

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

<h2 id="test-against-a-clean-configuration">
  クリーン設定に対してテストする
</h2>

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

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

```bash theme={null}
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
```

クリーンセッションには、ユーザーまたはプロジェクト設定、hooks、MCP サーバー、plugins、またはメモリがありません。

* マネージド設定は、組織がそれらをデプロイする場合でも適用されます。これらは `~/.claude` の外のシステムパスに存在するためです。
* Linux と Windows では、認証情報が設定ディレクトリの下に保存されているため、再度ログインするよう促されます。
* macOS では、認証情報は Keychain にあり、クリーンセッションに引き継がれます。

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

<h2 id="check-common-causes">
  一般的な原因を確認する
</h2>

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

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

<h2 id="related-resources">
  関連リソース
</h2>

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

* **[`.claude` ディレクトリリファレンス](/docs/ja/claude-directory)**: すべての設定ファイルの場所とそれを読むもの
* **[設定](/docs/ja/settings)**: 優先順位と完全なキーリスト
* **[Hooks リファレンス](/docs/ja/hooks)**: イベント名、ペイロード、`--debug hooks` 出力形式
* **[MCP](/docs/ja/mcp)**: サーバー設定、承認、`/mcp` 出力
* **[インストールとログインのトラブルシューティング](/docs/ja/troubleshoot-install)**: `command not found`、PATH、認証の問題
* **[トラブルシューティング](/docs/ja/troubleshooting)**: パフォーマンス、ハング、検索の問題