Answer
What should go into a coding agent's project instructions?
The commands, the conventions that are not enforced by tooling, and the facts about the system that reading the code cannot reveal.
Three things: the commands to build, test and check; the conventions your tooling does not enforce; and the facts about the system that reading the code cannot reveal. Anything else is duplicating something inspectable.
The file works best when it is treated as the answer to what a competent stranger would have to ask, restricted to questions whose answers are stable. That framing keeps it short, and short is what keeps it followed: every additional line competes with the others, so a file that lists everything is a file that is followed approximately.
Commands come first and are the most immediately useful content. How to build, how to run the tests, how to run one test, how to check formatting, how to start the thing locally. These are looked up constantly, they are stable, and getting them wrong wastes an entire turn. This is also the section most likely to be out of date, which is an argument for testing the file against reality occasionally.
Unenforced conventions come second, and the emphasis is on unenforced. If the formatter enforces the style, saying it in the file adds nothing and costs attention. If the team has a convention about error handling, module boundaries or naming that nothing checks, that is exactly what needs stating — and it is also a candidate for being moved into a check, which is strictly better than stating it.
The third category is the facts the code does not show. Which of two similar paths is live. Why the obvious approach was tried and abandoned. Which module is being replaced and should not be extended. What depends on a given interface in a way that is not visible from it. These are the highest-value lines in the file and they are the ones that are almost never written, because everyone who knows them has stopped noticing that they are not obvious.
What to leave out is as important. Descriptions of the directory structure, which the agent can see. Explanations of what the project does at a level that does not affect any decision. Rules restating what the tooling enforces. Aspirations about how the code should be written that the code does not currently follow, which put the agent in the position of choosing between the file and the evidence.
That last one deserves emphasis because it is common. A file describing the intended architecture of a system that has drifted from it will produce changes that match neither: the agent partially follows the document and partially follows the surrounding code. Where the aspiration is real, the honest form is to say what the current state is, what the target is, and which applies to new code.
If a linter can say it, the linter should say it, because a rule in a document competes for attention and a rule in a check does not.
Siddharth Sharma, Context Theory
Related questions
How long should the file be?
Short enough that you would re-read it when something goes wrong. Beyond that length its errors become permanent, because nobody checks it against reality and it continues to be supplied. Splitting by area helps more than compressing, since a reader can then verify one section against the code it describes.
Should it be generated from the codebase?
The parts worth having cannot be generated, which is a useful test of whether a line belongs. Commands, unenforced conventions and non-obvious history are all things a person knows and the code does not state. Anything a generator could produce from the repository is by definition something the agent could establish by looking.
METHOD
Every figure below carries its source and the date it was verified. Nothing on this page is asserted.
The numbers on this page.
| What | Value | Specific to |
|---|---|---|
| Visibility lift in AI-generated answers from GEO methods | up to 40% | Category-wide |
| Close rate — response under 5 minutes vs over 24 hours | 32% vs 12% | Category-wide |
Aggarwal et al., "GEO: Generative Engine Optimization", Princeton / Georgia Tech / IIT Delhi / Allen Institute for AI — KDD 2024 · GEO-bench · 10,000 queries across 8 domains · verified
Optifai speed-to-lead benchmark · n=939 companies · Q2 2025–Q1 2026 · verified
What is specific to this page.
| Kind | Claim | Check it against |
|---|---|---|
| Workflow | The admission test for a coding agent's instruction file is what a competent stranger must ask whose answer is stable, which excludes structure descriptions the agent can inspect and status that changes between sessions. | Checking each line against whether the agent could establish it from the repository. |
| Software | A convention already enforced by tooling adds nothing when restated in the instruction file and consumes attention shared with rules that are not enforced, so the correct move for a stated convention is usually to convert it into a check. | Identifying which rules in the file are already enforced by the formatter, linter or type system. |
| Response | Facts invisible in the code — which of two paths is live, which approach was abandoned and why, what depends on an interface from outside it — are the highest-value entries and are rarely written because those who know them no longer perceive them as non-obvious. | Collecting the questions asked by the last person to join the codebase and checking which are answered in the file. |
| Constraint | An instruction file describing an intended architecture that the code has drifted from produces changes matching neither, because the agent partially follows the document and partially follows the surrounding code it can see. | Comparing the architectural claims in the file against the current structure of the code they describe. |
Each row would be wrong on another industry's page. Where a sourced figure exists it is in the table above instead; these are the constraints that shape the work and do not happen to be numbers.
Start with the measurement.
Reading about a benchmark is not the same as knowing your own number. The audit produces yours, measured rather than estimated.
$497 · delivered in 5 business days · credited against month one