Claude Code で、正しく書いたのに何も起きない設定の全一覧
.claude/ の設定でいちばん時間を取られるのは、間違いが画面に出ないことです。
JSON は正しい。キー名も合っている。起動しても警告が出ず、--debug にも出ません。
ただ動きません。
公式ドキュメントが「無視される」「スキップされる」「効かない」と明記している 場所を、数えて並べました。推測は入れていません。
数
| どこ | 何件 | 何が起きるか |
|---|---|---|
hook の matcher |
イベント 33 種のうち 10 種 | matcher が黙って無視され、毎回走る |
hook の if |
評価されるのは 5 種だけ | それ以外に書くと、そのハンドラは一度も走らない |
| 設定キーのスコープ | 223 個のうち 71 個 | 書いた場所によっては何もしない |
| 非推奨の設定キー | 4 個 | うち1つは真偽が反転している |
| 権限ルール | 5 通り | 読み込まれて、そのまま何もしない |
| サブエージェントのファイル | 5 条件 | ファイルごと飛ばされ、セッションには出ない |
.mcp.json |
2 か所 | type の無い url は stdio 扱いで飛ばされ、timeout: 500 は約28時間になる |
共通しているのは、失敗がこちら側に返ってこないことです。 返ってくるものが無いので、手元でいくら実験しても届きません。
hook
matcher を書いても黙って無視されるイベントが10種あります。
エラーになりません。絞ったつもりで、毎回走ります。
CwdChanged UserPromptSubmit PostToolBatch Stop TeammateIdle
TaskCreated TaskCompleted WorktreeCreate WorktreeRemove MessageDisplay
if は逆の失敗をします。評価されるのはツール系の5種だけです。
PreToolUse PostToolUse PostToolUseFailure PermissionRequest PermissionDenied
それ以外のイベントに if を書くと、そのハンドラは一度も走りません。
matcher は広すぎる方へ、if は動かない方へ。どちらも静かに。
イベント33種ごとの対照表はこちらです。
https://quintetkit.github.io/reference/claude-code-hooks.html
設定キー
設定キーにはどのファイルから書けば効くかが決まっています。
| スコープ | 件数 | 効く場所 |
|---|---|---|
Managed |
39 | 組織が配る管理設定からのみ |
User or managed |
23 | ~/.claude/settings.json か管理設定からのみ |
User, local, or managed |
3 | settings.local.json からは効くが、settings.json からは効かない |
Global config |
6 | ~/.claude.json からのみ |
| 計 | 71 | |
Any file |
152 | どこに書いても効く |
3行目が厄介です。 settings.local.json に書いた本人には効いて、
共有した settings.json に移すと効かなくなります。
「自分の環境では動く」の正体がこれになりえます。
入れ子のキーは、点つなぎの完全な名前でスコープが決まります。
制限されているのは sandbox.network.strictAllowlist で、sandbox ではありません。
上の階層だけ見ていると、点つなぎの20個（うち sandbox.* が12個）を丸ごと見落とします。
71個の全一覧はこちらです。
https://quintetkit.github.io/reference/claude-code-settings-scope.html
非推奨のキーは4つ
| 書いてあるもの | 置き換え先 |
|---|---|
ignorePatterns |
permissions.deny |
includeCoAuthoredBy |
attribution |
disableArtifact |
enableArtifact |
voiceEnabled |
voice.enabled |
disableArtifact は真偽が反転します。 disableArtifact: false と
enableArtifact: false は逆の意味です。名前を置き換えるだけだと、設定が反転します。
権限ルール
permissions に書いても、エラーにならず何もしない書き方が5通りあります。
| 書き方 | 何が起きるか |
|---|---|
"*" / "B*" / "mcp__*" を allow に |
スキップされ、何も自動承認しない |
Write(...) NotebookEdit(...) Glob(...) MultiEdit(...) のパス指定 |
受け付けられるが参照されない |
Bash(command:...) のように本体の入力をパラメータ指定 |
無視される（9ツールが該当） |
括弧つきの mcp__ ルール |
読み込み時にスキップ |
allow で * のうしろに字が続く |
効くが、見た目より広く許可する |
最後のものが一番危ないです。
Bash(git log *) → git log から始まるコマンド
Bash(git * main) → git の全サブコマンド。git push origin main も、git -c も
Bash(* --version) → あらゆるプログラム
git -c は git に別のプログラムを起動させます。
「1つのコマンドを許した」つもりの1行が、そこまで開きます。
詳細はこちらです。
https://quintetkit.github.io/reference/claude-code-permission-rules.html
サブエージェントのファイル
.claude/agents/*.md は、frontmatter に問題があると飛ばされます。
そしてセッションには何も出ません。 理由はデバッグログにだけ出ます。
nameが無い- 開きの
---が1行目でない nameが-で始まる、または:を含むnameはあるがdescriptionが無い- YAML として壊れている
書ける18項目と、cacheTtl の置き場所（experimental の中）はこちらです。
https://quintetkit.github.io/reference/claude-code-subagent-frontmatter.html
.mcp.json
type を書き忘れた url は、http の既定になるのではなく stdio サーバとして読まれます。
stdio には command が要るので、そのサーバは飛ばされます。
そして timeout は1000 未満の値が無視されます。
無視されたあとは MCP_TOOL_TIMEOUT に落ち、それも未設定なら
その既定である約28時間になります。
"timeout": 500 // 500ms ではない。約28時間
短くしたつもりが、事実上の無制限になります。
トランスポート別の必須項目、sse が非推奨であること、
untrusted なフォルダでは承認設定が無視されることはこちらです。
https://quintetkit.github.io/reference/claude-code-mcp-json.html
まとめて検査する
上の全部を機械で見つけられます。
npx @quintetkit/ccheck
warn .claude/settings.json:63
`autoMode` applies from user or managed settings only. It has no effect from this file.
why: https://code.claude.com/docs/en/settings-reference
指摘には必ず出典が付きます。 根拠を示せないものはルールにしていません。
逆に、あえて検査していないものもあります。
- 未知のキー — 公式が「スキーマは最新 CLI に遅れる」と明記しているので、 新機能を使うたびに誤検出します
modelやcolorの値の一覧 — 網羅リストが文書化されていない、 あるいは値が増えるたびに誤検出しますdeny/askのツール名が実在するか — 判定には最新のツール一覧が要ります。 スナップショットしか持てないので、新しいツールが出るたびに誤検出します
誤検出を1件出した時点で、出力ごと読まれなくなります。 区別できないものは、区別できないと言って通します。
出典
- https://code.claude.com/docs/en/hooks
- https://code.claude.com/docs/en/settings-reference
- https://code.claude.com/docs/en/permissions
- https://code.claude.com/docs/en/sub-agents
- https://code.claude.com/docs/en/mcp
数はすべて 2026-09-04 に取得したスナップショットから数えたものです。