Claude Code 設定ガイド｜settings.jsonのスコープ優先順位とpermissions設計

Q: Claude Codeで環境変数はどう設定しますか？

settings.jsonのenvキーに書く。ここで設定した環境変数は、そのセッション全体とサブプロセスに適用される。値を空文字列""にすると、より優先度の低いスコープで設定された値を上書き（実質的な無効化）できる。

Q: 設定が正しく読み込まれているか確認する方法は？

セッション内で/statusを実行するとロード済みの設定ソース一覧が確認できる。/doctorはManaged設定違反やスキーマエラーを検出する。エディタでの補完・検証には、settings.jsonに"$schema": "https://json.schemastore.org/claude-code-settings.json"を追加するとVS Code/Cursorで効く。

Claude Code settings.json — scopes, permissions merge, and environment variables

🧠 Claude Code claude-code claude settings.json permissions 環境変数

2026.08.11 15分更新 2026.08.11

A AI Heartland · 編集部

Claude Code 設定ガイド｜settings.jsonのスコープ優先順位とpermissions設計 - AIツール日本語解説 | AI Heartland

Claude Codeのsettings.jsonは5段階のスコープに分かれ、permissionsのallow/denyはスコープ間で上書きでなくマージされる。この直感に反する挙動と主要キーの書き方を公式ドキュメントに基づいて整理する。

Claude Code 設定は、settings.jsonという1つのJSONファイルだけで完結する話ではない。Managed・コマンドライン引数・Local・Project・Userという5段階のスコープに分かれ、なかでも権限（permissions）のallow/denyは「上書き」ではなく「マージ」される、という直感に反する挙動を持つ。よく似た名前のCLAUDE.mdは自然言語で書く指示ファイルであり、本記事が扱うJSON形式のsettings.jsonとは別物なので、まずここを混同しないでおきたい（CLAUDE.mdの書き方は後述のリンク先で扱う）。本記事は公式ドキュメント（code.claude.com/docs/en/settings）に基づき、設定スコープ優先順位・settings.json 書き方の基本・permissions allow deny の設計・Claude Code 環境変数の指定方法を1ページで整理する。

Claude Codeの設定は5段階のスコープで適用される。上からManaged・コマンドライン引数・Local・Project・Userの順で優先度が下がる — Claude Codeの設定スコープは5段階。上に行くほど優先度が高い（出典: Claude Code settings公式ドキュメント）。

30秒でわかる Claude Code 設定（2026年8月時点）

・スコープは5段階：Managed（組織全体・上書き不可）＞コマンドライン引数（そのセッションのみ）＞ Local（.claude/settings.local.json）＞ Project（.claude/settings.json）＞ User（~/.claude/settings.json）の順で優先度が下がる。
・permissionsは上書きでなくマージ：allow/denyはスコープ間で合算され、Managedの最も制限的なルールが常に優先される。
・envキーで環境変数を設定でき、セッション全体とサブプロセスに適用される。空文字列で下位スコープの値を上書きできる。
・確認は3窓口：/status（設定ソース一覧）・/doctor（Managed違反やスキーマエラー検出）・$schema（エディタ補完）。
・注意：/config key=valueでの単一キー変更はv2.1.181以降の機能。バージョンが古いと使えない。

Claude Code全体の使い方・インストール・CLAUDE.md・Hooksまでを俯瞰したい場合は、Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きを参照してほしい。本記事はその中でもsettings.jsonのスコープ・主要キー・permissions設計に絞って掘り下げる。

Claude Code 設定ファイルはどこにある？5段階のスコープと優先順位

Claude Codeの設定は、1つのファイルではなく5段階のスコープに分かれている。設定スコープの優先順位は上から順に適用され、下に行くほど優先度が低い。

スコープ	ファイル場所	適用対象	チーム共有	優先順位
Managed	サーバー管理/plist/registry/`managed-settings.json`	組織全体	✅（IT部門展開）	最高
（コマンドライン引数）	—	そのセッションのみ	—	2番目
Local	`.claude/settings.local.json`	このリポジトリのみ	❌（gitignore対象）	3番目
Project	`.claude/settings.json`	リポジトリの全コラボレータ	✅（git管理）	4番目
User	`~/.claude/settings.json`	全プロジェクト共通	❌	最低

