CLAUDE.md & the Memory Hierarchy

Every Claude Code session starts with a fresh context window — Claude remembers nothing from yesterday. A CLAUDE.md file is how you carry knowledge across that gap. Think of it as the onboarding doc you hand a new teammate: the build command, the test runner, the directory layout, the two or three conventions they'd get wrong on day one.

The single most important thing to internalize: CLAUDE.md is loaded as context, not as enforced configuration. Claude reads it at session start and tries to follow it — but there is no hard guarantee of compliance, exactly as a human teammate might forget a guideline under pressure. This one fact explains almost every design decision in the system, so hold onto it.

A good CLAUDE.md answers a precise question for every line: "Would Claude make a mistake here without this instruction?" If Claude already does the right thing — say, it naturally runs your tests — the rule is noise. Delete it. The goal is a small, dense file of facts Claude can't guess, not a style manual.

There is a second, complementary system worth naming up front: auto memory, where Claude writes its own notes (build commands it discovered, a debugging insight) to MEMORY.md. The split is clean: you write CLAUDE.md; Claude writes auto memory. This lesson focuses on CLAUDE.md, the part you control.

CLAUDE.md instructions can live in four places, each with a different scope. They are listed here from highest precedence to lowest, but precedence here doesn't mean override — it means load order. All discovered files concatenate into context; nothing replaces anything. The rule to memorize: the closer a file is to your working directory, the later it loads — and the last thing Claude reads carries the most weight.

Think of it as concentric rings, from broadest to most specific. The managed policy tier is special: deployed by an organization via MDM/Group Policy/Ansible, it applies to every session on the machine and cannot be excluded by individual settings — that's the whole point of a policy. (In a monorepo you can skip other CLAUDE.md files with the claudeMdExcludes setting, but never the managed-policy file.)

Because everything concatenates with project-level last, your project's ./CLAUDE.md is read after the user file, and your private ./CLAUDE.local.md is appended after that — so your most specific, most local instructions get the final word.

How does Claude find these files? It walks up the directory tree from your current working directory, checking each directory for CLAUDE.md and CLAUDE.local.md. Run Claude in foo/bar/ and it loads foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md alongside them — all the way up to the filesystem root.

The ordering rule is precise and worth committing to memory:

• Across the tree, content is ordered from the filesystem root down to your cwd. So foo/CLAUDE.md appears before foo/bar/CLAUDE.md — instructions closer to where you launched are read last.
• Within a single directory, CLAUDE.local.md is appended after CLAUDE.md — your personal notes are the last thing read at that level.

# Launched in foo/bar/ — load order, top = first, bottom = last (most weight):
Managed policy CLAUDE.md      (if deployed)
~/.claude/CLAUDE.md           (user)
foo/CLAUDE.md                 (ancestor project)
foo/CLAUDE.local.md
foo/bar/CLAUDE.md             (closest project)
foo/bar/CLAUDE.local.md       <- read last, most weight

Subdirectories below your cwd behave differently. Claude discovers CLAUDE.md files in subdirectories too, but it does not load them at launch. Instead, a subdirectory's CLAUDE.md is pulled in on demand — only when Claude actually reads a file in that directory. This keeps a big monorepo's context lean: you only pay for the instructions in the parts of the tree you're actually touching.

Here is the most consequential detail in the whole system, stated exactly: CLAUDE.md content is delivered as a user message after the system prompt — it is not part of the system prompt itself. Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions.

Three practical consequences follow:

1. Specific beats vague — every time. Concrete, verifiable instructions are followed far more reliably than fuzzy ones.

   Write this	Not this
   Use 2-space indentation	Format code properly
   Run npm test before committing	Test your changes
   API handlers live in src/api/handlers/	Keep files organized

2. Contradictions get resolved arbitrarily. If two files give conflicting guidance for the same behavior, Claude may pick one at random. Periodically review your files (and nested ones) to prune outdated or clashing rules.

3. For guarantees, don't use CLAUDE.md at all. If something must happen at a specific moment — lint before every commit, block writes to a path — write a hook. Hooks run as shell commands at fixed lifecycle events and apply regardless of what Claude decides. That's the enforcement layer; CLAUDE.md is the advice layer.

If you genuinely need an instruction at the system-prompt level, the escape hatch is the --append-system-prompt flag — but it must be passed on every invocation, so it suits scripts and automation, not interactive use.

You rarely write a CLAUDE.md from a blank page. Run /init and Claude analyzes your codebase, then generates a starter file with the build commands, test instructions, and project conventions it discovers. From there you refine — add the handful of things Claude wouldn't discover on its own (the gotchas, the "never touch legacy/" rules).

Key behaviors:

• If a CLAUDE.md already exists, /init does not overwrite it — it reads what's there and suggests improvements instead. Safe to re-run.
• It's codebase-aware beyond just Claude: running /init in a repo with an existing AGENTS.md reads it and folds the relevant parts into the generated CLAUDE.md. It also reads other tool configs like .cursorrules and .windsurfrules.

For a richer setup, set the environment variable CLAUDE_CODE_NEW_INIT=1 to enable an interactive, multi-phase flow:

CLAUDE_CODE_NEW_INIT=1 claude
# then, inside the session:
/init

In that mode /init asks which artifacts to set up — CLAUDE.md files, skills, and hooks — explores the codebase with a subagent, asks follow-up questions to fill gaps, and presents a reviewable proposal before writing any files.

CLAUDE.md is loaded into the context window at the start of every session, spending tokens alongside your actual conversation. That cost drives the cardinal rule: target under 200 lines per file. Longer files consume more context and reduce adherence — the irony of a bloated instruction file is that the very rules you wrote get lost in the noise and ignored.

A discipline that keeps files tight:

• Apply the test to every line: would Claude err without it? If not, cut it.
• Structure with markdown headers and bullets. Claude scans organized sections the way you do; dense paragraphs are harder to follow.
• Add a rule when you've hit the same problem twice — Claude repeats a mistake, a review catches something it should've known, or you type the same correction you typed last session. That's the signal to write it down.
• Move the wrong-shaped content out. A multi-step procedure belongs in a skill (loads only when invoked). An instruction that only matters for one part of the tree belongs in a path-scoped rule under .claude/rules/ — it loads only when Claude touches matching files.

When a file genuinely needs to grow, split by topic into .claude/rules/. A rule with a paths: frontmatter (e.g. src/api/**/*.ts) loads only when Claude reads matching files, saving context everywhere else. (Note: @path imports help organize but do not save context — imported files still load in full at launch.)

Long sessions eventually hit /compact, which summarizes the conversation to reclaim context. A natural worry: does my CLAUDE.md survive? For the part that matters most, yes.

• Project-root CLAUDE.md is re-injected from disk after /compact. Claude re-reads the file and puts it back into the freshly compacted session. Your core project instructions persist by design.
• Nested subdirectory CLAUDE.md files are not automatically re-injected. They reload the next time Claude reads a file in that subdirectory — the same on-demand mechanism as initial discovery.

This yields a useful diagnostic. If an instruction vanished after compaction, it was one of two things: (a) it was given only in conversation and never written to a file, or (b) it lives in a nested CLAUDE.md that hasn't been re-triggered yet. The fix for (a) is the recurring theme of this lesson — if you want it to persist, write it to CLAUDE.md, don't just say it in chat.