Claude Codeの設定が効かないときの確認順序 — 保存先・優先関係・権限ルール

設定が効かないように見えるときは、いきなり優先順位の表へ進まず、次の順に原因を狭めます。

保存先は合っているか
  → 今のセッションがファイルを読んだか
    → そのキーをそのscopeで設定できるか
      → 通常値か、リストか、権限ルールか
        → 起動時指定・環境変数・managed settingsが関係するか
          → 今のセッションへ反映済みか

症状から最初の確認先を選ぶ

症状	最初に見る場所	結果の読み方	次の判断
どのprojectでも同じ設定だけ効かない	`~/.claude/settings.json` と `/status`	User settingsが表示されなければ、保存先かJSONを見直す	表示されるならkeyのscopeと上位sourceを見る
あるrepositoryだけ期待と違う	`.claude/settings.json`、`.claude/settings.local.json`、起動directory	共有設定とlocal設定の両方が読まれ得る	同じkeyの通常値か、mergeされるlistかを分ける
「許可したはず」なのに毎回尋ねられる	`/permissions`	`allow`だけでなく、同じ操作へ一致する`ask`や`deny`も見る	`deny → ask → allow`の順で最初に一致するruleを直す
自分では変更できない値がある	`/status` のmanaged source	managed settingsが同じkeyを設定していれば一般利用者側では上書きできない	管理者へ対象keyとsourceを伝える
保存直後も動作が変わらない	keyのreferenceと現在のsession	多くの設定は再読込されるが、起動時だけ読むkeyもある	対応するcommandを使うかsessionを再起動する

/statusにファイル名が出たことは「そのファイルを読んだ」証拠です。その中のすべてのkeyが採用された証拠ではありません。

保存先は「誰に効かせるか」で決める

保存先	適用範囲	主な用途
`~/.claude/settings.json`	このmachine上の自分、全project	個人の既定値や個人のpermission rule
`.claude/settings.json`	そのfolderで作業する人	commitして共有するteam設定
`.claude/settings.local.json`	そのprojectの自分	commitしない個人overrideと、許可promptから保存したrule
managed settings	組織が配布した対象	security policyやcompliance上の強制値
`--settings`、個別flag	起動した1 session	保存せずに試す値

共有project設定は、sessionのprimary working directoryにある.claude/settings.jsonから読みます。repository rootの設定を使うなら、まずrootから起動します。/cd後に移動先のproject設定を読み直す挙動はClaude Code v2.1.246以降です。

.claude/settings.local.jsonの場所はversion差があります。v2.1.211以降、git repository内で起動すると、原則としてrepository rootにあるlocal fileを使います。worktreeではmain checkout側のrootを使います。以前のversionが起動directoryへ残したlocal fileも読む場合があるため、古い環境から更新した後は/statusでsourceを確かめます。

「読み込んだ」と「その値が有効」は別に見る

Claude Code内で/statusを開き、Setting sourcesに想定したUser、Project、Project local、Managedのsourceがあるか見ます。
terminalでclaude doctorを実行し、壊れたJSON、受け入れられなかった値、無効なruleを確認します。
権限なら/permissionsを開き、現在有効なruleと、それぞれの保存元を確認します。
keyごとの公式referenceで、そのkeyをUser、Project、Local、Managedのどこへ置けるかを確認します。
同じkeyを起動flag、--settings、shellの環境変数が設定していないかを確認します。

設定ファイルはstrict JSONです。// commentや末尾commaは使えません。JSON全体や値の形式が不正な場合はSettings Error、個別ruleなど一部だけが不正な場合はSettings Warningになり、残りが使われる場合があります。schemaの警告だけで判断せず、Claude Code自身の診断結果も見ます。公式docsは、公開schemaが最新CLIより遅れる場合があると説明しています。

通常値は上書き、listは原則追加

同じ通常keyを複数の場所で設定した場合は、次の順で上にある値が採用されます。

managed settings
  ↓
command line（--settingsや個別flag）
  ↓
.claude/settings.local.json
  ↓
.claude/settings.json
  ↓
~/.claude/settings.json

ただし、この図だけで全設定を説明することはできません。