Managedはサーバー管理・plist（macOS）・registry（Windows）・managed-settings.jsonのいずれかで組織全体に配布され、最高優先度・上書き不可という扱いになる。IT部門やセキュリティチームが「これだけは絶対に変えさせない」というルールを敷く層だと考えるとわかりやすい。

一方でコマンドライン引数は「今このセッションだけ一時的に上書きしたい」場合に使う2番目に強い層で、ファイルとして残らない。Localはこのリポジトリでの自分専用の設定（.claude/settings.local.json）で.gitignore対象になり、チームには共有されない。Projectはリポジトリの全コラボレータに共有される.claude/settings.jsonで、git管理下に置くのが前提。Userは~/.claude/settings.jsonで全プロジェクトに横断的に効くが、5段階のうち最も優先度が低い。

具体例で見ると、User設定である値Aを、Project設定で値Bを指定した場合は、優先度の高いProject側の値Bが適用される。「後から書いた方が勝つ」のではなく、スコープの優先順位で決まるという点を押さえておきたい。

この5段階が分かれている理由は、関わる人の立場がそれぞれ違うからだ。組織のセキュリティ担当は「本番の秘密鍵は誰にも読ませたくない」という制約をManagedで敷きたい。リポジトリのメンテナは「このリポジトリではlintコマンドだけは常に許可しておきたい」という運用ルールをProjectに書きたい。個々の開発者は「自分のマシンだけ、このデバッグ用コマンドを許可したい」という一時設定をLocalに置きたい——という具合に、誰が・どの範囲に・どれだけ強制力を持って設定したいかが違う。1つのファイルに全部書いてしまうと、この「誰の設定か」が曖昧になり、チームで設定ファイルを共有した瞬間に個人の一時設定まで全員に配られてしまう。5段階のスコープ分割は、この事故を防ぐための設計だと理解すると腹落ちしやすい。

なお、Local（.claude/settings.local.json）は.gitignore対象なので、間違えてコミットしてしまわない限りチームには共有されない。個人のAPIキーやデバッグ用の一時許可をここに書く運用が向いている。逆にProject（.claude/settings.json）はgit管理下に置く前提のファイルなので、チーム全体に共有してよい情報だけを書く。この2つを混同すると、個人設定のつもりで書いた内容が誤ってチーム全体に配られる、という事故につながる。

スコープごとに「何を書くか」の目安

どのスコープに何を書くべきかで迷ったら、次のような役割分担が目安になる。

・Managed：組織のセキュリティポリシー上、絶対に外せないpermissions.deny（秘密鍵・本番環境変数へのアクセス拒否など）。個々のプロジェクトやユーザーの判断で緩めさせたくないルールだけを置く
・コマンドライン引数：一度きりの検証やデバッグで、ファイルに残したくない一時的な上書き
・Local：自分だけが使うAPIキーのプレースホルダ、個人的なデバッグ用コマンドの許可など、他のメンバーに影響を与えたくない設定
・Project：npm run lintやnpm testなどチーム全員が実行してよいコマンドの許可、リポジトリ固有のmodel指定など、チームで統一したいルール
・User：好みのモデル指定やエディタ連携など、プロジェクトをまたいで自分に適用したい個人設定

この目安に沿って書き分けておくと、後から「なぜこの設定が効いているのか／効いていないのか」を追いかけるときに、スコープを見るだけで意図が推測しやすくなる。

読者の3つの問いへの答え
① これは何ができるか：Claude Codeの動作（権限・モデル・環境変数など）を、組織／セッション／リポジトリ／個人の4つの粒度で制御できる ② 何を解決するか：「チーム全体で統一したいルール」と「自分だけの一時設定」を1つのファイルに混ぜずに済む ③ 何を代替できるか：シェルの環境変数やCLI引数を毎回手打ちする運用を、リポジトリに`.claude/settings.json`として固定化できる。

settings.jsonの主要キーと書き方

