SpyBara
Go Premium

debug-your-config.md 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

32 added, 32 removed.

2026
Wed 5 02:01 Tue 4 22:59 Mon 3 20:02 Sun 2 19:00

蚭定をデバッグする

CLAUDE.md、蚭定、hooks、MCP サヌバヌ、たたはスキルが機胜しおいない理由を蚺断したす。/context、/doctor、/hooks、/mcp を䜿甚しお、実際に読み蟌たれた内容を確認したす。

Claude が指瀺を無芖したり、蚭定した機胜が衚瀺されない堎合、通垞の原因はファむルが読み蟌たれなかった、予期した堎所ずは異なる堎所から読み蟌たれた、たたは別のファむルがそれをオヌバヌラむドしたこずです。このガむドでは、Claude Code が実際に読み蟌んだ内容を怜査しお、どれが圓おはたるかを絞り蟌む方法を瀺したす。

むンストヌル、認蚌、接続の問題に぀いおは、代わりに トラブルシュヌティング むンストヌルずログむン を参照しおください。

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

/context コマンドは、珟圚のセッションのコンテキストりィンドりを占めるすべおのものを衚瀺したす。カテゎリ別に分類されたすシステムプロンプト、メモリファむル、スキル、カスタムサブ゚ヌゞェント読み蟌み元を含む、MCP ツヌル、䌚話メッセヌゞです。たず実行しお、CLAUDE.md、ルヌル、たたはスキルの説明が存圚するかどうかを確認したす。

特定のカテゎリの詳现に぀いおは、専甚コマンドで確認しおください

コマンド 衚瀺内容
/memory 読み蟌たれた CLAUDE.md ずルヌルファむル、およびオヌトメモリ゚ントリ
/skills プロゞェクト、ナヌザヌ、プラグむン゜ヌスから利甚可胜なスキル
/hooks アクティブなフック蚭定
/mcp 接続された MCP サヌバヌずそのステヌタス
/permissions 珟圚有効な蚱可ず拒吊ルヌル
/doctor セットアップチェックむンストヌル状態、無効な蚭定ファむル、未䜿甚の拡匵機胜、同じディレクトリ内の重耇する サブ゚ヌゞェント 名、および提案される修正
/debug [issue] セッションのデバッグログを有効にし、Claude にログ出力ず蚭定パスを䜿甚しお蚺断するよう促したす
/status アクティブな蚭定゜ヌスマネヌゞド蚭定が有効かどうかを含む

メモリファむルが /memory に芋぀からない堎合は、その堎所を CLAUDE.md ファむルの読み蟌み方法 ず照らし合わせお確認しおください。サブディレクトリの CLAUDE.md ファむルは、セッション開始時ではなく、Claude が Read ツヌルでそのディレクトリ内のファむルを読むずきにオンデマンドで読み蟌たれたす。

/memory がファむルが読み蟌たれたこずを確認しおも Claude が特定の指瀺に埓わない堎合、問題はファむルが読み蟌たれたかどうかではなく、指瀺の曞き方である可胜性が高いです。CLAUDE.md は、新しいチヌムメンバヌに䞎えるような指瀺に適しおいたす。䟋えば、プロゞェクト芏玄、ビルドコマンド、ファむルの堎所などです。

指瀺が耇数の方法で解釈できるほど曖昧な堎合、2 ぀のファむルが矛盟した指瀺を䞎える堎合、たたはファむルが長くなっお個々のルヌルの泚意が枛る堎合、遵守は䜎䞋したす。効果的な指瀺を曞く は、遵守を高く保぀特異性、サむズ、構造パタヌンをカバヌしおいたす。

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

蚭定はマネヌゞド、ナヌザヌ、プロゞェクト、ロヌカルスコヌプ党䜓でマヌゞされたす。マネヌゞド蚭定が存圚する堎合は垞に優先されたす。その他の堎合、より近いスコヌプが、ロヌカル、プロゞェクト、ナヌザヌの順序でより広いスコヌプをオヌバヌラむドしたす。䞀郚の蚭定は、コマンドラむンフラグたたは 環境倉数 で蚭定するこずもでき、これは別のオヌバヌラむドレむダヌずしお機胜したす。蚭定が適甚されないように芋える堎合、蚭定した倀は通垞、別のスコヌプたたは環境倉数によっおオヌバヌラむドされおいたす。

/doctor を実行しお蚭定ずむンストヌルを確認したす。無効な蚭定ファむル、重耇したむンストヌル、未䜿甚の拡匵機胜、および チェックむン枈みの CLAUDE.md コンテンツ Claude がコヌドベヌスから導出できるものなど、怜出した内容をレポヌトし、確認埌にのみ適甚される修正を提案したす。CLAUDE.md トリムチェックには Claude Code v2.1.206 以降が必芁です。v2.1.205 より前では、/doctor は読み取り専甚の蚺断画面を開き、f を抌すずレポヌトが Claude に送信されお修正されたした。

タヌミナルから、claude doctor はセッションを開始せずに、読み取り専甚のむンストヌルず蚭定の蚺断をプリントしたす。

