The instruction file is the only thing you write once that shapes every future session. It is also, in most repositories, four hundred lines of aspirational prose that the agent reads and mostly ignores.
Short answer: an instruction file is prepended to every request, so every line you add competes with your actual code for attention and budget. Write the things the agent cannot discover by looking, in the imperative, with a reason attached. Delete everything it can see for itself. Sixty good lines beat four hundred vague ones, and the difference is measurable in output.
What the file is and where it goes
Two conventions, converging. AGENTS.md is the cross-tool convention: a markdown file in the repository root that any agent can read. Claude Code uses CLAUDE.md with a documented hierarchy of user-level, project-level and directory-level files, where the more specific file wins.
Practically: put one at the repository root, add directory-level files only where a subtree genuinely differs, and keep personal preferences in your user-level file rather than committing them.
The mechanism is unremarkable and worth stating precisely, because everything else follows from it. The file is loaded into context at the start of the session and resent with every request. It is not consulted when relevant. It is always there, always costing tokens, always competing.
The test for whether a line belongs
Could the agent work this out by reading the code?
If yes, delete the line. It is describing something the agent can see, at the cost of crowding out the thing it cannot.
Things it can see, and that appear in almost every bad instruction file:
- The directory structure. It can run
ls. - The tech stack. It can read
package.json. - What the tests are written in. It can open one.
- The general purpose of the project. The README exists.
- Formatting rules that a formatter enforces. The formatter enforces them.
Things it cannot see, and that almost never appear:
- Which of two existing patterns is the one you are migrating toward. The codebase contains both. Only you know which is the future.
- What is deliberately weird. The retry loop that looks wrong and is load-bearing for a downstream system.
- Where the boundaries are. Which directories are generated, which are vendored, which nobody may touch.
- The command that actually verifies the work. Not the README’s aspirational one, the one that really passes.
- Conventions with no artefact. Error handling style, logging expectations, how you name things and why.
Write rules, not essays
The failure mode is prose. Prose gets summarised in the model’s head and the specifics fall out.
Not this:
We generally try to keep our components fairly small and focused, and we have found over time that it tends to work better when state management is handled at a higher level rather than being scattered around, although there are some exceptions.
This:
Components hold no state. Lift state to the nearest route-level container. Exception:
packages/editor/, which manages its own.
Second version is a third the length, has no hedging, and names the exception. An agent following the first one will do something reasonable and unpredictable. An agent following the second will do what you said.
Three rules that make the difference:
- Imperative, not descriptive. “Use X” rather than “we tend to use X”.
- Give the reason when the rule is surprising. A rule with a stated reason survives cases you did not anticipate, because the agent can extrapolate. A bare rule breaks at the first edge case.
- Name the exception explicitly. Every real codebase has them. An unstated exception guarantees the agent will violate the rule in the one place where violating it is correct, or follow it in the one place where it should not.
What a long file actually costs
Three separate costs, and the third is the one that surprises people.
Tokens, every turn. The file is resent constantly. A 400-line file on a long session is a real line on your bill, which is the mechanics in what agents cost and where the tokens go.
Attention. Sitting near the front of the context is the best position in the window, and a bloated file spends that position on filler. Twenty important rules diluted across four hundred lines get followed less reliably than twenty rules in sixty lines. The mechanics are in why your agent forgets.
Contradiction. This is the real killer. Long files accumulate, nobody prunes, and eventually line 340 contradicts line 60. The agent picks one, apparently at random, and you conclude it does not follow instructions.
A structure that works
Roughly this order, roughly this length.
Commands, first. The exact build, test and lint invocations. Put these at the top because they are the most-used lines in the file and they are the thing the agent most often gets wrong by guessing.
Boundaries. What not to touch. Generated directories, vendored code, anything with a hand-written warning at the top.
Conventions that have no artefact. The handful of things a linter cannot check and a reader cannot infer.
The exceptions. Where the above does not apply, named specifically.
Verification. What “done” means in this repository. The one command that must pass. This connects directly to verifying agent work and it is the line most worth getting right.
Sixty to a hundred lines covers this comfortably for most projects. If yours is longer, something in it is describing the code.
Maintaining it without a ritual
Two habits, both cheap.
Add a line when you correct the agent twice for the same thing. Not the first time, that might be a one-off. The second time, it is a convention you never wrote down. This is the natural way these files grow correctly, because every line has a real incident behind it.
Delete a line when it stops being true. A stale instruction is worse than a missing one, because the agent will follow it confidently. Instruction files rot faster than code and nobody reviews them, so it is worth reading yours end to end once a quarter.
One thing worth watching for: if you find yourself writing the same instruction into five repositories, it belongs in your user-level file instead, or in a shared convention document the projects reference.
The uncomfortable observation
If your instruction file has to explain a great deal about your codebase, that is information about the codebase.
Confusing structure, inconsistent naming and undocumented conventions are hard for agents for the same reasons they are hard for new hires. The instruction file compensates; it does not fix. Teams that keep improving their file eventually notice they are documenting problems rather than solving them.
Fixing the underlying structure improves agent output more than any file can, and it improves everything else too. That is the broader argument in what an AI coding agent actually is: an agent is a reader with no institutional memory, and a codebase that reads well is a codebase agents work well in. It also changes what review has to catch, which is the subject of reviewing code your agent wrote.