Claude Code│settings.jsonの場所と優先順位｜ユーザー・プロジェクト・ローカルの違い

Claude Codeの設定は、settings.json というファイルに書きます。

設定にはユーザー・プロジェクト共有・プロジェクトローカル・組織管理の4つのスコープがあります。ファイル名や配布方法は異なり、同じ項目の扱いは優先順位と項目別の結合規則で決まります。

• 自分の全プロジェクトの設定：ホームフォルダの .claude/settings.json
• チームで共有する設定：プロジェクトの .claude/settings.json
• このプロジェクトの自分だけの設定：プロジェクトの .claude/settings.local.json
• 強い順：組織の管理設定 → 起動時の --settings → settings.local.json → プロジェクトの settings.json → ユーザーの settings.json

2026年10月23日に公式資料と照合しました。実行結果は9月29日のv2.1.284、既存画像は10月17日の記録です。今回は実機で再検証していません。

settings.jsonの場所

Windowsでは、ホームフォルダの .claude は %USERPROFILE%\.claude のことです。

ただし、環境変数CLAUDE_CONFIG_DIRを設定している場合は、ユーザー設定・セッション履歴・プラグインなどの保存先がそのディレクトリに変わります。

Windowsの例では、プロジェクトの.claude内に2つの設定ファイルを置きます。他のOSのGitリポジトリではローカル設定をルートに置き、worktreeではメイン側を使う場合があります。共有設定は起動場所にも依存するため、保存先は/statusで確認してください。

画像は、練習用に作った practice-project フォルダの .claude を、エクスプローラーで開いたところです。

settings.json と settings.local.json は同じフォルダに入り、名前の違いでプロジェクト用とローカル用を分けます。

Claude Codeを入れただけでは、settings.json はどこにも作られません。

自分で作成するほか、/configの変更や継続的な権限承認で作成されます。保存先は項目によって異なります。手で作ったsettings.local.jsonは.gitignoreへ追加してください。

~/.claude.jsonは別物

ホームフォルダには、.claude.json という似た名前のファイルもあります。

こちらはClaude Codeが自分で書くファイルで、ログインの情報やMCPサーバーの登録、フォルダを信頼したかどうかなどが入っています。

手で直す必要はありません。

あなたはどっち？どのファイルに書くかの判定フロー

設定を書く場所に迷ったときは、誰に効かせたいかで選びます。

1. 自分の全プロジェクトに効かせたい：ホームフォルダの .claude/settings.json に書きます。
2. そのプロジェクトの全員に効かせたい：プロジェクトの .claude/settings.json に書き、Gitに入れます。
3. そのプロジェクトで自分だけの例外にしたい：プロジェクトの .claude/settings.local.json に書きます。Gitには入れません。
4. その回だけ設定を変えたい：起動時の --settings で渡します。ファイルは書き換わりません。
5. 組織として全員に強制したい：managed-settings.json・MDM・claude.aiの管理画面で配ります。これがいちばん優先されます。

単一値の項目は通常、優先順位の高い設定を使いますが、リストの結合や項目ごとの例外があります。

強い順は、組織の管理設定、起動時の --settings、settings.local.json、プロジェクトの settings.json、ユーザーの settings.json です。

優先順位を実際に確かめた

練習用のフォルダで、同じ環境変数 DEMO_LEVEL を2つのファイルに書き、どちらが使われるかを見ました。

// .claude/settings.json（プロジェクト）
{
  "env": { "DEMO_LEVEL": "project" },
  "permissions": { "allow": ["Bash(echo *)"] }
}

// .claude/settings.local.json（ローカル）
{
  "env": { "DEMO_LEVEL": "local" }
}

設定ファイルにはコメントを書けないので、上の // の行は説明のために付けています。

実際のファイルには // の行を入れず、1つのファイルに1つのJSONだけを書きます。

2026年10月17日の撮影では、練習用のファイルを作ってメモ帳で開いただけで、Claude Code は起動していません。

