Claude Codeのsettings.json｜5階層のどこに書けば効くか

「.claude/settings.json に書いたはずのルールが、なぜか効かない」。Claude Codeをチームで使いはじめた方から、いちばん多く届く相談がこれです。

書き方を間違えたわけではないことがほとんどです。同じキーが、別の置き場所にも書かれている。それだけのことが起きています。Claude Codeの設定ファイルは1か所ではなく、置き場所が5つに分かれているからです。

この記事では、優先順位の決まり方と、値の型によって競合の結果が変わる仕組みを公式ドキュメントから整理します。そのうえで、チームに配る設定と手元だけの設定をどこで分けるかまで持っていきます。

この記事は、AIエージェントを自分の手で動かしている方の会話をはさみながら進めます。若葉さんが言葉の意味を、高梨課長が運用の手ざわりを聞き、鈴木さんが答えます。

01Claude Codeのsettings.jsonは5つもあって、AIエージェントはどれを読んでいるんですか？

Claude Codeの設定は、ユーザー・プロジェクト共有・ローカル・コマンドライン引数・Managedという5つの置き場所に分かれています。分かれている理由は「誰に効かせたい設定なのか」が置き場所ごとに違うからです。

若葉さん

若葉さんの発言

5つもあるんですね…。設定ファイルって、プロジェクトの.claude/に1つ置けば済むものだと思っていました。

鈴木さん

鈴木さんの発言

そう思って書きはじめると、たいてい迷子になりますね。5つは機能の違いではなくて、効かせたい相手の違いで分かれているんですよ。自分だけなのか、チーム全員なのか、組織全体なのか。そこが違うだけです。

Managed以外の4スコープは、ファイルパスが決まっています。ユーザー設定は~/.claude/settings.json、プロジェクト共有設定は.claude/settings.json、ローカル設定は.claude/settings.local.jsonです。コマンドライン引数は、セッション起動時に--settingsで渡します。

Managedだけは事情が違います。サーバー配信・MDM・ファイル配置（macOSは/Library/Application Support/ClaudeCode/）と、複数の経路を持ちます。どの経路で配信されても、開発者側からは上書きできません（出典: Claude Code公式ドキュメント）。

02settings.jsonの優先順位は、エージェントが後から書いた方を選ぶわけではないんですか？

ここを誤解したまま設定を足していくと、いつまでも意図した動きになりません。Claude Codeは、同じキーが複数のsettings.jsonにあっても、書いた時刻の新しさでは選びません。優先順位はスコープの種類だけで固定されています（出典: Claude Code公式ドキュメント）。

順位は固定なので、ユーザー設定をどれだけ丁寧に書き直しても、プロジェクト共有設定の値には勝てません。逆にプロジェクト側からも、Managedの値は一切上書きできません（出典: 同）。

つまり「効かないから書き足す」は、たいていの場合、遠回りです。書き足す前に、上の層に同じキーが無いかを見に行くほうが早く終わります。

03Claude Codeのsettings.jsonを、AIエージェントが本当に読んでいるかはどこで分かりますか？

順位の話に入る前に、そもそも読み込まれているかを確かめます。読み込まれていないファイルは、いくら書いても順位の勝負に参加していません。

まず、非Managedの3スコープが実在するかを見ます。

ls -la ~/.claude/settings.json
ls -la .claude/settings.json
ls -la .claude/settings.local.json

3つとも存在しなくてもエラーにはなりません。存在しないスコープは「そのスコープには何も定義されていない」という扱いになり、優先順位の判定から静かに外れます（出典: 同）。エラーが出ないので、無いことに気づけないのがやっかいなところです。

04/statusに出ないsettings.jsonは、AIエージェントが読んでいないということですか？

はい、そう考えて差し支えありません。読み込まれた設定ソースは、起動中のセッションで/statusを実行すると「Setting sources」という行に一覧表示されます（出典: 同）。この一覧に出ないスコープは、そのセッションでは1件も読み込まれていません。

バージョンの確認はclaude --versionです。Managed設定は組織のIT担当者が配布する前提のため、開発者のターミナルからは通常見えません。存在すれば/statusの一覧に、配信経路つきで表れます。構造そのものは$schemaフィールドで検証できます（出典: 同）。

