Writing a CLAUDE.md (or AGENTS.md) that actually helps your agent

There's one file that does more for a coding agent's output than any prompt-engineering trick: the repo's context file, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, whatever your tool reads. The agent treats it like an onboarding doc. A good one is the difference between a teammate and a flailing intern. Most are useless. Here's how to write one that isn't.

What to put in it

Think like you're onboarding a fast, literal new hire who can read code but doesn't know your shop:

• How to run things. Build, test, lint, and run commands, spelled out exactly. The agent shells out; give it the commands instead of making it guess. This one section alone changes results, because it lets the agent close the test loop itself.
• Conventions that aren't obvious from the code. Naming patterns, the architecture you follow, libraries you've standardized on, libraries you've banned. The things a new hire learns by getting a PR rejected.
• What NOT to touch. Generated files, the fragile legacy service, the module that breaks if you look at it wrong. Bounding the agent away from danger is as valuable as pointing it at the work.
• The gotchas. The undocumented staging step, the flaky test it shouldn't trust, the API whose real behavior contradicts its docstring. This is where agents walk into walls. Write the wall down.
• Where things live: a brief map of the project structure, so it doesn't waste a turn rediscovering it.

What to leave out

This is where most context files go wrong: they bloat.

• Anything the agent can read from the code. Don't restate function signatures or describe what a file obviously does. The code is right there; restating it is noise that dilutes the signal.
• A novel. The file (or its description) is loaded every turn: every line costs tokens and competes for attention with the lines that matter. A tight, 40-line file beats a rambling 400-line one. Brevity is a feature here.
• Aspirational rules nobody follows. Document reality, not the style guide you wish your team obeyed. If the codebase uses tabs and the file says spaces, the agent gets conflicting signals and trusts the wrong one.

A context file is read every turn, so every word is a recurring tax. Write it like you're paying by the line, because you are.

How to write it well

• Imperative and specific. "Run tests with pytest -q. Never edit files in generated/." Not "we value clean code."
• Lead with the load-bearing stuff. Put how to run things and what not to touch near the top.
• Iterate from failure. Every time the agent does something wrong, that's a candidate line. The file is a living record of "things I had to correct," which is exactly software as memory: the corrections you make today become context tomorrow.

Two things the pros do

Keep it cacheable. The context file is part of your stable prefix. Keeping it tight and byte-stable means it caches. Bloating or churning it costs you on every single request.

Use progressive disclosure for big projects. Don't pile every convention into one giant always-loaded file. Split task-specific guidance into skills loaded on demand, so the always-on context stays small and the detail loads only when relevant. One huge CLAUDE.md is the thing progressive disclosure exists to replace.

The headline: this file is the cheapest, best investment you can make in agent quality, and almost nobody writes it well. Spend twenty minutes making yours specific and honest, and every agent you point at the repo gets measurably better, for free, on every task, forever.