下の表の結果は、この記事を書いたときに Claude Code v2.1.284 で試したもので、撮影時点の版（2.1.289）では確かめ直していません。

ローカルがプロジェクトに勝ち、起動時の --settings がさらにローカルに勝っています。

claude --settings '{"env":{"DEMO_LEVEL":"cli"}}'

--settings はその回だけの設定で、ファイルは書き換わりません。

組織の管理設定が最優先ですが、一部の項目では下位の設定にある制限の強い値が優先されます。

例えば disableClaudeAiConnectors は、管理設定が false でも、他の設定で true にするとその制限が適用されます（公式の管理設定の例外、2026年10月8日確認）。

リストの設定は足し合わされる

permissions.allow のようなリストの項目は、通常、複数の設定ファイルの中身がまとめられます。

ただし fallbackModel と modelPicker は上位の設定の値を使い、availableModels と modelSettings もそれぞれ固有の規則で処理されます（公式のリスト結合と例外、2026年10月8日確認）。

チームの settings.json で許可したコマンドに、自分の settings.local.json で許可を追加する、といった使い方ができます。

単一値は通常上位の設定を使います。ただしmodelは初期値と選択制限が別で、専用フラグや環境変数の規則も確認します。

シェルで設定した環境変数と設定項目の優先関係は、項目ごとに決まっています。

一方、settings.json 内の env は設定ファイルの一項目として、通常の設定の優先順位に従います（公式の設定の優先順位、2026年10月8日確認）。

よく使う設定項目

書き方の例です。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

1行目の $schema を書いておくと、VS Codeなどで項目名の補完と入力チェックが効きます。

ただしスキーマの更新は新しい版より遅れることがあるので、新しい項目に警告が出ても間違いとは限りません。

JSONエラーと個別項目の警告を区別する

settings.json は厳密なJSONなので、コメントや末尾のカンマは書けません。

試しにプロジェクトの settings.json の末尾にカンマを付けたところ、そのファイルの設定がすべて効かなくなりました。

{
  "env": { "DEMO_LEVEL": "project", },
}

出力は空でした（`DEMO_LEVEL` は未設定です）。

不正なJSONなどはSettings Errorになります。一方、不正な権限ルールなど個別項目のSettings Warningでは、その項目だけが除外され、残りは有効です。管理設定には別の扱いがあります。

当時のclaude -pでは対話ダイアログは出ませんでした。現在も非対話実行ではダイアログは出ないため、設定が反映されないときはclaude doctorで除外された内容を調べてください。

設定が効かないときの確かめ方

1. 対話中に /status を実行し、Setting sources の行に目的のファイルが出ているかを見る
2. JSONの書き間違い（コメント・末尾のカンマ）がないかを見る
3. 同じ項目を上の順位のファイルで決めていないかを見る
4. 組織の管理設定で決められていないかを見る

/statusは読み込んだ設定元を表示し、個々のキーの採用元までは示しません。/configには全キーが並ぶわけではありません。また--settingsで指定できるのはユーザー設定で扱えるキーで、管理専用・Global configのキーは対象外です。

/config verbose=true のように、項目と値を直接書いて変えることもできます。

設定ファイルの変更は多くの場合、そのセッションにも再読み込みされ、permissionsやhooksも対象です。

一方、modelやeffortLevelなどはファイルを書き換えるだけでは実行中のセッションへ反映されないため、途中で変えるときは/modelや/effortを使います。

変更が新しいセッションで消える場合は、一時指定だったか、上位の設定があるかに加えて、保存先のユーザー設定ファイルへ書き込めるかも確認してください。

/config はターミナルの画面だけの機能で、VS Codeの拡張機能やデスクトップアプリでは開けません。

書くファイルが合っていても、項目自体がそのスコープに対応していなければ適用されません。

例えばpermissions.defaultModeのautoとbypassPermissionsは、プロジェクト共有・ローカル設定からは有効になりません。

必要な権限を検討したうえで、公式設定一覧のScope欄と、その項目を設定できる場所を確認してください。

