The document you need exists. It is called notes-final-2.md, it sits in an archive folder beside three older copies, and the version that replaced it lives in a different directory under a different name.

A fresh session searches, finds the archive first, and acts on a decision you retired last week. It was not kept from anything. The stale copy was simply easier to find than the true one.

The idea

A cold session has no private index of your project. It finds things the way a stranger would: by reading names, searching text, and inferring conventions from whatever sits nearby. Your folder layout is the search surface. The goal is to make the current truth cheaper to reach than every stale alternative, and to make the right home for a new fact obvious enough that the next file lands there without a decision.

text
project/
  CLAUDE.md              loaded at launch: the parts, one line each, where commands run
  PROGRESS.md            the active pointer: done, active, next
  docs/
    decisions/           dated: the choice, the reason, the consequence
  src/
    api/
      CLAUDE.md          loaded only when a file in src/api/ is read
      handlers/          named for what they are, so a search finds them
  archive/               still tracked, so still searched and still found
    notes-final-2.md     retired last week, and nothing in it says so

How it works

Placement decides what actually gets loaded. Claude Code walks up from your and loads every instruction file it passes on the way up, outermost first. They are added together rather than overriding each other, so a nested file extends the root file instead of replacing it, and a nested rule that flatly contradicts the root does not reliably win. Files in subdirectories below you are not loaded at launch at all: they load on demand when Claude Code reads a file in that directory. A convention written next to the code it governs arrives exactly when that code is opened, and costs nothing the rest of the time.

Where you start the session sets the same dial. Start at the project root and it carries the root instructions, your own personal ~/.claude/CLAUDE.md, and whatever else sits on the path above, but nothing from the directories below. Start inside the one directory the work lives in and that directory's rules come too, with unrelated areas out of scope from the first turn.

That is why Anthropic's guidance on large codebases recommends splitting instructions by directory rather than growing one root file. The root file's job becomes orientation: name the parts, one line each, and say where commands run. Anthropic's advice on writing those lines is worth borrowing for folder names too. "API handlers live in src/api/handlers/" is useful; "keep files organized" is not.

Reading costs context, and the tree decides how much. Anthropic's large-codebases guidance says Claude Code's content searches respect by default, so build output and installed packages stay out of results on their own. Checked-in generated code and vendored libraries do not: they are tracked, so they get searched, matched and read like real source. A directory of machine-written files sitting in the normal search path competes with yours for the model's attention.

What to do

  1. Give recurring roles recurring names, and use them everywhere: CLAUDE.md, PROGRESS.md, docs/decisions/, migrations/.
  2. Put conventions in the directory they describe, and keep the root file to what the whole project needs.
  3. Delete retired documents rather than archiving them. An archive/ folder is ordinary tracked content and gets searched like everything else, while a deleted file is still in git's history if it was ever committed: git log --all -- docs/notes.md gives you the commit ids and git show 4b1e9c2:docs/notes.md prints the file back. If you do keep one in place, make its first line read RETIRED 2026-03-04, superseded by docs/decisions/0007-email-provider.md, so a session learns that before it learns anything else.

Where it breaks

Rearranging a mature project to match an imagined ideal breaks imports, links and your own habits while improving nothing. Learn the existing convention first, then add one clear entry point.

Splitting instructions by directory has a failure of its own. A rule in src/api/CLAUDE.md is invisible to any session that never opens a file in src/api/, so anything that has to hold everywhere belongs in the root file, however much tidier it looks one level down.

A pointer nobody updates fails the same way the archive folder does: it is found first and it is out of date.