Skip to main content
What this unit solvesBefore learning any tool’s configuration details, build a universal coordinate system first. Grasp the two axes — scope and setting type — and you can immediately judge where any configuration file belongs, whether it will be overridden by something else, and whether it should be committed to version control.

​
Learning objectives

  • Use the scope axis (managed, user, project, local) to describe the effective range of any setting.
  • Use the setting-type axis (personalization, memory, rules, privacy, permissions, automation) to classify any configuration item.
  • Explain the override precedence order and distinguish the three distinct layer semantics: override, concatenate, and merge.
  • Correctly identify which configuration files should be committed (team-shared) and which should be gitignored (personal).

​
1. First axis: scope

The same setting can appear at different scopes; which one takes effect depends on precedence. Using Claude Code as the primary reference, five layers from highest to lowest (as of 2026-05 official documentation [1]):
One rule to remember“The closer a setting is to the current task, the higher its precedence.” Managed policy is the only exception that flows top-down and cannot be overridden — that is for IT administration. The remaining four layers all obey “closer wins.”

​
Three layer semantics: override vs concatenate vs merge

This is the biggest misconception people have about “layers”: not all settings use “higher layer overrides lower layer.” Claude Code has at least three distinct merge behaviors. Mixing up these mental models costs a great deal of debug time ([1][2]): In other words: your ~/.claude/CLAUDE.md and the project’s ./CLAUDE.md do not override each other — both are read (user layer first, project layer second). But for the same key in ~/.claude/settings.json and .claude/settings.json, the higher-priority layer wins. Treating these two situations as identical is the root cause of confusion like “I clearly set this at the user layer, why does the project behave differently?“

​
2. Second axis: setting type

Scope determines “where it takes effect”; type determines “what it controls.” Six types:
  • Personalization: role, language, tone, output format.
  • Memory: facts and preferences persisted across sessions (short-term vs long-term covered in 01-4).
  • Rules / instructions: project conventions and constraints (CLAUDE.md, AGENTS.md, .claude/rules/).
  • Privacy: training opt-out, retention period, temporary conversations.
  • Permissions: which tools can execute, which paths can be read or written (allow / ask / deny).
  • Automation: skills, hooks, workflows.
Cross the two axes and any configuration item maps to exactly one cell: a rule is “rules type x some scope,” a permission is “permissions type x some scope.”

​
3. Two axes combined: decision tool

Treat “type x scope” as a matrix. Every time you need to place a setting, pick these two axes first — the result determines which file it goes in and whether to commit it.
Three settings, three locations
  1. Team-shared coding style conventions: rules type x project scope — write into ./CLAUDE.md, commit to version control, shared with the team.
  2. Your personal sandbox URL and preferred test data: personalization / rules type x local scope — write into ./CLAUDE.local.md, add to .gitignore, only you can see it, does not pollute the team.
  3. Your cross-project language preference (always reply in Traditional Chinese): personalization type x user scope — write into ~/.claude/CLAUDE.md, applied to every project on your machine.
All three are “rules / personalization” type; the only difference is scope, and scope directly determines “commit or gitignore, who can see it.” That is the two-axis coordinate system in practice: fix the type, fix the scope, and the file location and version-control strategy fall out automatically.
When the same key appears at multiple layers, decide first: override or concatenateIf you set model in ~/.claude/settings.json and also set a different model in .claude/settings.json, the project layer wins (override; closer wins). But if you write style rules in both ~/.claude/CLAUDE.md and ./CLAUDE.md, both take effect (concatenate). When they conflict, Claude may follow either one, so do not let rules at two layers contradict each other.

​
4. Commit vs gitignore (critical practice)

The most direct version-control consequence of the scope axis is this binary:
  • Commit (version control, team-shared): rules and settings the whole team should follow consistently. ./CLAUDE.md, .claude/settings.json, .claude/rules/, AGENTS.md.
  • gitignore (personal, not shared): personal overrides, secrets, local paths. ./CLAUDE.local.md, .claude/settings.local.json, anything containing tokens.
This is the same mental model as .env vs .env.example: the shareable template goes into version control; the instance that contains secrets stays local. The test is simple: if a teammate applied this setting, would it help them or leak something about you? If it helps them, commit it; if it leaks you, gitignore it.
Secrets never go in a file that will be committedThe most common and most expensive mistake: writing an API key or token into .claude/settings.json (which is committed) instead of settings.local.json (gitignored). Once pushed to a remote, it is effectively public. Secrets, local absolute paths, and personal sandbox addresses always go in the local layer.

​
5. Mapping any new tool to this model

The value of this coordinate system is that it works across tools. When you encounter an unfamiliar tool, answer these five questions in order and you understand its configuration surface without reading the entire documentation:
1

Where is the user-level configuration?

Which file or directory holds personal preferences that apply to all your projects?
2

Which file is the project-level rules file?

Which file is committed to version control and takes effect for the whole team?
3

Is there a local override layer?

Is there a gitignored personal configuration entry point?
4

Where is the privacy / training opt-out toggle?

How do you opt out of data training or set a data retention period?
5

How are permissions controlled?

Can you restrict what the tool reads, writes, and executes? Where are deny / ask / allow configured?
Answer all five and you can start using it safely, rather than discovering “I set this and it did nothing” or “I accidentally committed a secret” after the fact.

​
Tool comparison

Configuration layer mapping across vendors (as of 2026-05; exact filenames and mechanisms are subject to each vendor’s current documentation; per-item details in 02-2 and 02-6):
The comparison table gives coordinates, not detailsThis table tells you “what the same layer is called in your tool.” The exact semantics of each cell (what overrides what, which files are committed) are fast-moving facts; verify them in 02-2 (Claude) and 02-6 (others) with dated notes. The key takeaway: almost every vendor has the user / project / local scope axis; the differences are only in filenames and how complete the local layer is.

​
Common pitfalls

Anti-pattern list
  • Assuming all layers use “higher overrides lower”: settings.json uses override, but CLAUDE.md uses concatenation and permissions uses merge. Using the wrong mental model has a real debug cost (Section 1).
  • Writing personal preferences into team-shared project rule files: your language preference and sandbox URL in ./CLAUDE.md pollute every teammate’s context. That belongs in CLAUDE.local.md or the user layer.
  • Writing secrets into committed configuration files: settings.json goes into version control; secrets belong in settings.local.json (Section 4).
  • Not knowing a setting is being overridden by a higher-priority layer: “I clearly set this, why isn’t it working?” is almost always a closer layer covering it, or a managed policy locking it out. First confirm which layer is actually in effect.

​
Self-check

The bar for passing this unit
  1. Can you name where your primary tool’s “user-level” and “project-level” configuration files live, and which ones are already committed to version control?
  2. Given an API key, a team style rule, and a personal language preference, can you say for each: “which cell, commit or gitignore?”
  3. Can you explain why ~/.claude/CLAUDE.md and ./CLAUDE.md do not override each other, while the same key in two settings.json files does?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
  • [1] Anthropic, “Claude Code settings” (setting precedence: managed, CLI, local, project, user; file locations; permissions as cross-layer merge), Claude Code Docs. https://code.claude.com/docs/en/settings (as of 2026-05)
  • [2] Anthropic, “How Claude remembers your project” (CLAUDE.md hierarchy and concatenation loading, CLAUDE.local.md, @path import syntax, .claude/rules/, Claude Code reads CLAUDE.md not AGENTS.md), Claude Code Docs. https://code.claude.com/docs/en/memory (as of 2026-05)
  • Related: 02-2 Claude configuration item by item; 02-6 configuration comparison across tools; 04-1 CLAUDE.md and memory files; 04-2 rules files.