CLAUDE.md and AGENTS.md: the context files that steer agents

Every agent session on your codebase starts from amnesia. The agent knows nothing about your build, your conventions or your architecture except what it can read, and the first thing it reads is a context file: CLAUDE.md, AGENTS.md, or whatever your tool calls its standing brief. That file is the highest-leverage document in the repository right now, and most teams either do not have one or have one that actively hurts.

The best practice for CLAUDE.md and AGENTS.md files compresses to one rule: short, verified, load-bearing. Everything in the file should change what the agent does, everything should be true, and everything competes for a limited budget of attention. A context file is configuration that happens to be written in prose, not documentation.

What belongs in CLAUDE.md and AGENTS.md

Commands first. How to build, run the tests (and run one test, fast), lint, and start the app locally. This is the difference between an agent that verifies its own work in a tight loop and one that guesses. If your test command needs three environment variables and a warm database, say so, because the agent will otherwise burn twenty minutes discovering it, every session.

A map, not a tour. Where things live and where changes go: the API layer sits here, shared logic there, migrations follow this path. A dozen lines of orientation save an agent hundreds of file reads and prevent the classic failure of new code landing in a plausible but wrong place.

Conventions that differ from defaults. Agents ship with sensible generic habits, so do not restate them. Document where your team deviates: we use this result type instead of exceptions, dates are UTC everywhere, this service must never import that one. The deviations are precisely what the agent cannot guess.

Landmines. The flaky suite that needs a retry, the generated directory nobody edits by hand, the module where changes require a migration plan, the vendored dependency that looks editable and is not. One honest line per trap. This section pays for the whole file.

What does not belong

Generic advice, first among sins. "Write clean, well-tested code" changes nothing about any agent’s behavior and spends attention. The same goes for restating what your linter already enforces: the linter is the enforcement, the pipeline is where rules live, and the context file should not duplicate either.

Aspirational rules. If the codebase does not follow the pattern the file describes, the agent now holds a contradiction, and it will resolve it unpredictably: sometimes copying the code around it, sometimes obeying the file, often mixing both in one diff. Describe the codebase you have, plus the direction of travel if it is real ("new endpoints use the v2 handler pattern, old ones migrate opportunistically").

Task-specific procedure. How to write a migration or run a release belongs in a skill the agent loads when that task comes up, not in the standing brief every session carries. The context file answers "what is always true here"; skills answer "how do we do this particular thing". Keeping that boundary is what keeps both usable.

And length for its own sake. We regularly meet context files past a thousand lines, assembled by pasting in the style guide, the onboarding doc and three READMEs. Each addition felt reasonable. The sum is a file where the twelve lines that matter are buried in six hundred that do not.

How a bad file degrades every session

The failure is quiet, which is why it persists. Nothing crashes. The agent just gets slightly worse at everything: it follows the stale test command and concludes the suite is broken, obeys a rule the team abandoned last year, ignores the buried warning about the generated directory. Worse, contradictions teach it to discount the file altogether, the way developers learn to ignore a README that lied to them once. You keep paying the context cost while the benefit decays toward zero, and every engineer on the team quietly inherits the same degradation in their sessions.

The test we apply is behavioral: give an agent a routine task in a fresh session and watch. Does it find the right directory, run the right commands, follow the house conventions without being told twice? If not, the fix is almost always in the context file, and it is usually a deletion.

Maintain it like code, because it is

The file changes in pull requests, ideally in the same PR that changes what it describes: renamed the test command, update the brief. Someone owns it per repository. Every touch deletes something. And once a quarter, someone reruns the fresh-session test to catch the drift nobody noticed. Writing the first honest version takes an afternoon and is the highest-return item in making a codebase agent-ready; teams that go further usually find their whole documentation stack shifting, because agents finally gave docs a reader that acts on them.

Auditing and rewriting these files is routinely the first fix we ship in an agentic engineering engagement, and it is the cheapest delta we know: one afternoon, one file, every future session on the codebase slightly better.