Claude Code 設定階層 5層｜managed と local の違いがわかる

「.claude/settings.json に書いた permission を、チームの後輩にも効かせたいのに、なぜか彼の手元では動かない」「/config で設定を変えたら、なぜか git diff に出てこない」「ChatGPT に聞いたら ~/.claude/settings.json に書けと言われたけれど、プロジェクトの .claude/settings.json にも同じキーがある場合、どっちが勝つのか分からない」

このタイプの混乱は、Claude Code の settings.json が 5 階層スタックで動いていることを知らないことから来ます。シリーズ #08 効果的な CLAUDE.md の書き方では「メモリ」、特に .claude/rules/<topic>.md + paths: frontmatter による path-scoped rules までを扱いました。本記事はもう一段下のレイヤー、設定ファイル（settings.json）の階層を扱います。

settings.json は 5 階層スタック
各層に何を書くか
どの層が active かを確認する /status
踏みやすい罠 4 つ
今週やる 1 つ ─ .gitignore に 1 行追加する
まとめ
TL;DR

settings.json は 5 階層スタック

Anthropic 公式ドキュメントの Settings precedence には、こう明記されています。

設定は優先順位に従って適用されます。最高から最低まで。

Managed settings
Command-line flags
Local project settings (.claude/settings.local.json)
Shared project settings (.claude/settings.json)
User settings (~/.claude/settings.json)

訳すと「設定は優先順位の順に適用される。最高位から最低位まで」です。Claude Code は起動時に 5 つの場所から settings を読み込み、上の層が下の層を上書きする。これが全ての出発点です。

flowchart TD M["第1層: Managed settings<br/>（組織が縛る・上書き不可）"] C["第2層: コマンドラインフラグ<br/>（セッション限定）"] L["第3層: .claude/settings.local.json<br/>（自分専用・git-ignored）"] P["第4層: .claude/settings.json<br/>（チーム共有・git commit）"] U["第5層: ~/.claude/settings.json<br/>（全プロジェクト共通の個人設定）"] M -->|上書き| C C -->|上書き| L L -->|上書き| P P -->|上書き| U

各層を 1 行で要約します。

第1層 Managed: 組織の IT 管理者が全社員に強制する設定。個人開発者には基本関係ない
第2層コマンドラインフラグ: claude --permission-mode auto のようなセッション限定の上書き
第3層 .claude/settings.local.json: 自分専用のプロジェクト設定。git に入れない
第4層 .claude/settings.json: チーム共有のプロジェクト設定。git にコミット
第5層 ~/.claude/settings.json: 全プロジェクトに効かせたい個人の好み

「上の層が下を上書きする」を覚えておけば、迷ったときに必ず正解にたどり着きます。

各層に何を書くか

5 階層を「読者が明日から書ける」レベルまで噛み砕きます。

第5層: `~/.claude/settings.json` ─ 全プロジェクト共通の個人設定

ホームディレクトリの ~/.claude/settings.json は、全プロジェクトに効く自分専用の設定です。スタックの最下位なので、project 側に同じキーが書いてあれば負けます。

書くもの:

theme editorMode のような UI の個人好み
全プロジェクトで使いたい env（例: EDITOR=nvim）
個人的に許したい permission ルール（自分のローカル開発で使う社内ツールなど）

書かないもの:

プロジェクト固有の env（その層は第4層）
機密値（OAuth トークン等は ~/.claude.json 経由で Claude Code が自動保存する。settings.json には書かない）

第4層: `.claude/settings.json` ─ チーム共有のプロジェクト設定

リポジトリ直下の .claude/settings.json は git にコミットしてチーム全員で共有する設定です。

書くもの:

プロジェクトで使う env（テストツールの環境変数、CI で必要な値など）
チーム全員に効かせたい permission allow / ask / deny ルール
プロジェクト用の hooks 設定
このプロジェクトで使う MCP サーバー（.mcp.json）と連動した設定

git にコミットするので、機密値は書きません。API キー、個人アクセストークン、社内システムの URL のような「コミットしたら漏れて困るもの」は別の層へ。

第3層: `.claude/settings.local.json` ─ 自分専用のプロジェクト設定

.claude/settings.local.json は そのプロジェクト内で自分だけに効かせたい設定です。git に入れません。

書くもの:

自分だけが Claude に許したい permission（チームには強制したくないもの）
自分の local 環境変数（自分の dev DB URL、社内 VPN 経由のエンドポイントなど）
disableAllHooks: true のような「自分の手元では一時的に切りたい」設定