settings.jsonはJSON形式で、主要なキーは次の通りだ。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": ["Bash(npm run lint)"],
    "deny": ["Read(./.env)"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "autoUpdatesChannel": "latest"
}

modelキーでセッションのデフォルトモデルを指定できる。permissionsは次のH2で扱うallow/denyの権限ルールを持つオブジェクトだ。envは環境変数を定義するオブジェクトで、詳細は後述する。autoUpdatesChannelは自動アップデートのチャンネル指定に使うキーである。

冒頭の"$schema": "https://json.schemastore.org/claude-code-settings.json"をsettings.jsonに追加しておくと、VS CodeやCursorでオートコンプリートとスキーマ検証が効くようになる。存在しないキー名を書いてしまうミスを、エディタ側で早期に検出できるのでほぼコストなしで入れておく価値がある。

実際に上記のJSONは手元の検証環境で.claude/settings.jsonとして保存し、JSON構文エラーが出ないことを確認済みだ。settings.json 書き方の基本は「有効なJSONであること」だけで、キーの並び順に意味はない。ただし前述のとおり存在しないキー名を書いても警告なく無視されることがあるため、$schemaによるエディタ側の検証を併用するのが安全だ。

キーごとに設定できる粒度も異なる。modelとpermissionsはManaged・Project・User・Localのどのスコープにも書けるオブジェクトだが、実務では「モデルは個人の好みでUserに書き、permissionsはチームで統一したいのでProjectに書く」といった役割分担にするケースが多い。1つのキーを複数スコープに重複して書いてしまうと、前述の優先順位に従ってどちらが有効になるかが決まるので、意図せず片方が無視される事態を避けるためにも、どのキーをどのスコープに置くかをチームで決めておくとよい。

permissions（allow/deny）の設計 — マージという直感に反する挙動

settings.jsonまわりで最も誤解されやすいのが、permissions.allow/permissions.denyの扱いだ。多くの人は「Projectで許可（allow）したら、他のスコープの拒否（deny）は上書きされて無効になる」と考えがちだが、実際の挙動は違う。

allow/denyルールはスコープ間で上書きされず、マージ（合算）される。 ProjectでBashコマンドをallowしていても、UserやManagedに別のdenyルールがあれば、それも合わせて評価対象になる。そしてManaged設定に含まれるルールは、最も制限的なもの（＝拒否する方向）が優先される。組織のManaged設定で「本番環境の秘密鍵を読ませない」というdenyルールを敷いていれば、Project側でどれだけallowを積み上げても、そのdenyは無効化できない。

permissionsのallow/denyはスコープ間でマージされる。上書きされるという誤解と、実際はマージされるという挙動の対比図 — 「Projectでallowすればdenyは上書きされる」は誤解。実際はスコープ間でマージ（合算）される（出典: Claude Code settings公式ドキュメント）。

