Nested CLAUDE.md Never Loads at Start

The annoyance

I dropped CLAUDE.md under src/billing/ so the billing rules would be in every session. The file sat there, finished. /memory listed the parent files. Claude ignored the nested rules until much later — or never, if I only Wrote or Created in that tree.

I had the usual suspects. A stale CLI. A worktree. A file one directory too high. Then I Read a file in that folder and the same instructions appeared first time.

It is not a silent parse miss. It is the documented load order.

What Anthropic actually says

From the official Debug your configuration page, common-causes table:

Symptom: “Subdirectory CLAUDE.md instructions seem ignored”
Cause: “Subdirectory files load on demand, not at session start”
Fix: “They load when Claude reads a file in that directory with the Read tool, not at launch and not when writing or creating files there. See how CLAUDE.md files load.”

The Check context section is the same rule, and it is the first thing to prove:

“If a memory file is missing from the /context breakdown, check its location against how CLAUDE.md files load. Subdirectory CLAUDE.md files load on demand when Claude reads a file in that directory with the Read tool, not at session start.”

The How Claude remembers your project page is the load contract. Files above cwd come in at launch. Files under cwd wait:

“CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand when Claude reads files in those directories.”

The “How CLAUDE.md files load” section is sharper on the nested case:

“Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.”

After /compact, the same page is blunt. Project-root CLAUDE.md is re-injected. Nested files and path-scoped rules are not:

“Project-root CLAUDE.md survives compaction: after /compact, Claude re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories and rules with paths: frontmatter reload as Claude reads files they apply to.”

The fix

Move anything that must survive every session into project-root CLAUDE.md, or .claude/CLAUDE.md. Keep package-local notes nested only when lazy load is intentional.

# Loads at every session start
./CLAUDE.md
# or
./.claude/CLAUDE.md

## Billing
Never write a charge without an idempotency key.

# Loads only when Claude Reads a file in that tree
./src/billing/CLAUDE.md

## Local layout
Invoice templates live in src/billing/templates/.

The root file is the one that loads at launch and comes back after compact. The nested file is for layout that only matters once Claude is already in that tree. Same split as the CLAUDE.md diet: facts that are always true stay short and high; the rest waits.

Prove it

/memory lists locations. It does not prove the nested file is in this session. Official text:

“To check which files actually loaded into the current session, run /context.”

Prove the nested file is absent at launch, then prove a Read brings it in.

# In-session: /context
# Check Memory files. Nested src/billing/CLAUDE.md is absent at launch.
# /memory lists locations, including parent files; /context shows what loaded.
# Then Read any file in that subdirectory. Do not Write. Do not Create.
# Run /context again. The nested CLAUDE.md should now appear under Memory files.

Write and Create do not count. The debug table is explicit: the nested file loads when Claude Reads a file in that directory, not when it writes or creates one there.

Checklist

1. Put must-survive-every-session rules in project-root CLAUDE.md or .claude/CLAUDE.md.
2. Leave nested CLAUDE.md for notes that should wait until Claude Reads in that tree.
3. Run /context at launch and confirm the nested file is absent from Memory files.
4. Read a file in that subdirectory, then run /context again.
5. After /compact, expect the nested file to drop until the next matching Read.

Why it fails

I treat every CLAUDE.md as launch context. The name is the same. The folder looks finished. The load contract is not the same. Parent files come in at start. Nested files wait for a Read, and they wait again after compact. That is the sibling of the compact drop: the instruction left the window, and a Write will not bring it back.

Same family as Claude Code ignores AGENTS.md — the file is in the tree, /context does not list it, and nothing throws. The documented place, or the documented trigger, is a different one.

If you want to run this with other operators rather than on your own, we are doing that in the public Skool community, and that is https://www.skool.com/navaigate.

Sources

• Anthropic — How Claude remembers your project
• Anthropic — Debug your configuration
• The CLAUDE.md Diet
• The Compact Drop
• Claude Code Ignores AGENTS.md
• NavAIgate Skool community