05同じ許可をsettings.jsonに書いたのに、AI社員の片方だけ効かないのはなぜですか？

ここが本記事の核心です。優先順位は「勝った1つのファイルが設定を丸ごと決める」という仕組みではありません。キーの型によって、競合したときの挙動が変わります（出典: Claude Code公式ドキュメント）。

若葉さん

若葉さんの発言

同じsettings.jsonに書いたのに、片方は上書きされて、もう片方は両方とも生きている…。書き方を間違えたんでしょうか。

鈴木さん

鈴木さんの発言

いえ、たぶん正しく書けています。値が1つしか置けない棚と、いくつでも入る箱があると思ってください。棚は上の層の人が置いたものだけが残って、箱は全員のぶんが入るんです。

公式ドキュメントはspinnerTipsEnabledを例に挙げています。ユーザー設定でtrue、プロジェクト共有設定でfalseなら、プロジェクトの値が適用されます（出典: 同）。上位が勝ち、下位は消えます。

06配列値が合算されると、AIエージェントに配ったsettings.jsonの許可はどうなりますか？

配列値は逆に足し算になります（出典: 同）。プロジェクト共有設定とユーザー設定を同時に読み込む例で確かめます。

// .claude/settings.json（プロジェクト共有）
{
  "permissions": {
    "deny": ["Bash(terraform apply*)"]
  }
}

// ~/.claude/settings.json（ユーザー）
{
  "permissions": {
    "deny": ["Bash(curl *)"],
    "allow": ["WebFetch(domain:example.com)"]
  }
}

この2つを同時に読み込むと、denyは合算され、terraform applyとcurlの両方が拒否されます。allowのWebFetchは優先順位を比べる相手がいないため、そのまま有効になります。

07配列なのに合算されないsettings.jsonの設定は、AIエージェントの何を守るためですか？

配列はすべて合算される、と覚えると次でつまずきます。順序に意味を持つ配列は、合算すると意味が壊れるためです。

代表例がfallbackModelです。ユーザー設定とプロジェクト共有設定の両方に書いた場合を見ます。

// ~/.claude/settings.json（ユーザー）
{ "fallbackModel": ["claude-opus-5", "claude-haiku-4-5"] }

// .claude/settings.json（プロジェクト共有・こちらが優先）
{ "fallbackModel": ["claude-sonnet-5"] }

プロジェクト共有の方が優先順位で上のため、最終的なfallbackModelは["claude-sonnet-5"]という1件だけのチェーンになります。ユーザー設定の2件は合算されず、丸ごと無視されます（出典: 同）。

もう1種類、特定のスコープでは書いても何も起きない値があります。defaultMode: autoはプロジェクト設定・ローカル設定では無視され、~/.claude/settings.jsonに書く必要があります（出典: 同）。skipDangerousModePermissionPromptも同じ理由でプロジェクト設定では無視されます。

08denyは、AI導入の安全弁としてsettings.jsonの優先順位より強いんですか？

権限ルール（allow・ask・deny）には、階層の優先順位より強い決まりがあります。どのスコープのdenyも、他のどのスコープのallowより先に評価されます（出典: Claude Code公式ドキュメント）。

高梨課長

高梨課長の発言

ということは、私がユーザー設定で止めておいた操作を、プロジェクト側の許可で開けてしまうことは無いんですね。

鈴木さん

鈴木さんの発言

はい、そこは逆向きも同じです。チームで止めた操作を、個人の許可で開けることもできません。止める側が先に読まれる、と覚えておくと事故が減りますよ。

ユーザー設定で許可した操作でも、プロジェクト共有設定が拒否すれば拒否されたままです。逆に、ユーザー設定の拒否をプロジェクト側の許可で覆すこともできません。allowとdenyは同じ土俵で戦っていない、と考えると分かりやすくなります。

権限そのものの配分（何をallowにして、何をaskで止めるか）は、この記事の範囲を越えます。配分の考え方と設定例は『Claude Codeの権限設定｜AIエージェントに任せる範囲と3列の配分』が扱います。危険操作を実行前に遮断する仕組みは『Claude CodeのPreToolUseで危険コマンドを遮断する4つの判定』が扱います。