flowchart LR M["Managedのallow/deny
(最優先・変更不可)"] --> R["最終的な権限ルール"] L["Localのallow/deny"] --> R P["Projectのallow/deny"] --> R U["Userのallow/deny
(最も優先度が低い)"] --> R R --> N["スコープ間でマージ
(上書きではなく合算)"]

この挙動を完全にロックダウンしたい場合は、allowManagedPermissionRulesOnly: trueをManaged設定に加えることで、User/Projectのpermissionsルールそのものを無効化できる。組織全体で「開発者にpermissionsをいじらせたくない」というケースに使えるオプションだ。

先ほどの主要キーの例で使った.claude/settings.jsonをそのまま例に取ると、permissions.allowにBash(npm run lint)、permissions.denyにRead(./.env)を書いていた。これはProjectスコープの設定なので、チーム全員がこのリポジトリでnpm run lintを実行できる一方、.envファイルの読み取りは拒否される。ここでもし個々の開発者がUserスコープの~/.claude/settings.jsonにpermissions.allow: ["Read(./.env)"]を書いても、Projectのdenyは無効化されない。permissions allow deny の設計を「上書き」ではなく「足し算」で捉えていないと、なぜ自分のUser設定が効かないのか分からず混乱することになる。

よくある誤解
「Projectのsettings.jsonでallowしたのに、コマンドが拒否される」という報告の多くは、User側やManaged側に残っているdenyルールが合算されて効いているケースである。allow/denyは足し算で考える。

チームでこの挙動を運用に落とし込むなら、permissionsを変更するPull Requestではdiffだけでなく「このallow/denyがどのスコープに置かれ、他のスコープと矛盾しないか」をレビューの観点に加えるとよい。特にProjectの.claude/settings.jsonはgit管理下にあるため、通常のコードレビューの延長で確認できる。Managedの設定を変更できる権限を持つのは通常IT部門やセキュリティチームに限られるため、開発チーム側で「Managedにどんなdenyルールが敷かれているか」を把握していないと、原因不明の拒否に時間を溶かしやすい。導入初期はチームのREADMEやCLAUDE.mdに、Managedで敷かれている代表的なdenyルールを一覧化しておくと、混乱を減らせる。

Claude Code 設定で環境変数とモデルを指定する

Claude Code 環境変数の設定はenvキーに書く。ここで定義した環境変数は、そのセッション全体とサブプロセスの両方に適用される。CIやDocker上で決まった環境変数を毎回シェルで渡す代わりに、リポジトリの.claude/settings.jsonに固定できる。

{
  "env": {
    "NODE_ENV": "development",
    "DISABLE_TELEMETRY": ""
  }
}

値を""（空文字列）にすると、より優先度の低いスコープで設定されていた同名の環境変数を上書き（実質的な無効化）できる。「Userで設定していた値を、このリポジトリだけ無効にしたい」といった場面で使える。

モデルの指定はmodelキーで行う。前述の主要キーの例のとおり"model": "claude-sonnet-5"のように書くと、そのスコープが有効な間のデフォルトモデルになる。CLIの--agentオプションのようにセッション単位で上書きする方法もあるが、リポジトリ全体で固定したい場合はsettings.jsonのmodelキーの方が適している。

環境変数とモデル指定を両方Managedスコープに書くと、組織全体で「使うモデルを固定し、かつ特定の環境変数を強制する」運用ができる。例えば社内のプロキシ設定や、特定のAPIエンドポイントを指す環境変数を全社員のセッションに強制したい場合、個々人のUser設定やProjectのCLAUDE.mdで指示するよりも、Managedのenvキーで固定してしまう方が確実だ。Local/Project/Userのenvはチームやリポジトリ単位の柔軟な調整に、Managedのenvは「絶対に外せない前提条件」の固定に、という役割分担で考えるとよい。

Claude Code 設定を確認・検証する方法（/status・/doctor・$schema）

設定ファイルを書いた後、それが実際にどう読み込まれているかを確認する窓口は主に3つある。

Claude Codeの設定を確認する3つの窓口。/status・/doctor・$schemaによるエディタ補完 — 設定を確認する3つの窓口：/status・/doctor・エディタの$schema補完。

セッション内で/statusを実行すると、現在ロードされている設定ソースの一覧が確認できる。/doctorはManaged設定違反やスキーマエラーを検出するための診断コマンドだ。/configはタブ形式のUIで設定を編集でき、/config key=valueの形式で単一キーだけを直接変更することもできる（この単一キー指定はv2.1.181以降の機能）。

手元の検証環境（Claude Code CLI 2.1.227）で実際に.claude/settings.jsonを作成し、CLIのヘルスチェックコマンドを実行したところ、次の結果が返った。

cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": ["Bash(npm run lint)"],
    "deny": ["Read(./.env)"]
  }
}
EOF

claude doctor

Claude Code doctor

Running: native (2.1.227)
Search: OK (bundled)
Auto-updates: enabled

No installation issues found.

For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

このコマンドラインのclaude doctorはインストール全体の健全性チェックであり、セッション内の/doctor（Managed設定違反やスキーマエラーを検出する設定特化の診断）とは別物である点に注意したい。上記の実行では、少なくともJSON構文エラーやインストール異常は検出されず「No installation issues found」で終わった。実際のManaged違反検出結果までは今回の検証環境（Managed設定なし）では再現できていないため、その挙動は公式ドキュメントの記述に基づく。

