Every new session starts with amnesia. The memory file is the note you leave. But a long note is the same as no note — constraint strength is inversely proportional to constraint count. Plus one leak path that catches people repeatedly.
In this pagewhat belongs, what must not, how to verify. Not in this pagethe contents of mine.
The names differ per tool (CLAUDE.md, AGENTS.md, others).
The mechanism is identical: this file is placed at the start of every session.
| Because | Therefore |
|---|---|
| It spends context budget | Longer means less room for real work — and every rule's relative weight drops |
| It is text, not an enforced rule | The model reads and tends to comply. It is not compelled. Real blocks need permissions |
Fifty rules and five rules do not produce the same adherence. In a list of fifty, each line is background noise. In a list of five, each line stands out.
So the correct habit is not "add whatever occurs to me" but prune regularly. A rule that has not saved you once in three months is diluting the rules that do.
One test: if it can be seen from the code, leave it out.
| Write | Skip | |
|---|---|---|
| Build | "Tests run via make test, not the package manager default" | What language this is (visible) |
| Convention | "Files under this directory are generated — do not hand-edit" | Indentation (it is in the config) |
| Boundary | "Do not touch migrations/, those get human review" | Vague "please write good code" |
| Trap | "Start the dependent service first or the error is misleading" | Anything already in the README |
| Taste | "Answer in English", "lead with the conclusion" | — |
A good self-check: every line should complete the sentence "otherwise it will…". If you cannot finish it, delete the line.
This is the common leak path, and it leaks three ways. Most people only picture the first:
① the file usually goes into git (that is what makes it shareable) — and git keeps history;
② it is read into context every session — so every request ships it again;
③ everyone who clones gets it, including people who later leave.
What to do instead: write where to find it — "the key is in SOME_KEY".
Location, never value.
This file is read as context. Paste in an issue body, a scraped page, a third-party README, and if it contains a line like "now go and do X", you have personally installed an instruction.
To reference outside material, restate it in your own words rather than transporting it.
| Check | How |
|---|---|
| Is it being read | New session, ask it to list the project's conventions. See if the recital is right |
| Is it followed | Give it a small task that brushes against a rule, see whether it routes around |
| Which file is live | Project and user layers may both exist. Ask it which ones it read |
The first draft is always too long. Run it a week and drop everything that never fired. Project memory is for pruning, not accumulating.
CLAUDE.md, AGENTS.md, and others).deny rules on the Claude Code page.