チームで Claude Code を配ると、最初に壊れるのは「設定が思ったとおりに効かない」という一点です。ローカルでは deny できていたコマンドが CI では通る、プロジェクトに書いた defaultMode が無視される、managed 設定に typo を入れたら全社ポリシーが飛ぶのではないかと怖くて触れない。本稿は Claude Code の設定系（settings スコープ、permissions、sandbox、managed 設定）を公式ドキュメントの記述に逐語で紐づけて整理し、本番で踏みやすい落とし穴と、その回避のための具体的なファイル構成を示します。検証日は 2026-07-13、確認バージョンは 2.1.207 です。

1. スコープの優先順位: 上書きされる順番を最初に固定する

設定は複数のファイルから読まれ、明確な順序で適用されます。

Managed (highest): can't be overridden by anything Command line arguments : temporary session overrides Local : overrides project and user settings Project : overrides user settings User (lowest): applies when nothing else specifies the setting

Managed が最上位で、以下 CLI 引数、Local（.claude/settings.local.json）、Project（.claude/settings.json）、User（~/.claude/settings.json）の順です[1]。ここで重要なのは「上書き」の粒度がキーによって違うことです。たとえば fallbackModel は結合されません。

fallbackModel is an ordered chain where position carries meaning: the highest-precedence file that defines it supplies the entire value.

順序に意味がある値は、最高優先度のファイルが値全体を供給します[1]。「User に書いた分と Project に書いた分が足し合わされる」と期待すると外れます。

セッション中に変更が反映されないキーもあります。

A few keys are read once at session start and apply on the next restart instead

model と outputStyle はセッション開始時に一度だけ読まれ、反映には再起動（model は /model、outputStyle は /clear か再起動）が要ります[1]。

2. settings.local.json: git ignore とワークスペーストラストの非対称

When Claude Code creates .claude/settings.local.json , it configures git to ignore the file. If you create the file yourself, add it to your gitignore manually.

Claude Code が自動生成した場合だけ git ignore が設定され、自分で作った場合は手動で .gitignore に足す必要があります[1]。ここを忘れると、個人の allow ルールがリポジトリに混入します。しかもこの混入は単なる行儀の問題では終わりません。

Because this file is yours rather than the repository's, its permission allow rules take effect without the workspace trust step that .claude/settings.json allow rules require. If the repository supplies the file, for example by committing it, workspace trust still applies.

local 設定の allow ルールは「あなたのもの」であるためワークスペーストラストのステップを経ずに効きますが、リポジトリがコミットして供給している場合はトラストが適用されます[1]。つまり local ファイルのコミットは、意味論まで変えてしまいます。

3. permissions: 評価順は deny → ask → allow、特異度は関係ない

Rules are evaluated in order: deny rules first, then ask, then allow. The first match determines the outcome regardless of rule specificity.

deny が最初、次に ask、最後に allow。最初にマッチしたルールが結果を確定し、ルールの特異度は考慮されません[1]。「より具体的な allow を書けば広い deny を上書きできる」という直感は成立しません。

MCP に対するグロブにも制約があります。

Tool-name globs are supported only in the tool position after a literal mcp____ prefix, such as mcp__github__get_* ; the server segment must be glob-free.

グロブはツール位置にのみ使え、サーバー名の位置には使えません[1]。

リポジトリ側が自分に権限を付与できないよう、意図的に無視されるキーもあります。

auto is ignored when set in project or local settings, so a repository can't grant itself auto mode; set it in ~/.claude/settings.json instead.

defaultMode: auto はプロジェクト・ローカル設定では無視されます[1]。同様に、

Ignored when set in project settings ( .claude/settings.json ) to prevent untrusted repositories from auto-bypassing the prompt

skipDangerousModePermissionPrompt もプロジェクト設定では無視されます[1]。

4. fail-closed と fail-open が混在している

managed 設定の不正値の扱いは、キーごとに向きが違います。まず全体方針として、

When a managed configuration contains an entry that fails schema validation, Claude Code strips that entry, records a warning, and enforces every remaining valid policy.

typo 一つで組織ポリシー全体が無効化されることはありません[1]。そのうえで、

Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed.

allowedMcpServers は fail-closed です[1]。逆に、