共有ファイルのpermissions.allowや多くのenv値などは、利用者がフォルダーを信頼するまで適用されない一方、denyとaskはすぐに適用されます。

ローカルへallowを追加しても別の設定のaskを打ち消せないため、継続的に許可したのに確認が出る場合はaskルールも調べてください。

CLAUDE.mdとの使い分け

settings.json の権限ルールは、対象のツールやパスに一致した操作を制御します。

ただし、Readの拒否ルールだけで、すべての経路からのファイル読み取りを防げるわけではありません。

CLAUDE.md に書いたことは、指示として読まれるだけで、必ず守られるとは限りません。

この権限の適用範囲は2026年10月14日に公式資料で確認したもので、本記事のv2.1.284での設定優先順位の実測とは別です。

間接的な読み取りを含む拒否動作は、今回実機では検証していません。

ツールの許可・確認・拒否は settings.json に、書き方の好みは CLAUDE.md に書きます。

公式のRead/Edit仕様では、組み込みのファイル操作や認識可能なシェルのファイル操作にルールを適用する一方、PythonやNodeなどの子プロセスが間接的に読む場合などは対象外とされています。

OSレベルのアクセス制限が必要な場合は、利用環境に対応したサンドボックスとファイル権限も確認してください。

CLAUDE.md の置き場所と読み込まれる順番は、Claude CodeのCLAUDE.mdの書き方と置き場所で紹介しています。

よくある質問：settings.jsonで迷ったときのチェックリスト

settings.jsonが見つからないのはなぜですか？

Claude Codeを入れただけでは、settings.json はどこにも作られません。

自分で作成するほか、/configの変更や継続的な権限承認で作成されます。保存先は項目によって異なります。手で作ったsettings.local.jsonは.gitignoreへ追加してください。

~/.claude.jsonとは別のファイルですか？

別物です。

.claude.json はClaude Codeが自分で書くファイルで、ログインの情報やMCPサーバーの登録、フォルダを信頼したかどうかなどが入っています。

手で直す必要はありません。

設定が効かないときは、何を確かめますか？

対話中に /status を実行して、Setting sources の行に目的のファイルが出ているかを見ます。

そのうえで、JSONの書き間違い、同じ項目を上の順位のファイルで決めていないか、組織の管理設定で決められていないかを確認します。

settings.jsonにコメントを書いてもよいですか？

書けません。

settings.json は厳密なJSONなので、コメントや末尾のカンマは書けません。

末尾のカンマはJSON構文エラーです。通常の設定ファイルを無視して続ける場合がありますが、個別項目の警告や管理設定のエラーとは扱いが異なります。claude doctorで内容を確認してください。

permissions.allowのようなリストは、上書きされますか？

通常は上書きされず、複数の設定ファイルの中身がまとめられます。

ただし fallbackModel と modelPicker は上位の設定の値を使うなど、一部に例外があります。

settings.jsonとCLAUDE.mdは、どう使い分けますか？

settings.json の権限ルールは、対象のツールやパスに一致した操作を制御します。

ただし、Readの拒否ルールだけで、すべての経路からのファイル読み取りを防げるわけではありません。

CLAUDE.md に書いたことは指示として読まれるだけで、必ず守られるとは限りません。

ツールの許可・確認・拒否は settings.json に、書き方の好みは CLAUDE.md に書きます。

Readの拒否ルールは、PythonやNodeなどが間接的にファイルを読む経路まで一律に遮断するものではありません。

機密ファイルを扱うときは、実行環境のアクセス制限も確認してください。

まとめ

• 自分用はホームの .claude/settings.json、チーム用はプロジェクトの .claude/settings.json
• 自分だけの例外は .claude/settings.local.json に書く
• 強い順は、組織 → --settings → ローカル → プロジェクト → ユーザー
• リストは通常まとめられ、値が1つの項目は強いほうが使われる（モデル選択など一部に例外あり）
• JSONエラーと個別警告を分け、/statusとclaude doctorで確かめる

参考：Claude Code公式ドキュメント「Settings files and precedence」（2026年10月23日に再確認）。