Nine rules I wrote for my AI agents, and the failure behind each

The instruction file my coding agents read is 79 lines long. Nine of those lines are a block a tool writes for me. The rest is prose, and inside it sit nine numbered rules that I added one at a time, always after something had gone wrong.

None of them is a preference. That is the whole selection criterion, and it took a while to arrive at.

#A controlled study found generated context files make agents worse, not better

For most of the last year, the advice was to write more. Describe the architecture. The conventions. The testing approach. The review standards. Then in February 2026 a team at ETH Zürich measured it — 138 tasks drawn from twelve Python repositories, four different coding agents, three conditions: no context file, one written by a model, and one written by the repository's own developers.

The generated files lost. Success rates fell by 0.5 to 2% against giving the agent no context file at all, while inference cost rose by more than 20%. Developer-written files gained, but modestly — around 4%, and only when they stayed minimal. The behavioural detail is the part worth sitting with: agents given a context file ran more tests, searched more files, traversed more of the repository and produced more reasoning tokens. They worked harder and finished worse.

The paper's own conclusion is that unnecessary requirements make tasks harder, and that a human-written file should describe only minimal requirements. Which is correct, and not yet actionable. Minimal is a property you can only check once you have already decided what counts.

#Five of the nine exist because something broke without producing an error

Five. That is more than half of them, and it is not a coincidence — every one of these fails while looking exactly like success.

• An ancestor with `overflow-hidden` silently disables `position: sticky`. No warning, no console message. The element simply stops sticking, several components away from the CSS that caused it.
• The body is the scroll container here, so `window` scroll listeners never fire. The listener attaches, the handler is correct, the events never arrive. IntersectionObserver is the answer.
• Visitor tracking does nothing under `next dev`. React StrictMode's mount, cleanup and remount cycle trips an initialisation guard, and the listeners never re-attach. Everything looks fine in development and only production is real.
• `saveVisit()` returns `false`. It never throws. So a partial failure and a complete success are indistinguishable unless you read the return value.
• Adding a page means adding it to `STATIC_ROUTES` too. Miss it and a monitor reports the new page as a 404 on every check, forever. Nothing on the site breaks, so nobody notices.

An agent is unusually exposed to this class of problem, and the reason is worth naming. It cannot tell the difference between a task that worked and a task that produced no error, because for most tasks those are the same signal. A human eventually notices the page looks wrong. An agent reports success and moves on to the next thing.

#Two exist because the framework moved and the training data did not

middleware.ts is gone in this version of Next.js. It is proxy.ts now, exporting a proxy(request) function with a statically-read config.matcher, running on the Node runtime. A model trained before that change will write middleware.ts with complete confidence, and the file will sit there doing nothing.

The second one is smaller and more annoying: next/image accepts exactly one quality value in this project, because the config option that would allow others is unset. Every other number fails.

Neither of these is a bug and neither is a preference. They are places where the model's most probable answer is wrong for this repository, which is a different reason for a rule to exist and, I think, the most durable one. The version will keep moving.

#One of the nine is not about code at all

There is an idea I have already considered, thought about properly, and deliberately parked. It is a reasonable idea. It is reasonable enough that a fresh agent, looking at the same evidence, proposes it — and then the next one proposes it, and the one after that.

So the ninth rule says: this has been decided, do not raise it unprompted, and here is the one specific symptom that would make it worth raising again. It encodes a judgement rather than a fact, and it is there because repeating a rejected suggestion costs attention every single time.

I have not seen this category discussed anywhere, and it is the rule I would least like to lose. A new agent has no memory of what you have already turned down. Without a note, it will keep finding the same good idea for as long as the repository exists.

#A line earns its place when you can name the failure it prevents

That is the whole rule, and it is why the file is 79 lines rather than 400. Before adding anything I have to be able to finish the sentence: *this is here because on such-and-such a date, this specific thing happened.* If the sentence does not finish, the line does not go in.

It rules out most of what people put in these files. Architecture overviews go out, because the agent can read the architecture. Coding style goes out, because the linter enforces it and an agent reading the surrounding code will match it anyway. Testing philosophy goes out. General best practice goes out hardest of all — it is the purest form of the unnecessary requirement the study found is costing success.

The one exception I allow is the ninth rule, which is not an incident but a decision, and I would rather be honest that the criterion has an exception than pretend it does not.

#The top of my file is machine-written, and I commit it anyway

Nine of the 79 lines are generated. next dev writes a block at the top saying this version of the framework differs from what is in your training data, and pointing at the docs bundled in node_modules. It re-adds itself if you delete it, so removing it from a diff only produces the same uncommitted change again the next time the dev server runs.

Which makes my file a hybrid of exactly the two categories the study separated — a generated block sitting on top of nine hand-written rules — and I cannot tell you which side of the line it lands on. Nine generated lines is a long way from the bloated generated file the paper measured. It is also not nothing, and I did not choose it.

I commit it because fighting a tool that rewrites a file on every run is a worse use of a morning than accepting nine lines of accurate warning. But it is a good reminder that the file is not entirely mine, and that the next version of the tool could make that block considerably longer without asking.