Every serious agent reads a project file before it does anything: CLAUDE.md for Claude Code, AGENTS.md for Codex and a growing number of others, .cursor/rules for Cursor. Different names, same job — tell the agent what this repository is before it starts guessing.
Most people either skip it or fill it with things the agent could work out on its own. Both are wasteful.
The test for whether something belongs#
Ask: could the agent figure this out by reading three files?
If yes, leave it out. It will read the three files. Listing your directory structure is a waste of context — ls exists.
If no, write it down. Anything that lives in a person's head, in a Slack thread, or in a decision made two years ago is exactly what belongs here.
The five things worth writing#
1. What the system is, in two sentences#
Not the README pitch. The operational reality.
Payments service. Go 1.23, Postgres, deployed on Fly.
Money is involved: never guess at a rounding rule — ask.That second line does more work than a page of architecture description. It sets a stopping condition.
2. The commands that verify work#
The single highest-value line in most memory files is the one that tells the agent how to check itself.
- `make check` must pass. It runs vet, lint and the race detector.
- `make test-integration` needs Docker running; it is slow, run it once at the end.Without this the agent will invent a command, get an error, and spend three turns discovering your build system. With it, it self-corrects before showing you anything.
3. Invariants that are not visible in the code#
This is the part that prevents the expensive failures.
- internal/ledger is double-entry. Every write needs a matching
counter-entry in the same transaction, or the invariant test fails.
- Migrations in db/migrations are append-only. Never edit one that
has shipped; write a new one.
- pkg/generated is regenerated from proto. Editing it is always wrong.Each of these is a rule someone learned the hard way. None of them can be inferred by reading a file.
4. How to work here, as a procedure#
Agents follow numbered steps well. Use that.
1. Read the failing test before you read the source.
2. Change one thing, run `make check`, then continue.
3. If a change touches internal/ledger or db/migrations, stop and
summarise the plan before writing code.Step 3 is a gate. Gates are the cheapest safety mechanism you have — they cost one sentence and they stop the class of change you most regret.
5. Explicit prohibitions#
Negative instructions work better here than anywhere else, because they are unambiguous.
## Do not
- Do not add dependencies without asking.
- Do not "fix" a flaky test by adding a retry.
- Do not reformat files you were not asked to change.That last one saves more review time than anything else on the list.
What to leave out#
Your directory tree. It goes stale in a week and the agent can list files.
Coding style already enforced by a linter. If Prettier fixes it, do not describe it. Point at the command instead.
Aspirational rules nobody follows. If half the codebase violates a rule you wrote down, the agent now has to reconcile the document with the reality, and it will pick whichever it saw more recently. Write down what is true, not what you wish were true.
Long prose. Everything in this file competes for attention with the actual code. Two hundred lines of guidance means the agent is reading your essay instead of your source.
Keep it honest#
A memory file that is wrong is worse than none at all, because the agent trusts it over the code. Give it the same treatment as a test: when the thing it describes changes, it changes in the same commit.
A good habit is to add a line to your PR template: does this change make anything in the memory file untrue?
Starting from nothing#
If you are staring at a repository you did not write, do not write this file yourself on day one. Ask the agent to read the codebase and draft it, then correct the draft. It will get the mechanical parts right — build commands, entry points, test layout — and it will get the invariants wrong, which tells you exactly which lines are worth your attention.
Correcting a wrong draft takes twenty minutes. Writing one from scratch takes an afternoon and you will still miss things.
Next: scoping a request so the diff is small enough to actually review.