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. Nothing was hidden from it. 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/               out of the everyday search path
    notes-final-2.md     retired, and it used to be found first

How it works

Placement decides what actually gets loaded. Claude Code walks up from your and loads every instruction file it passes, ordered from the filesystem root down, so the file closest to where you started is read last. Files in subdirectories 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 the session can reach every file but loads only the root instructions until it wanders. Start inside the one directory the work lives in and it loads that directory's rules plus every ancestor's, 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. Content searches skip anything in , so build output and installed packages stay out of results on their own. Checked-in generated code and vendored libraries do not: they get searched, matched and read like real source until you exclude them deliberately. 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. Keep the active pointer at the entry with history behind it, and move retired material out of the normal discovery path instead of leaving it beside the current copy.

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.

Layered instructions drift. Two files can end up contradicting each other, and Anthropic's memory documentation says the model may then pick one arbitrarily.

A pointer nobody updates reads exactly like a true one, which is the same trap as the archive folder in a different costume. And a readable tree changes what the model finds first, which is worth a great deal, while enforcing nothing at all.