What belongs in CLAUDE.md or AGENTS.md?

Standing instructions that apply to every session: the build and test commands, conventions the agent cannot infer, directories it must not touch, and how to run things locally. Not history, and not anything that was true once.

Why does a long CLAUDE.md make the agent worse?

It is read in full on every session, so every line costs context on every turn and competes with the instructions that matter. Rules that contradict each other or no longer hold are worse than absent ones.

Where should the things I remove from it go?

Facts that were true once belong in searchable history rather than in a file read every session — the transcripts already hold them, and recall can fetch the relevant one when it matters.

When your rules file gets too long

read in full, every session — so every line is paid for on every turn

It starts as five lines about the build command. Six months later it is four hundred, half of it describing a migration that finished in spring, and the agent seems to be reading less of it rather than more.

The cost of a rules file is paid every session

CLAUDE.md, AGENTS.md, GEMINI.md and the rest are read in full at the start of every session. That is the point of them — and it is also the constraint. Every line competes for context with the actual task, and unlike a search result nothing weighs it against relevance: the paragraph about a database you no longer run arrives with the same authority as the build command.

Three failure modes follow, in the order people hit them:

Stale rules. Something that was true once and is now wrong. This is the expensive one: the agent follows it confidently.
Contradiction. Two rules added months apart that cannot both hold. The model picks one, usually the later or the longer.
Dilution. Nothing is wrong, there is just too much, and the three lines that mattered are surrounded by two hundred that did not.

What belongs in it

A rule earns its place if it is true on every session and the agent cannot work it out from the repository:

How to build, test and run locally, with the flags this project actually needs.
Conventions that are not visible in the code — the reason a pattern is used, not the pattern itself.
Boundaries: what must not be touched, what must never be committed, what needs a human.
Where things are, when the layout is surprising.

If you can imagine a session where the line is irrelevant, it is not a rule; it is a fact about one moment.

What does not, and where it goes instead

Facts about one moment are the bulk of what makes these files grow: the incident in March, the flag that turned out to matter for one service, the approach that was tried and reverted. They are worth keeping — just not in a file the agent re-reads every time.

They are already kept. The session where you worked it out is on disk, written by the harness itself, and it is still there. An index over those transcripts answers the same question at the moment it comes up rather than paying for it every session:

deja how "go test"                    # the invocation this project actually uses
deja fix "pq: too many connections"   # what was run after that error, where it stayed fixed
deja blame internal/index/ingest.go   # what earlier sessions decided about this file

With recall wired in the agent asks those itself, and the block is absent when the history has no answer — which is the property a rules file cannot have.

A way to shorten one

Go through the file line by line and ask two questions. Is this true on every session? Could the agent find it out from the repository in one step? A line that fails the first is history; a line that fails the second is noise. What survives is usually a page, and the rest is not deleted so much as moved to where it can be retrieved on demand.

One caution: do not convert a rules file into a memory system by hand. Writing down each fact you might need later is the same manual step that made the file long, and the sessions already contain them.

Why agents forget · What memory costs in tokens · When the same wall comes back