settings.json（セッティングス）　設定の置き場所と効く順番

一行でいうと

Claude Codeの挙動を変える設定を書くファイルです。置き場所が4つあり、同じ設定が複数箇所で指定されたときは、決まった順番でどれか1つが勝ちます。

なぜ必要になったのか

CLAUDE.mdは「お願い」でした。文脈として渡るだけで、守るかどうかはClaudeの判断です。hooksは「強制」でした。判断の余地なく仕組みとして実行されます。

settings.jsonは、このどちらとも違う3つ目の層です。文章として読ませる指示ではなく、Claude Codeというソフトウェア自体の挙動を直接変える設定です。どのコマンドを確認なしで実行していいか、起動時にどのモデルを使うか、どんな環境変数を渡すか。これらはClaudeの判断に委ねる話ではなく、ソフトウェアの設定として決まっている必要があります。

そして設定には、書く人が違うという事情があります。自分だけのエディタの好みもあれば、チーム全員で揃えたいコミット作法もあり、会社として一律に禁止したい操作もある。1つのファイルに全部書くと、個人の好みがチーム設定を汚したり、チームの取り決めが会社の方針を上書きしたりします。だから置き場所が分かれています。

CLAUDE.mdとの違いを一言で

CLAUDE.mdは「こうしてほしい」という文脈、settings.jsonは「こう動く」という設定です。前者は破られることがあり、後者は破られません。迷ったら、この一言に戻ってください。

仕組み

4つのスコープ

Claude Codeは、設定が効く範囲（スコープ）ごとに、次の4つのファイルから設定を読み込みます。

効く順番

同じキーが複数のファイルで設定されていたら、優先順位が最も高いレベルの値が使われます。高い順に並べると、こうなります。

ここで注意が要るのは、配列（リスト）を値に持つキーです。permissions.allow のような配列は、優先順位で1つが勝つのではなく、複数ファイルの内容が結合されます。userで許可した3件、projectで許可した2件があれば、両方合わせて5件が有効になる。「上の階層に書けば下を無効化できる」という発想は、配列キーには通用しません。

ただし例外が4つあります。fallbackModel・modelPicker・availableModels（managed設定が定義している場合）・modelSettings は、結合されず、最も優先順位が高いファイルの値がまるごと採用されます。配列に見えても、これらは順序そのものに意味があるため結合しないという扱いです。

さらにもう一段の例外があります。disableClaudeAiConnectors など9個のセキュリティ関連キーは、managed設定より厳しい値がどのスコープにあっても、そちらが優先されます。管理側が緩めても、現場が厳しくした側が勝つという、逆向きの安全弁です。

書ける主なもの

settings.jsonで変えられる代表的な項目です。

• permissions: どのツール・コマンドを確認なしで実行していいか
• env: セッションとサブプロセスに渡す環境変数
• hooks: ライフサイクルの各時点で実行する自作コマンド
• model: 起動時に使うモデル
• outputStyle: Claudeの口調と出力形式
• statusLine: 画面下部に出すカスタムステータスバー

/config と /permissions でできること

/config は、テーマ・エディタモード・詳細出力といった個人向けの設定を短い一覧で見せてくれます。全キーの一覧ではなく、よく触る一部だけです。選んだ変更はほとんどが ~/.claude/settings.json(User)に保存され、一部（Show tipsなど)だけ .claude/settings.local.json(Project local)に保存されます。

/permissions は逆に、今効いている権限ルールを全部見せてくれます。しかもルールごとに、どのsettings.jsonファイル由来かまで表示します。作業中に開いてルールを足したり消したりすると、その場でその後のツール呼び出しから反映されます。「なぜこの操作だけ確認が要らないのか」を調べるときは、まず /permissions を開いてください。

マネージド設定は別枠

managed-settings.jsonは、情報システム部門などの管理者が組織全体に配る設定です。OSごとに決まったシステムディレクトリに置くか、claude.aiの管理画面から配信します。原則としてどのスコープからも上書きできません。配布の仕組みと、強制できることの詳しい範囲は、Claude Codeを組織に入れるのレッスンで扱います。ここでは「個人やチームの設定より強い、別枠の設定がある」とだけ覚えておいてください。

よくある誤解と罠

罠1: 個人用の設定をリポジトリに入れてしまう

.claude/settings.json(Shared project)はgit管理下に置いて、チーム全員と共有するためのファイルです。ここに自分だけの好み、たとえば「このコマンドは自分だけ確認なしで実行したい」を書くと、次にリポジトリをcloneした全員がその設定を引き継ぎます。

個人の好みは、全プロジェクトに効かせたいなら ~/.claude/settings.json(User)、このプロジェクトだけの一時的な上書きなら .claude/settings.local.json(Project local、gitignore対象)に書く。どちらもリポジトリには乗りません。何をコミットして何を個人用に残すかの具体的な線引きは、Claude Codeをチームで回すのレッスンで扱います。

罠2: 効く順番の思い込み

ありがちなのは「あとから書いた方が勝つ」「project の設定は user より常に強い」という思い込みです。実際の順番は編集の新旧とは関係なく、managed > コマンドライン引数 > project local > shared project > user で固定です。

もう1つの思い込みは、「配列キーも1つのファイルが勝つ」という前提です。先に見たとおり、permissions.allow のような配列は結合されます。上位のファイルから特定の1件だけを消したいなら、上位に書き足すのではなく、deny 側に明示的に書く必要があります。

そして「managed設定は絶対に一番強い」という思い込みにも例外があります。9個のセキュリティ関連キーだけは、どのスコープであれ厳しい値の方が勝つ。管理者の設定を信頼しつつ、この逆転が起こり得る場所があることは知っておいてください。

使いどころ

置き場所を選ぶときの目安です。

• 自分のマシン全体に効かせたい好み → User(~/.claude/settings.json)
• チーム全員に揃えたい取り決め → Shared project(.claude/settings.json、git管理)
• このプロジェクトだけの、自分限定の一時的な調整 → Project local(.claude/settings.local.json)
• 会社として一律に強制・禁止したいこと → Managed設定(情シス・管理者の管轄)

迷ったら、「これは誰のためのルールか」を自分に問う。答えが「自分だけ」ならUserかProject local、「このチームの取り決め」ならShared project、「会社の方針」ならManagedです。

今日のまとめ

3行で振り返ります。

• settings.jsonには4つのスコープがあり、managed > コマンドライン引数 > project local > shared project > user の順で効く
• 配列キー（permissions.allowなど)は上書きでなく結合される。一部のキーだけは最優先ファイルの値がまるごと採用される
• 個人用の設定はUserかProject localに書く。Shared projectに書くとチーム全員を巻き込む

次は、まとめて配れるもう1つの仕組み、Pluginsです。