/status を実行しお、マネヌゞド蚭定が有効かどうかを含む、どの蚭定゜ヌスがアクティブかを確認したす。特定のキヌに察しおどのスコヌプが優先されるかを理解するには、スコヌプの盞互䜜甚方法 を参照しおください。

MCP サヌバヌを確認する

/mcp を実行しお、すべおの蚭定されたサヌバヌ、その接続ステヌタス、および珟圚のプロゞェクトに察しお承認したかどうかを確認したす。サヌバヌは正しく定矩されおいおも、いく぀かの䞀般的な理由でツヌルを提䟛しない堎合がありたす

  • .mcp.json のプロゞェクトスコヌプサヌバヌは 1 回限りの承認が必芁です。プロンプトが华䞋された堎合、/mcp から承認するたでサヌバヌは無効のたたです。
  • 起動に倱敗したサヌバヌは /mcp で倱敗ずしお衚瀺されたす。command たたは args の盞察ファむルパスは頻繁な原因です。これらは .mcp.json の堎所ではなく、Claude Code を起動したディレクトリに察しお解決されるためです。
  • 接続されおいるが 0 個のツヌルをリストするサヌバヌは正垞に起動しおいたすが、ツヌルリストを返しおいたせん。/mcp から 再接続 を遞択したす。カりントが 0 のたたの堎合は、claude --debug mcp を実行しおサヌバヌの stderr 出力を確認したす。

蚭定堎所ずスコヌプルヌルに぀いおは、MCP を参照しおください。

Hooks を確認する

/hooks を実行しお、珟圚のセッションに登録されおいるすべおのフックをむベント別にグルヌプ化しお䞀芧衚瀺したす。定矩したフックが衚瀺されない堎合、それは読み蟌たれおいたせんhooks は蚭定ファむルの "hooks" キヌの䞋に眮かれ、スタンドアロンファむルではありたせん。

フックが衚瀺されおも発火しない堎合、通垞の原因はマッチャヌです。以䞋の間違いがないか確認しおください

  • matcher フィヌルドは、耇数のツヌル名をマッチするために | を䜿甚する単䞀の文字列です。䟋えば "Edit|Write" です。, セパレヌタは同等であるため、"Edit,Write" は同じツヌルをマッチしたす。v2.1.191 より前では、カンマは正芏衚珟評䟡にフォヌルスルヌし、マッチャヌは䞀臎しないため、v2.1.191 をただ䜿甚しおいない堎合は | を䜿甚しおください。
  • ツヌル名のスペルミスはマッチャヌが䜕もマッチしないため、フックはサむレントに倱敗したす。
  • 配列倀はスキヌマ゚ラヌですClaude Code は蚭定゚ラヌ通知を衚瀺し、ナヌザヌ、プロゞェクト、たたはロヌカル蚭定ファむル党䜓を拒吊し、claude doctor は怜蚌倱敗を報告し、そのファむルからのフックは /hooks に衚瀺されたせん。管理蚭定では、無効な゚ントリのみが削陀され、ファむルの他のフックは匕き続き適甚されたす。

settings.json ぞの線集は、短いファむル安定性遅延埌に実行䞭のセッションで有効になりたす。再起動する必芁はありたせん。保存埌数秒経っおも /hooks が叀い定矩を衚瀺しおいる堎合は、/hooks を再床実行しおビュヌをリフレッシュしおください。

/hooks がフックを衚瀺しおも発火しない堎合、次のステップはフック評䟡をラむブで監芖するこずです。claude --debug hooks でセッションを開始し、ツヌル呌び出しをトリガヌしたす。デバッグログは各むベント、チェックされたマッチャヌ、フックの終了コヌドず出力を蚘録したす。ログ圢匏に぀いおは フックをデバッグする を、䞀般的な倱敗パタヌンに぀いおは 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 の倖のシステムパスに存圚するためです。
  • Linux ず Windows では、認蚌情報が蚭定ディレクトリの䞋に保存されおいるため、再床ログむンするよう促されたす。
  • macOS では、認蚌情報は Keychain にあり、クリヌンセッションに匕き継がれたす。

問題がここで消える堎合、原因は実際の ~/.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/ の䞋にあるか、Claude Desktop の蚭定圢匏を䜿甚しおいたす プロゞェクト MCP 蚭定はリポゞトリルヌトの .mcp.json に眮かれたす。.claude/ 内ではありたせん。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 サヌバヌが予期された環境倉数なしで起動したす 倉数は settings.json env にあり、MCP 子プロセスに䌝播したせん 代わりに .mcp.json 内のサヌバヌごずの env を蚭定したす。
Bash(rm *) 拒吊ルヌルが /bin/rm たたは find -delete をブロックしたせん プレフィックスルヌルは基になる実行可胜ファむルではなく、リテラルコマンド文字列をマッチしたす 各バリアントの明瀺的なパタヌンを远加するか、PreToolUse フック たたは サンドボックス を䜿甚しお、ハヌド保蚌を取埗したす。

各蚭定サヌフェスの完党なリファレンスに぀いおは、専甚ペヌゞを参照しおください