D3 · Claude Code › Cluster 1 · Memory & CLAUDE.md

1.6 · Nested / Sub-directory CLAUDE.md

Path-scoped guidance

CONCEPT Ancestors load eagerly; descendants load lazily

The tree walk from 1.3 has two halves, and the exam leans on the difference:

🔑 This is what makes nested CLAUDE.md a path-scoping tool. A 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 cwdWhen it loads
cwd and every parent directory up to rootAt launch, in full (root-down order)
A subdirectory below cwdOn 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:

⚠️ If an instruction "disappears" after /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

flowchart TD ROOT["repo/CLAUDE.md
(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"] }
Prefer nested CLAUDE.md when guidance is tied to a whole subtree. If you want even finer control (by file extension/glob), reach for a path-scoped rule in .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

Trap: "All CLAUDE.md files in the repo load at startup." → Only ancestors of cwd load at launch. Subdirectory files load on demand when Claude reads a file there.
Trap: "A nested CLAUDE.md overrides the root one." → They're concatenated. The nested file loads after ancestors (more specific = later), but both are in context together.
Trap: "After /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.
Trap: "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.