09チーム共有と個人用で、AI社員のsettings.jsonはどこに線を引くんですか？

階層と競合ルールが分かると、次に迷うのは配置です。公式ドキュメントは、4つの非管理スコープの使い分けを示しています（出典: 同）。

高梨課長

高梨課長の発言

危険な操作の拒否ルールは、とりあえず自分の手元に書いておけばいいでしょうか。まずは自分の環境で試したいので。

鈴木さん

鈴木さんの発言

試すあいだはそれで大丈夫です。ただ、試し終わったら移してください。手元に置いたままだと、守られているのは高梨さんの環境だけなんですよ。

.claude/settings.local.jsonには、Claude Codeが「今後は聞かない」を選んだ操作を自動保存する役割もあります（出典: 同）。この自動保存は個人の作業ログに近いもので、チームへそのまま配ると、意味の薄いルールが積み重なっていきます。

配置を誤ると実害が出ます。危険な拒否ルールをローカルだけに書くと、自分のマシンでしか効きません。他の担当者は無防備なままです。

10settings.jsonを直したのにAIエージェントの動きが変わらないのは、どこが原因ですか？

型でも順位でも説明がつかないときは、次の4つを疑います。どれも設定が壊れているわけではなく、反映のされ方の問題です。

落とし穴1：プロジェクト共有のallowルールを書いたのに効かない。.claude/settings.jsonのallowルールは、そのワークスペースの信頼ダイアログを承認するまで適用されません（出典: 同）。「動かない」と感じたら、まずここを確認します。

落とし穴2：defaultMode: autoをプロジェクト設定に書いても発動しない。前章で触れたとおり、autoモードはプロジェクトやローカル設定に書くと無視されます。

落とし穴3：.claude/settings.local.jsonの置き場所がバージョンで変わる。v2.1.211より前はセッションを開始したディレクトリに保存され、v2.1.211以降はリポジトリのルートに統一されました（出典: 同）。古いバージョンで複数の階層から使っていた場合、ローカル設定が分裂して残っている可能性があります。

落とし穴4：設定を直したのに動きが変わらない。permissionsとhooksは変更を検知して自動で再読み込みされますが、modelとoutputStyleはセッション開始時の1回だけです（出典: 同）。設定が壊れているのではなく、反映のタイミングが違うだけです。

11自分の環境でsettings.jsonが想定どおりか、Claude CodeのAI活用を広げる前にどう確かめますか？

読んで分かった気になっただけでは、自分の環境で成立しているかは分かりません。手元で確かめてから、任せる範囲を広げます。

高梨課長

高梨課長の発言

ここまでの内容を、自分の環境でも同じかどうか確かめたいです。何を見れば「合っている」と言えますか。

鈴木さん

鈴木さんの発言

判定できる形にしておくと後が楽です。スカラー値で上書きを1回、配列値で合算を1回。この2つが目の前で再現できれば、あとは同じ理屈で追えますよ。

判定基準は次の4項目です。

• /statusを実行し、「Setting sources」に想定したスコープがすべて表示されている
• スカラー値（例：defaultMode）を2つのスコープに別の値で書き、優先順位が高い方が反映されている
• 配列値（例：permissions.deny）を2つのスコープに別の値で書き、両方が合算されて効いている
• プロジェクト共有のallowルールを書いた直後は、ワークスペース信頼ダイアログを承認してから確認している

4項目とも期待どおりなら、この記事の内容は自分の環境でも成立しています。ズレた場合は、まず/statusの一覧を見ます。そこに出ていなければJSON構文エラーを疑い、claude doctorで詳細を確認します（出典: 同）。

なお、この記事は置き場所と優先順位に絞って扱いました。初期設定全体の観点は『Claude Codeの初期設定｜AIエージェントに任せる前の4観点』が扱います。

12よくある質問

13まとめ｜今日やる3つのこと

優先順位はスコープの種類だけで決まり、書いた時刻の新しさは関係しません。競合の結果は値の型で変わり、スカラー値は上位が勝ち、配列値は合算されます。denyだけは階層の外側にいて、どこか1か所で止めれば止まったままです。この3つで、「効かない」に出会ったときの調べ方が決まります。