エディタでの補完・検証には、前述の$schemaをsettings.jsonの先頭に置くのが手軽だ。VS CodeやCursorでキー名の誤字やスキーマ違反をその場で指摘してくれる。

実務での確認の流れとしては、①settings.jsonを編集する前に$schemaでエディタ側の静的な検証を済ませる ②保存したら/statusで実際にどのスコープの値がロードされているかを確認する ③permissionsが想定通りに効いていない、Managed違反が疑われるといった場合に/doctorで詳細な診断を行う、という3段階で考えると迷わない。特に複数人が関わるプロジェクトでは、「自分のLocal設定のつもりが、実はProjectの値で上書きされていた」という勘違いが起きやすいため、変更のたびに/statusで確認する習慣をつけておくと事故を防ぎやすい。

まとめ：Claude Code 設定でまず押さえる3つのポイント

Claude Code 設定を扱ううえで押さえておきたいのは次の3点だ。
① 5段階のスコープと優先順位（Managed＞コマンドライン引数＞Local＞Project＞User）を理解する
② permissionsのallow/denyはスコープ間でマージされる——上書きではなく合算されるため、「許可したのに拒否される」現象の多くはこの仕組みで説明がつく
③ 変更後は/status・/doctor・$schemaで実際の読み込み結果を確認する習慣をつける

本記事で扱った内容はいずれもsettings.jsonという単一ファイル・単一機構（スコープの優先順位とpermissionsのマージ）に閉じている。.claude/フォルダにはこの他にもcommands・skills・agentsといった別のディレクトリ・別の機構が存在するが、それらは本記事の範囲外だ。

.claude/フォルダ全体の構造（commands・skills・agentsディレクトリなど）まで含めて知りたい場合は Claude Codeの.claudeフォルダ設定ガイド：commands・skills・agents構造を徹底解説が扱っている。自然言語による指示ファイルの書き方は CLAUDE.mdの書き方？AIに仕事を任せる人が最初に学ぶべきセクション設計と失敗パターンを、Claude Code自体の導入・料金プランは Claude Codeとは？Anthropic公式AIコーディングツールの使い方・インストール・料金【2026年版】を、日々の運用Tipsは Claude Codeベストプラクティス2026｜Boris直伝25 Tips・並列ワークツリー・–bare最適化を参照してほしい。

参照ソース

・Claude Code settings（公式ドキュメント） — スコープ優先順位・主要キー・permissionsのマージ挙動を取得
・Claude Code Docs トップ — 関連ドキュメント（CLAUDE.md・hooks等）への導線を確認

よくある質問

Claude Codeの設定ファイルはどこにありますか？

優先度が高い順に、Managed（サーバー管理/plist/registry/managed-settings.jsonで組織全体に適用）、コマンドライン引数（そのセッションのみ）、Local（.claude/settings.local.json・このリポジトリのみでgitignore対象）、Project（.claude/settings.json・リポジトリの全コラボレータ向けでgit管理）、User（~/.claude/settings.json・全プロジェクト共通）の5段階がある。

settings.jsonのpermissionsで許可したのに拒否されるのはなぜですか？

allow/denyルールはスコープ間で上書きではなくマージ（合算）される。ProjectでallowしてもUserやManagedのdenyルールが別に存在すれば、そちらも合わせて評価される。特にManaged設定は最も制限的なルールが優先されるため、Project側の許可では上書きできない。

Claude Codeで環境変数はどう設定しますか？

settings.jsonのenvキーに書く。ここで設定した環境変数は、そのセッション全体とサブプロセスに適用される。値を空文字列""にすると、より優先度の低いスコープで設定された値を上書き（実質的な無効化）できる。

設定が正しく読み込まれているか確認する方法は？

セッション内で/statusを実行するとロード済みの設定ソース一覧が確認できる。/doctorはManaged設定違反やスキーマエラーを検出する。エディタでの補完・検証には、settings.jsonに"$schema": "https://json.schemastore.org/claude-code-settings.json"を追加するとVS Code/Cursorで効く。

🧠

Claude Code

Claude Codeの使い方・設定・内部アーキテクチャ・拡張エコシステムを網羅。Harness Engineering・AI MDファイル・Claude Designも含む →