CONCEPT Ancestors load eagerly; descendants load lazily
The tree walk from 1.3 has two halves, and the exam leans on the difference:
- Above your cwd (ancestors): every
CLAUDE.md/CLAUDE.local.mdfrom your working directory up to the root loads in full at launch. Ordering is root-down, so the file closest to where you launched Claude is read last. - Below your cwd (descendants):
CLAUDE.mdfiles in subdirectories are not loaded at launch. They're pulled in on demand — the moment Claude reads a file inside that subdirectory.
src/frontend/CLAUDE.md stays out of context until Claude actually works under
src/frontend/ — so a monorepo can give each area its own conventions without every session paying
for all of them.| File position relative to cwd | When it loads |
|---|---|
| cwd and every parent directory up to root | At launch, in full (root-down order) |
| A subdirectory below cwd | On demand, when Claude reads a file there |
Within one directory: CLAUDE.md then CLAUDE.local.md |
Local is appended after CLAUDE.md at that level |
CONCEPT Compaction & the lazy-load gotcha
Because nested files load lazily, two behaviors trip people up:
- After
/compact: the project-root CLAUDE.md is re-read from disk and re-injected, so it survives. Nested CLAUDE.md files are not re-injected automatically — they reload the next time Claude reads a file in that subdirectory. - Monorepo noise: ancestor CLAUDE.md files from other teams may get picked up. Use the
claudeMdExcludessetting (glob patterns against absolute paths) to skip them — but note managed policy CLAUDE.md can never be excluded.
/compact, it was either given only in
conversation or lives in a nested CLAUDE.md that hasn't reloaded yet. Put durable rules in a CLAUDE.md so they
persist; the root one always comes back.DIAGRAM A monorepo tree and what's in context
(ancestor → loads at launch)"] --> FE["repo/frontend/CLAUDE.md"] ROOT --> BE["repo/backend/CLAUDE.md"] CWD["You launch in repo/frontend/"] --> INCTX["🟢 In context now:
repo/CLAUDE.md + repo/frontend/CLAUDE.md"] FE -.->|"already an ancestor of cwd"| INCTX BE -.->|"below a sibling — NOT loaded
until Claude reads a backend/ file"| LAZY["🟠 Loads on demand"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class INCTX ok; class LAZY gate;
CODE Path-scoped conventions via nested files
Each area carries only the rules relevant to it; they enter context when Claude works in that subtree.
# repo/CLAUDE.md — always loaded (ancestor) ## Global - Conventional Commits for every commit - Never commit secrets # repo/frontend/CLAUDE.md — loads when Claude touches frontend/ files ## Frontend - React function components only; hooks over classes - Styling via Tailwind utility classes # repo/backend/CLAUDE.md — loads when Claude touches backend/ files ## Backend - FastAPI routers in `app/routers/` - All DB access through `app/db/session.py` # Skip a noisy other-team file (in .claude/settings.local.json): { "claudeMdExcludes": ["**/other-team/CLAUDE.md"] }
.claude/rules/ with
paths: frontmatter instead.TRADE-OFFS Nested CLAUDE.md vs. one root file
✅ Nested / sub-directory files
- Area-specific rules load only when relevant
- Keeps launch context small in big repos
- Each team owns its own subtree file
⚠️ One big root CLAUDE.md
- Simple — one place to look
- But everything loads every session (token cost)
- Mixes unrelated conventions → lower adherence
EXAM TRAPS
/compact all my CLAUDE.md files come back." → Only the
project-root file is re-injected automatically. Nested files reload only when Claude next reads a file in
that subdirectory.claudeMdExcludes can silence any CLAUDE.md, even the org's." →
Managed policy CLAUDE.md can never be excluded; excludes only skip project/team files.PRACTICE
Q1 · You launch Claude in repo/frontend/. Is repo/backend/CLAUDE.md in context?
Not at launch — it's below a sibling, not an ancestor of cwd. It loads on demand only if
Claude reads a file under backend/. Loaded at launch: repo/CLAUDE.md and
repo/frontend/CLAUDE.md.
Q2 · A subdirectory rule vanished after /compact. Why, and what returns it?
Nested files aren't re-injected on compaction — only the project-root CLAUDE.md is. The nested rule reloads the next time Claude reads a file in that subdirectory.
Q3 · When do you pick a nested CLAUDE.md over a .claude/rules/ path rule?
Use a nested CLAUDE.md when guidance applies to a whole subtree and should load whenever
Claude works there. Use a path-scoped rule when you need finer targeting by file glob/extension via
paths: frontmatter.