requiredMinimumVersion and requiredMaximumVersion fail open by design: an invalid value is stripped rather than enforced, so a bad policy push cannot prevent Claude Code from starting.

バージョン強制は fail-open です[1]。壊れたポリシー push が起動不能を招かないための設計です。なお requiredMinimumVersion は起動をブロックする強制フロアであり、

Differs from minimumVersion , which prevents downgrades but never blocks startup.

minimumVersion はダウングレード防止のみで起動をブロックしません[1]。

ログインの強制側は fail-closed です。

An empty array fails closed and blocks login with a misconfiguration message

forceLoginOrgUUID に空配列を書くと、誤設定メッセージとともにログインがブロックされます[1]。

5. managed 設定のファイル配置とドロップイン

Linux and WSL: /etc/claude-code/ Windows: C:\Program Files\ClaudeCode\ The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75.

Linux/WSL は /etc/claude-code/、Windows は C:\Program Files\ClaudeCode\ です[1]。

Following the systemd convention, managed-settings.json is merged first as the base, then all *.json files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values, arrays are concatenated and de-duplicated, and objects are deep-merged.

managed-settings.d/ は systemd 流のドロップインで、スカラーは後勝ち、配列は結合・重複排除、オブジェクトはディープマージです[1]。ポリシーを機能単位のファイルに割り、番号プレフィックスで順序を明示できます。

policyHelper はスコープが厳しく制限されています。

Claude Code ignores policyHelper when it appears in any other scope, including user settings, project settings, the HKCU registry hive, and server-managed settings .

MDM もしくはシステムの managed-settings.json からしか読まれません[1]。そして起動を止める力があります。

When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit 0 .

非ゼロ終了は起動拒否です。障害耐性が必要なヘルパーは自前キャッシュから供給して exit 0 で終えるべきです[1]。

6. sandbox: 「有効にした」と「効いている」は別

Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed.

failIfUnavailable の既定は false で、その場合はサンドボックスが起動できなくても警告のみでコマンドは非サンドボックスで走ります[1]。本番で「サンドボックスに入れたつもり」が最も危険なのはこの既定です。

シークレットのマスクにもスコープ制限があります。

mask entries are only honored from user, managed, or CLI --settings settings, not from .claude/settings.json or .claude/settings.local.json .

sandbox.credentials.envVars の mask はプロジェクト・ローカル設定からは読まれません[1]。ネットワーク側は deny 優先です。

Takes precedence over allowedDomains when both match. Merged from all settings sources regardless of allowManagedDomainsOnly .

deniedDomains は全ソースからマージされ、allowedDomains より優先します[1]。

7. 2026 年の新しめのキー

Only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings enabledPlugins are loaded. User, project, and all other plugin hooks are blocked.

allowManagedHooksOnly はユーザー・プロジェクトの hooks をブロックします[1]。

When true , suspends every Bash and PowerShell allow rule while auto mode is active so all shell commands route through the classifier, not only rules that match arbitrary-code-execution patterns.

autoMode.classifyAllShell（v2.1.193 以降）は auto mode 中の Bash/PowerShell allow ルールをすべて停止します[1]。

Reject the --plugin-dir , --plugin-url , --agents , and --mcp-config CLI flags at startup, which users could otherwise pass to bypass strictKnownMarketplaces for a single run. Requires Claude Code v2.1.193 or later.

disableSideloadFlags は 1 回きりの回避経路を塞ぎます[1]。

8. 設定ファイルが壊れたときの副作用

If Claude Code can't read or parse a settings file, it pauses the retention cleanup sweep and shows a warning in /status until you fix the file, unless managed settings provide cleanupPeriodDays , in which case the sweep runs at the managed value.

読めない設定ファイルは retention cleanup を止めます[1]。壊れた設定は「その設定が効かない」以上の波及を持ちます。

UI をフリーズさせうる設定もあります。

Nested quantifiers such as (a+)+$ can take exponentially long against certain inputs and freeze the session, so keep each pattern linear and avoid nesting + or * .

footerLinksRegexes のパターンはメインスレッドで走るため、ネストした量化子は避けます[1]。

References

[1] https://code.claude.com/docs/en/settings