What CLAUDE.md and AGENTS.md can hold, and what they cannot
Instruction files should hold stable conventions that apply to every task. They are the wrong place for findings, because the whole file is read on every task, nothing in it carries evidence, and nothing in it ever expires.
Every team using coding agents ends up with an instruction file. CLAUDE.md, AGENTS.md, a rules file, a prompt preamble. It starts at fifteen lines and it is genuinely useful. Then it grows.
Six months later it is four hundred lines. It contains the test command, a paragraph about a migration that finished in March, three warnings about a service that no longer exists, and one line that is load bearing and that nobody dares delete because nobody can remember what breaks without it.
The file is not the problem. Using it as the team's memory is.
What instruction files are good at
They are good at anything that is true for every task, stable over months, and cheap to state.
- Toolchain and commands. Use pnpm, not npm. The test command is
pnpm test. Node 24. - Conventions with no discoverable trace. Server components by default. Put stateful interaction in a focused client component.
- Prohibitions. Never edit generated files. Never commit to main directly.
- Orientation. Where the code lives, what the module boundaries are, which directory is a build artifact.
These share a shape. They are policy rather than fact. They do not have a truth value that the code could contradict, so they cannot quietly become wrong when someone merges a pull request. If the team changes its mind, someone edits the file, and that edit is the change.
What they are bad at
Findings have the opposite shape. "The staging bucket is in eu-west-1, not eu-central-1, which is why the signed URLs fail there." That is a fact about the system, and the system can change underneath it.
Three properties of instruction files make them a poor container for facts.
Everything is read on every task. There is no relevance step. A note that matters to one file in one repository is paid for, in tokens and in attention, on every unrelated task. That cost pushes teams to keep the file short, which is in direct conflict with using it to accumulate what the team learns.
Nothing carries evidence. A line in an instruction file is an assertion with no attached reason. You cannot ask why it is there, when it became true, who established it, or what would have to change for it to stop being true. The commit that added it is the only trace, and by the time anyone looks the commit message says "update CLAUDE.md".
Nothing expires. A wrong line and a right line look identical. The wrong one is obeyed with exactly as much confidence as the right one, and it is obeyed by every agent on every task until a human notices. That is the failure mode we call context rot, and instruction files are where it does the most damage, because their whole content is authoritative by default.
A working boundary
The test we use is whether the statement could be falsified by a merge.
If a change to the repository could make the line wrong without anyone editing the line, it is a finding, and an instruction file is the wrong home. If the line can only become wrong when the team decides differently, it is a convention, and the instruction file is exactly the right home.
Applied to a real file:
| Line | Kind |
|---|---|
| Use pnpm with the pinned lockfile | Convention, keep |
| Run lint, typecheck and the production build before finishing | Convention, keep |
| The auth middleware runs before the rate limiter | Finding, and a merge can falsify it |
Do not use the legacy_users table, it is being migrated out | Finding with an expiry date nobody set |
| Prefer server components | Convention, keep |
The last two are the ones that hurt. They were true and useful when written. They are the reason the file cannot be trusted a year later.
What to do with the findings
Short answer: not the instruction file, and not nowhere.
A few teams push them into documentation, which at least gives the reasoning room to exist, but a document has no relationship to the code and no way to notice when the code moves away from it. Some push them into code comments, which is the most durable option available today, because the comment sits next to the thing it describes and moves with it. That works when the finding is about one function. It does not work when the finding is about the relationship between two repositories, which is where the expensive knowledge tends to be.
What the findings actually need is a place that can do three things an instruction file cannot: hold the evidence alongside the claim, be retrieved only when relevant instead of on every task, and be re-checked against the code so a claim that has gone stale can be marked stale rather than repeated. That is the system REM is being built to be. It is in private beta and we are not going to pretend otherwise here.
In the meantime, the cheap improvement is to stop letting the two kinds of statement share a file. Keep the instruction file to conventions and keep it short. When you catch yourself adding a fact about how the system currently behaves, that is the signal that you have run out of instruction file and started needing a memory.
A practical trim
Read the file with one question per line: could a merge make this wrong?
For each line where the answer is yes, either delete it, or move it next to the code it describes, or write down what evidence would confirm it. That last option is the one that scales, and it is the one almost nobody does by hand, which is the whole reason this problem is still open.