shellの環境変数は独立した一段ではなく、対応するkeyごとにどちらを優先するかが決まります。
permissions.allowのようなlistは、複数scopeの項目を原則として結合します。
fallbackModel、modelPicker、availableModels、modelSettingsには個別の結合規則があります。
security上の一部keyは、下位scopeにある厳しい値がmanaged valueより優先されます。
keyによってはproject fileから設定できず、UserまたはManagedだけを受け付けます。

「local fileはproject fileより上だから、配列も丸ごと置き換わる」と考えないことが重要です。まずkeyの型と、そのkey固有のScope欄を見ます。

権限ルールは上書き図ではなく、全ruleの評価で考える

権限のallow、ask、denyは、通常値のように「localがprojectを消す」関係ではありません。読み込まれたscopeのruleを合わせ、同じ操作へ一致するruleがあると次の順で判定します。

deny に一致 → 実行しない
ask に一致  → 人へ確認する
allow に一致 → 確認なしで許可する

ruleの具体性はこの順序を変えません。たとえば広いdenyに一致する操作を、より狭いallowで例外にすることはできません。同様に、askへ一致する操作は、より具体的なallowがあっても確認されます。

共有projectのpermissions.allowはworkspace trustを得るまで適用されません。一方、共有projectのdenyとaskは先に適用されます。local fileへ保存したallowがあるのにpromptが続く場合は、別scopeのaskまたはdeny、trust状態、ruleが実際のcommand表記へ一致しているかを見ます。

CLAUDE.mdは作業方針を自然言語で伝える仕組みです。permission ruleの代わりではありません。CLAUDE.mdへ「このcommandを実行しない」と書いても、強制的なsecurity boundaryにはなりません。

代表的な切り分け

Projectだけmodelが戻る

/statusでProject localとProject settingsが読まれているかを見る。
.claude/settings.local.json、.claude/settings.json、~/.claude/settings.jsonのmodelを比較する。
起動時の--model、--settings、ANTHROPIC_MODELを確認する。
managed settingsがmodelや利用可能modelを制限していれば、利用者側で解除せず管理者へ確認する。

保存した許可が次のtool callでも使われない

/permissionsで保存先とrule文字列を確認する。
同じ操作に一致するdenyまたはaskがないかを見る。
共有projectのallowなら、folderをtrustしたかを見る。
Bash ruleはcommand文字列へ一致するため、別pathやsh -cなど別の呼び方を同じprogramとして一括制御できないことを確認する。

permission ruleだけでprogram全体を安全に囲めるとは限りません。管理者の制限を迂回したり、ruleを広げてpromptを消したりするのではなく、強制が必要なら公式docsが案内するsandboxやhookの責務を管理者と分けます。

設定fileは表示されるのに一部keyだけ効かない

claude doctorで、そのentryが拒否されていないかを見る。
公式settings referenceのScope欄で、その保存先が対応しているかを見る。
同じkeyの上位scope、flag、環境変数を確認する。
listならmerge規則、permissionならdeny → ask → allowへ切り替えて考える。
起動時だけ読むkeyならsessionを再起動する。

多くのsettings file変更はrunning sessionへ再読込されますが、modelなど一部は別のcommandで切り替えるか、次のsession開始時に反映されます。managed sourceも配布方式ごとに反映間隔が違います。保存したという事実だけで、今のsessionへ反映済みとは判断しません。

自分で直す範囲と管理者へ渡す範囲

自分のUser／Project local設定、JSONエラー、対応scope、起動flag、環境変数は自分で切り分けられます。共有project設定の変更はteam reviewが必要です。/statusにmanaged sourceがあり、同じkeyやpermission policyを強制している場合は、一般利用者のfileで上書きせず、次を管理者へ渡します。

Claude Codeのversion
起動directoryと、repository／worktreeの別
/statusに表示された設定source名
問題のkeyまたはpermission rule
期待した結果と実際の結果
claude doctorに出たerrorまたはwarning

この情報があれば、「ファイルを読んでいない」「keyのscope外」「別sourceが優先」「permission評価」「version差」を分けて確認できます。