設定レイヤーとは?Claude Codeの設定の優先順位

設定が「何段にも積み重なっている」という話

Claude Codeの設定は、1つのファイルだけで決まるわけではありません。組織が配った設定、プロジェクトの設定、自分だけの設定……といった複数の場所に散らばっていて、それらが重なり合って最終的な動作が決まります。この重なりの構造を 設定レイヤー(Settings layers) と呼びます。

はじめてこの仕組みに触れたとき、「あれ、settings.jsonをいじったのに反映されない」と混乱する人はけっこう多いです。だいたいの原因は、自分が編集したファイルより優先度の高いレイヤーが、別の場所で値を上書きしていることです。

服の重ね着で考えてみる

イメージとしては服の重ね着が近いです。一番下にインナー(ユーザー設定)を着て、その上にシャツ(プロジェクト設定)、さらにジャケット(ローカル設定)を羽織る。外から見えるのは一番外側に着ているものです。インナーの色をどれだけ変えても、ジャケットで完全に隠れていれば見た目は変わりません。

設定も同じで、同じ項目を複数のレイヤーで指定した場合、外側=優先度の高いレイヤーの値が勝ちます。

優先順位はこの順番

優先度が高い順に並べると次のようになります。

優先度	レイヤー	どこにあるか
1(最も強い)	組織のmanaged policy	組織が配布する管理者向け設定
2	コマンドライン引数	Claude Code起動時に渡すオプション
3	ローカル設定	.claude/settings.local.json
4	プロジェクト設定	.claude/settings.json
5(最も弱い)	ユーザー設定	~/.claude/settings.json

一番上のmanaged policyは、会社や組織が「これは絶対に守ってほしい」というルールを配るためのものです。個人がプロジェクト設定で書き換えても、こちらが優先されます。逆に一番下のユーザー設定は、自分のマシン全体に効かせたい「デフォルトの好み」を置く場所です。

真ん中あたりにある2つのファイルの違いも押さえておくと便利です。.claude/settings.json はプロジェクトのリポジトリに入れてチーム全員で共有するもの、.claude/settings.local.json は自分のマシンでだけ効かせたい上書き用、という住み分けになっています。名前に local が付いているほうが強い、と覚えておくといいでしょう。

「上書き」と「マージ」の2種類がある

ここが少しややこしいポイントなのですが、重なり方には2種類あります。

スカラー値(単一の値) の場合は、上位レイヤーが下位を上書きします。同じキーに別の値が入っていたら、優先度の高いほうだけが残ります。さっきの重ね着の話そのままです。

配列(リスト形式の値) の場合は挙動が違って、レイヤーをまたいでマージされます。つまり上書きして消えるのではなく、各レイヤーの要素が合わさった状態になります。

具体例で見てみます。

// ~/.claude/settings.json(ユーザー設定)
{
  "someList": ["A", "B"]
}

// .claude/settings.json(プロジェクト設定)
{
  "someList": ["C"]
}

この場合、配列はマージされるので、結果は ["A", "B", "C"] 相当になります。「プロジェクト設定で ["C"] と書いたのだから A と B は消えるはず」と思っていると、想定と違う結果になります。逆に言えば、下位レイヤーの要素を配列から消したいときに、上位レイヤーで短い配列を書いても消えない、ということです。

つまずいたときの確認手順

設定が思ったとおりに効かないときは、いきなりファイルを書き換えるのではなく、まずどのレイヤーに何が書かれているかを洗い出すのがおすすめです。

自分が編集したファイルより上のレイヤー、たとえば .claude/settings.local.json に古い設定が残っていないか。組織のmanaged policyで固定されている項目ではないか。あるいはコマンドライン引数で渡した値が毎回勝ってしまっていないか。この3つを順に見ていくと、たいていの「反映されない」は解決します。

そして、その項目が配列なのかスカラーなのかも一度確認してください。マージされる項目を上書きのつもりで書いていた、というパターンは意外と多いです。

どこに書くのが正解か

迷ったときの目安として、チーム全員に効かせたいルールは .claude/settings.json に置いてリポジトリにコミットする、自分の環境固有の事情による上書きは .claude/settings.local.json、プロジェクトを問わない自分の好みは ~/.claude/settings.json、という使い分けがきれいです。

レイヤーが分かれているのは面倒に見えますが、これがあるおかげで「組織のルールは守りつつ、プロジェクトごとの事情も、個人の好みも同時に反映できる」わけです。仕組みを理解してしまえば、むしろ扱いやすい構造だと思います。

詳しい設定項目は公式ドキュメント(https://code.claude.com/docs/ja/settings)を参照してください。