Anthropic 公式ドキュメントは、.claude/settings.local.json についてこう書いています（Configuration scopes）。

.claude/settings.local.json for settings that are not checked in, such as machine-specific tweaks. Claude Code will configure git to ignore .claude/settings.local.json when it is created.
マシン固有の調整など、チェックインされていない設定の .claude/settings.local.json。 Claude Code は、作成時に .claude/settings.local.json を無視するように git を設定します。

作成時に Claude Code が自動で .gitignore を更新してくれる仕様です。ただし既存リポでは自動更新が走らないこともあるため、手動で .gitignore に入っているか確認します。

第2層: コマンドラインフラグ ─ セッション限定の上書き

claude --permission-mode auto claude --allowedTools "Bash(git:*)" のように、起動時のフラグで設定を上書きできます。そのセッションだけ有効で、settings.json は触りません。

書くもの（=渡すフラグ）:

単発で permission モードを変えたいとき（--permission-mode auto）
1 回限りで特定のツールを許可したいとき（--allowedTools）

settings.json の編集を残したくない一時的な実験には、この層が最適です。

第1層: Managed settings ─ 組織が縛る最上位

最上位の Managed settings は、組織の IT 管理者が全社員の Claude Code に強制する設定です。「--dangerously-skip-permissions 禁止」「指定した MCP サーバー以外は使用禁止」「特定ドメイン以外への WebFetch 禁止」など、組織全体のセキュリティポリシーを deploy する用途で使われます。

個人開発者にはほぼ関係ありません。家で 1 人で Claude Code を使っているなら、この層は読み飛ばして問題ありません。

ただし「/config を開いたら見覚えのない設定がデフォルト値になっている」「特定のコマンドが許可できない」と感じたら、この層が効いている可能性があります。確認方法は次の節で扱います。

どの層が active かを確認する `/status`

「いま自分の Claude Code はどの settings 層を読み込んでいるのか」を知りたければ、Claude Code 内で /status を実行します。

Anthropic 公式ドキュメントの Verify active settings には、こう書かれています。

