Domain 2 · 20%% of exam

The CLAUDE.md hierarchy and load order

Where memory files live, in what order they load, and why nested files behave differently.

6 min read · Lesson 3 of 11 in this domain

Memory files are how you give Claude Code standing context about a codebase without repeating yourself every session. The design has two halves worth understanding separately. Discovery: Claude walks up from your working directory to the filesystem root collecting files, so a monorepo package inherits the repo-wide conventions above it. Delivery: everything collected is concatenated and sent as a user message after the system prompt — which is precisely why it is guidance and not configuration. Files below your working directory are handled differently, loading only when Claude actually reads a file there, so a large monorepo does not flood the context at launch.

Key points

Claude Code walks up the directory tree from your working directory, collecting CLAUDE.md and CLAUDE.local.md at each level.
All discovered files are concatenated, not overridden. Order is filesystem-root-first, so instructions nearest your working directory are read last.
Within a directory, CLAUDE.local.md is appended after CLAUDE.md.
Files in subdirectories below your working directory load on demand — when Claude reads a file in that directory — not at launch.
CLAUDE.md content is delivered as a user message after the system prompt. That is precisely why it is context rather than enforced configuration. For system-prompt-level text use --append-system-prompt.
Target under 200 lines per file. Longer files consume context and measurably reduce adherence.
After /compact, the project-root CLAUDE.md is re-read and re-injected. Nested files are not — they reload lazily.

Diagram

Discovery walks up, loads root-first

Reference

Scope	Location
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS) /etc/claude-code/CLAUDE.md (Linux/WSL)
User	~/.claude/CLAUDE.md
Project	./CLAUDE.md or ./.claude/CLAUDE.md
Local	./CLAUDE.local.md (gitignore it)

Worked example

Reading the order. You launch in repo/services/api/. Claude collects repo/CLAUDE.md (company-wide conventions), repo/services/CLAUDE.md (service conventions), then repo/services/api/CLAUDE.md (this service's specifics) — root first, nearest last. Nothing overrides anything; all three are in context together. If the root says "use tabs" and the API file says "use spaces", you have not configured a winner, you have handed the model a contradiction to resolve. Keep narrower files additive rather than contradictory.

Exam trap

Several third-party guides claim user CLAUDE.md lives at ~/.claude.json. It does not — it is ~/.claude/CLAUDE.md.

Check your understanding

Where does a personal, all-projects CLAUDE.md live?

Correct answer: B — ~/.claude/CLAUDE.md
~/.claude.json holds OAuth session and MCP state — it is not a memory file. Several third-party guides get this wrong.

Three CLAUDE.md files exist up the tree. What happens?

Correct answer: B — All are concatenated, root first
Nothing overrides anything; instructions nearest your working directory are simply read last.

Practise this domain with 20%%-weighted questions in the study app.

Open in study app

← Previous

Permissions: enforcement vs guidance

Path-scoped rules with .claude/rules/

Source: Claude Code Docs — Memory · Independent study aid, not affiliated with or endorsed by Anthropic.