What does CLAUDE.md actually do — and where does it stop?

CLAUDE.md is a rules file read into context at session start — excellent as a stable constitution, and structurally unable to be a memory: it is written by hand, served whole every session, ranked by nothing, and no outcome ever updates it. Keep it for the rules that never change; give the living decisions a record that learns.

what it is good at thirty stable lines need no infrastructure

A short CLAUDE.md is genuinely load-bearing: build commands, non-negotiable conventions, the shape of the repo. It arrives every session and costs little. If your project's truth fits in thirty stable lines, you may not need anything else.

the four walls each one structural — no amount of discipline removes them

hand-writtenthe session that learned something ends, and a human must remember to write it down

served wholeevery rule rides every session, relevant or not — and the file only grows

ranked by nothingline 200 competes with line 3, and a model skims both

never correcteda rule that stopped being true keeps being served until someone notices

Teams feel this as the rules file that grows until the agent starts ignoring it — the file became a memory dump, and a flat file is the wrong structure for memory.

constitution and record, together the two compose — nothing asks you to delete your rules

Keep CLAUDE.md short, stable, hand-curated. Let the record hold what changes: decisions captured at turn end with provenance, served when relevant, confidence moved by outcomes — worked strengthens, failed retires. Measured on live completions, the one-shot violation rate with load-bearing rules served from the pinned record was 0.167, against 0.417 without it.

npx memcell connect