Run /status inside Claude Code to see which settings sources are active. The Status tab includes a Setting sources line that lists each layer Claude Code loaded for the current session, such as User settings or Project local settings. When managed settings are in effect, the entry shows the delivery channel in parentheses, for example Enterprise managed settings (remote), (plist), (HKLM), (HKCU), or (file).
クロードコード内で /status を実行して、どの設定ソースがアクティブであるかを確認します。「ステータス」タブには、「ユーザー設定」や「プロジェクトのローカル設定」など、現在のセッションでロードされた各レイヤーのクロードコードをリストする「ソースの設定」行が含まれています。管理設定が有効な場合、エントリには配信チャネルが括弧内に表示されます (例: 「エンタープライズ管理設定 (リモート)」、「(plist)」、「(HKLM)」、「(HKCU)」、または「(file)」。

例えば User settings や Project local settings。Managed settings が効いている場合は、配信チャネルが括弧書きで表示される」です。

開発中に「permission ルールが効かない」「env が読まれていない」と感じたら、まず /status でどの層が active かを確認します。何も書いていないはずの層が表示されていたら、過去の自分が書いた設定が残っている可能性があります。

踏みやすい罠 4 つ

5 階層スタックの全体像をつかんだら、実務で踏みやすい罠を 4 つだけ押さえます。

罠 1: チーム共有の `.claude/settings.json` に API キーを書いて commit

第4層の .claude/settings.json は git にコミットする設計です。機密値を書く場所ではありません。ここに API キーや個人アクセストークンを書いてそのまま push すると、公開リポなら全世界に漏れます。社内リポでも、組織内の全エンジニアに見えてしまいます。

正しい置き場所:

OAuth トークンなどは Claude Code が自動で ~/.claude.json に保存する（手で書かない）
自分の dev DB URL のようなマシン固有の機密は .claude/settings.local.json（第3層）
環境変数化して process.env から読む（ローカルは .env.local で）

罠 2: チームに効かせたい設定を `.claude/settings.local.json` に書いて「効かない」と詰む

「チーム全員に Bash(npm:*) を allow したい」と思って、自分の手元で設定を書いたら、なぜか commit に出てこない。後輩が pull してきても効かない。

原因はほぼ 100%、書く場所を間違えています。チーム共有したいルールは第4層 .claude/settings.json に書いて commit する必要があります。第3層の .claude/settings.local.json は git-ignored なので、書いてもチームには絶対に伝わりません。

判別の手順:

設定したいルールが「チーム全員に効かせたい」のか「自分だけ」なのかを先に決める
「チーム全員」なら .claude/settings.json をエディタで直接開いて追記し、git add / commit する
「自分だけ」なら .claude/settings.local.json に追記する。git に入れない

.claude/settings.json が commit 済みかを確認するワンライナー:

git ls-files .claude/settings.json
# → このパスが出力されれば既に追跡されている
# 何も出なければまだ未追跡（git add していない）

罠 3: `~/.claude/settings.json` で全プロジェクトに効かせたつもりが、上書きされる

5 階層スタックの第5層は最下位です。プロジェクト側の .claude/settings.json（第4層）や .claude/settings.local.json（第3層）に同じキーが書いてあれば、project 側が勝ちます。

具体例:

~/.claude/settings.json に "theme": "dark" を書いた
そのプロジェクトの .claude/settings.json に "theme": "light" が書いてあった
→ Claude Code は light で起動する

直感に反するかもしれませんが、これは「team が決めた設定が、個人の好みより強い」という意図的な設計です。逆らいたいなら、そのプロジェクトの .claude/settings.local.json（第3層）に書きます。第3層は git に入らない自分専用なので、第4層を上書きできます。

罠 4: `.gitignore` 漏れで `.claude/settings.local.json` を commit してしまう

第3層の .claude/settings.local.json は、Claude Code が作成時に自動で .gitignore を更新する仕様です。ただし「既存のリポで Claude Code を初めて使い始めた」「別マシンで作ったファイルをコピーした」「git add -A で全部追加した」などのタイミングで、.gitignore への自動追加が走らないことがあります。

このまま commit すると、自分専用のはずだった設定（permission allow ルールなど）がチーム全員に共有されてしまいます。チェックのワンライナーを 30 秒で実行します。

cd <your-project>
git check-ignore -v .claude/settings.local.json
# → ".gitignore:N:.claude/settings.local.json .claude/settings.local.json"
# が出れば OK（ignore されている）
# 何も出なければ ignore されていない → .gitignore に追記する
echo '.claude/settings.local.json' >> .gitignore

.claude/settings.local.json がすでに追跡されてしまっていた場合は、次のコマンドで追跡を外します。

git rm --cached .claude/settings.local.json
git commit -m "chore: stop tracking .claude/settings.local.json"

これでファイル自体はローカルに残ったまま、git の追跡対象から外れます。

今週やる 1 つ ─ `.gitignore` に 1 行追加する

すでに Claude Code を使っているプロジェクトがあるなら、最初の 30 秒でできる安全策があります。

cd <your-project>
grep -E '^\.claude/settings\.local\.json' .gitignore \ || echo '.claude/settings.local.json' >> .gitignore
git check-ignore -v .claude/settings.local.json

これで、自分専用設定を間違って commit する事故は構造的に防げます。team settings (.claude/settings.json) と local settings (.claude/settings.local.json) を物理的に分離する第一歩です。

その後の運用は、最初の段落でやった「先に層を決める → 書く」という順番に慣れていきます。

チーム全員に効かせたい? → 第4層 .claude/settings.json を手で開いて編集 → commit
自分だけ? → 第3層 .claude/settings.local.json を手で開いて編集 → commit しない
全プロジェクトで使う自分の好み? → 第5層 ~/.claude/settings.json
今だけ実験? → コマンドラインフラグ

/status で active settings を確認する習慣もつけておくと、設定が効かない原因の切り分けが一瞬で終わります。

まとめ

settings.json は 5 階層スタックで動いています。Managed → コマンドラインフラグ → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json の順で、上が下を上書きします。チーム共有は第4層に手で書き、自分専用は第3層に書いて .gitignore に追加する、/config UI の編集は第5層に保存される可能性がある（迷ったら /status で確認）。この 3 つを覚えておけば、settings 周りの事故はほぼ起きません。Managed settings は組織が縛る最上位ですが、個人開発者にはほぼ関係ありません。

シリーズ #08 で扱った CLAUDE.md と .claude/rules/ の path-scoped rules、本記事の .claude/settings.json ─ これで Claude Code の「メモリ・ルール・設定」3 層がそろいました。次回はこの上に立つ「外との接続」を扱います。

TL;DR

Claude Code の settings.json は 5 階層スタック（Managed > コマンドラインフラグ > .claude/settings.local.json > .claude/settings.json > ~/.claude/settings.json）で動き、上が下を上書きする（Anthropic 公式 docs）。チーム共有は第4層、自分専用は第3層、.gitignore 追加と /status 確認を習慣化すれば事故は起きない。