Many coding agents read a plain-text instruction file from your repository before they start work. Teams often treat it as a place to dump every preference they have ever had. The result is a long file that the agent follows inconsistently and nobody maintains.

A better way to think about it: the file is a briefing for a capable new colleague who cannot ask questions. Write what they could not figure out from the code in a few minutes, and nothing else.

Write down what the code can't tell you

Good entries share one trait: they hold information that is not discoverable by reading the repository.

  • How to run things. The exact commands to build, run the fast test subset, run a single test, and start the dev environment. Agents waste a lot of effort guessing these.
  • Non-obvious constraints. "Migrations must be backward compatible for one release." "This directory is generated; edit the template instead." "Never call the payment client directly; use the wrapper."
  • Where decisions live. Pointers to design notes or ADRs for the areas where the code looks odd for a reason.
  • What done means. Which checks must pass, and what a reviewer in this repo expects in a change description.

Automate what can be checked

If a rule can be enforced mechanically, enforce it with a linter, formatter, type checker, or pre-commit hook, and keep it out of prose. "Use single quotes" in an instruction file is a weak, probabilistic version of something a formatter does perfectly. Mechanical enforcement also gives the agent immediate feedback: it runs the check, sees the failure, and fixes it.

A useful test for each line you are tempted to add: *could a tool fail the build on this?* If yes, write the tool config. If no, and it is not discoverable from the code, it belongs in the file.

Keep the file short and honest

Every instruction competes for attention with the task itself. A few practices keep the file useful:

  • Prefer specifics over virtues. "Write clean code" says nothing. "Public functions need a docstring stating units for numeric arguments" is checkable.
  • Date or justify surprising rules. A rule with a reason gets applied with judgment. A rule without one gets applied rigidly or ignored.
  • Review it like code. When an agent repeatedly makes the same mistake, add a line. When a line has not mattered for months, delete it. Stale instructions are worse than none because they are still obeyed.
  • Test it. Give an agent a small, realistic task in a clean checkout and see whether the file was enough. Where it stumbles is where the file is missing something.

The closing point

The file is not a policy document. It is the smallest set of facts that lets a newcomer make a correct first change, with everything enforceable pushed into tooling. If you cannot explain why a line is there, remove it.

AI Coding AssistantsDeveloper ToolsSoftware Engineering