CLAUDE.md, AGENTS.md and the file that makes a coding agent useful

A coding agent arriving in your repository knows the language and knows nothing about you. It does not know that the tests need a container running, that the legacy/ directory is frozen, that your team writes migrations in a particular way or that the utils module is where things go to die.

You can explain that every session, or you can write it once. That file — CLAUDE.md, AGENTS.md, whatever the tool reads — is the highest-leverage thing in the repository once agents are in use, and almost every one we see is either absent or three times too long.

What belongs in it

How to run things. The exact commands for install, build, test, lint and a single test. Not "npm test" if the real answer is "npm test requires the docker-compose stack up first, and the integration suite needs TEST_ENV=local". This alone removes the most common failure: an agent that cannot verify its own work and therefore does not.

The layout, in five lines. Where the entry points are, what each top-level directory contains, where the thing that surprises people lives. An agent that has to search to find the API layer will find it, eventually, after reading files it did not need.

The conventions that are yours and not the language's. Not "use meaningful variable names". Things like: errors are wrapped with fmt.Errorf and never logged at the point they are created; every endpoint goes through the permission decorator; SQL lives in the repository layer and nowhere else. Three to eight of these, the ones you would correct in review.

The prohibitions, with reasons. Do not edit files under generated/. Do not upgrade the ORM, it is pinned for a reason. Do not add dependencies without asking. A rule with a reason attached survives; a bare rule gets interpreted around.

Where to look for context. Pointers to the architecture doc, the runbook, the schema. Agents follow references well, and a pointer costs one line where the content would cost fifty.

What does not belong in it

Anything derivable from the code. Listing the modules and what each one does duplicates something the agent can read and guarantees a file that is wrong within a month. Stale context is worse than absent context because it is followed confidently.

Prose about your values. "We care about quality" changes nothing. Every line should be actionable or deletable.

Full API documentation. It bloats the context window on every single turn, including the ones that do not touch the API.

Anything secret. These files are read aloud into a model's context and committed to a public-ish repository. No internal hostnames you would not publish, no credentials, obviously, but also no unreleased product names in a repo that might get open-sourced.

Why the long ones stop working

A context file is prepended to essentially every request. At three hundred lines it is competing for attention with the actual task, and the practical effect is that the model follows the first and last few instructions and drifts on the middle. It also costs tokens on every turn, which is real money at volume.

The discipline is the same one that keeps a README useful: one page, and every line earns its place. If you need more, split it — most tools support nested files so that frontend/CLAUDE.md is loaded only when the agent works in that directory. That scoping is how large monorepos keep the root file short.

Keep it honest

Treat it as code: reviewed in pull requests, updated when the build commands change, and pruned when a rule stops being true. The tell that a file has gone stale is that people have started correcting the agent about the same thing in chat rather than fixing the file, which is the documentation equivalent of routing around a broken process.

A good habit: after any session where you corrected the agent twice on the same point, add the line. Over a couple of months the file converges on exactly the tacit knowledge a new hire would need, which is a pleasant side effect — the onboarding document writes itself, in the only format anyone actually maintains.

What to do this week

Open your main repository and check whether the test command in the context file still works. In about half the repos we look at it does not, which means every agent session has been starting from a false statement and working outwards.