CONCEPT Four scopes, loaded broadest → most specific
CLAUDE.md isn't one file — it's a hierarchy of scopes, each living in a fixed location and serving a different audience. All discovered files are concatenated into context (they don't override one another). They load in order from broadest scope to most specific, so more-specific instructions appear later in context — which is how the effective precedence works out for conflicting guidance.
| Scope | Location | Shared with | Use for |
|---|---|---|---|
| Managed policy (enterprise) | macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL: /etc/claude-code/CLAUDE.mdWindows: C:\Program Files\ClaudeCode\CLAUDE.md |
All users on the machine | Org standards, security & compliance |
| User | ~/.claude/CLAUDE.md | Just you (all projects) | Personal prefs, tooling shortcuts |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
Team, via source control | Architecture, standards, workflows |
| Local | ./CLAUDE.local.md (gitignore it) |
Just you (this project) | Sandbox URLs, personal test data |
CONCEPT Two things that map onto the same layers — but aren't the same
The scope names mirror the settings.json hierarchy (managed / user / project / local), and it's
easy to conflate them. Keep them straight: settings enforce; CLAUDE.md guides.
claudeMd key inside managed-settings.json. That key is honored only
in managed/policy settings — setting claudeMd in user, project, or local settings has no effect.DIAGRAM Concatenation order in context
/Library/... or /etc/... (org-wide)"] --> U["User
~/.claude/CLAUDE.md"] U --> P["Project
./CLAUDE.md or ./.claude/CLAUDE.md"] P --> L["Local
./CLAUDE.local.md (gitignored)"] L --> CTX["🟢 All concatenated into context
broadest first → most specific last"] classDef pol fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef mid fill:#e2e3f3,stroke:#6c63ff,color:#2a2a6a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class M pol; class U mid; class P mid; class L mid; class CTX ok;
CODE What lives where
A typical layout across the four scopes on one developer's machine.
# Managed policy — deployed by IT, applies to everyone, can't be excluded /Library/Application Support/ClaudeCode/CLAUDE.md # User — your personal preferences across every project ~/.claude/CLAUDE.md # Project — checked into git, shared with the whole team my-repo/CLAUDE.md # (or my-repo/.claude/CLAUDE.md) # Local — your private per-project notes; add to .gitignore my-repo/CLAUDE.local.md # Org-wide memory injected via managed settings instead of a file: # managed-settings.json { "claudeMd": "Always run `make lint` before committing.\nNever push to main." }
TRADE-OFFS Project CLAUDE.md vs. CLAUDE.local.md
✅ Project CLAUDE.md
- Committed → shared with the team
- One source of truth for conventions
- Reviewed like any other code
- Best for standards, architecture, workflows
⚠️ CLAUDE.local.md
- Private, gitignored — only on your machine
- Good for sandbox URLs, personal test data
- Doesn't travel across git worktrees
- Being superseded by home-dir imports (see 1.3)
EXAM TRAPS
.claude/." → User memory is
~/.claude/CLAUDE.md in your home dir. The project's .claude/CLAUDE.md is a
project-scope file shared via git.claudeMdExcludes." →
Managed policy CLAUDE.md cannot be excluded. Excludes only skip ancestor project/team files.claudeMd in project settings for team-wide memory." → The
claudeMd settings key is honored only in managed/policy settings. For team memory, commit a
project CLAUDE.md.PRACTICE
Q1 · List the four CLAUDE.md scopes in load order and give each location.
Managed (/Library/Application Support/ClaudeCode/CLAUDE.md, /etc/claude-code/CLAUDE.md,
or C:\Program Files\ClaudeCode\CLAUDE.md) → User (~/.claude/CLAUDE.md) →
Project (./CLAUDE.md or ./.claude/CLAUDE.md) → Local
(./CLAUDE.local.md). Broadest first, most specific last.
Q2 · Two files conflict: user says "use tabs," project says "use 2 spaces." Which wins?
Project, effectively — it loads after user (more specific = later in context). Both stay in context; ordering resolves the conflict. Cleaner still: remove the contradiction.
Q3 · How does an org push a rule to every repo on every machine, unremovable by users?
A managed policy CLAUDE.md at the platform path, or a claudeMd key in
managed-settings.json. Both load before user/project memory and cannot be excluded by individual
settings.