Your Agent Instructions Are Rotting Right Now

There's a particular kind of file that only ever grows. You know the one. It started as a short list of project conventions for your agent, and every time something went sideways you appended a line to stop it happening again. Always run the build before committing. Don't touch the lockfile. Use the existing helper instead of writing a new one.

Every line was correct on the day it was written. That's what makes this hard to see.

Because instructions aren't code. Nothing fails when they go stale. There's no red test, no type error, no failing pipeline. A rule that stopped being true six months ago sits there looking exactly like a rule that's still true, and the agent — being obedient — follows both with equal conviction.

Instructions don't break loudly. They just quietly stop describing your project.

The context is the product made the case that what you feed an agent matters more than which model you picked. This is the uncomfortable follow-up: that context is an artifact you own, and artifacts you own need maintenance. Nobody budgets for maintaining a text file.

How the rot actually happens

It's never one dramatic mistake. It's four small, reasonable things.

The project moves and the file doesn't. You migrate from one test runner to another, rename a directory, drop a library. The code changes in one commit. The instruction describing the old world changes in... no commit, because nobody thought about it. Now the agent is confidently steering toward a folder that isn't there.

Rules get added to fix single incidents. The agent did something dumb once, so you wrote a rule. The rule is narrow, situational, and phrased as a universal law. Twenty of those later, you've encoded a list of past accidents rather than a description of how the project works.

Nothing ever gets deleted. Deleting a rule feels risky — what if it was load-bearing? So the file only accretes. And because instructions usually sit near the top of the agent's context, every dead line is taking up room that live information could be using.

Contradictions arrive silently. Rule 4 says prefer the shared utility. Rule 19, added months later by someone solving a different problem, says write it locally in the feature folder. Both are in the file. The agent picks one, more or less arbitrarily, and now its behavior looks random — which is the symptom people usually misdiagnose as the model being unreliable.

That last one is worth sitting with. When an agent behaves inconsistently across similar tasks, the instinct is to blame the model or add another rule. Often the real cause is that you've given it two rules and asked it to guess.

The symptoms, before you go looking

You can usually feel this before you can point at it.

The agent starts doing things you don't remember asking for, and when you grep the instructions, there it is — a line from months ago you'd completely forgotten writing. Or it does the right thing four times out of five, and the fifth is a coin flip. Or you find yourself correcting the same class of thing in review over and over, adding a clarification each time, and the clarifications aren't helping. That's the tell: if adding rules isn't improving behavior, the problem isn't a missing rule. It's the pile.

Honestly, the strongest signal is simpler. When was the last time you read your instructions file top to bottom? If you can't remember, you're not maintaining a document, you're maintaining a sediment layer.

Treat it like code, because it is

The fix isn't clever. It's just deciding that this file has an owner and a lifecycle, the same as any other part of the system.

Read it end to end on a schedule. Not when something breaks — on a cadence. It takes ten minutes. You will find at least one line that describes a project that no longer exists.

Delete aggressively. This is the part people won't do, so let me put it plainly: a rule you can't justify today is doing damage today. It's consuming context, and it's a coin-flip waiting to happen when it eventually contradicts something newer. If you're wrong and it mattered, you'll find out fast and can put it back in thirty seconds. That's a cheap mistake. Carrying twenty dead rules is not.

Prefer describing the system over listing incidents. "Feature code lives under src/features/{feature}, and anything shared moves to src/shared only when a second feature needs it" is worth ten rules about specific files. Principles survive refactors. Incident notes don't.

Hunt contradictions directly. When you review, don't just ask is this line true? Ask does this line disagree with another line? Contradictions are the expensive failure here, and they're invisible unless you're specifically looking.

Update instructions in the same commit as the change. You renamed the folder — the rule mentioning that folder is part of the rename. This is the one habit that stops rot at the source, and it costs nothing once it's automatic.

I've had to redo this myself

I'm not writing this from the outside. The memory system on this site is exactly this problem in a different shape — a set of files an agent reads before it does anything, describing conventions and decisions.

I wrote up the first version, published it, and then redesigned the whole thing after a few weeks of actually using it. Not because the original idea was wrong, but because the first design let information accumulate without ever forcing anything out. The rules that ended up mattering were about overwriting rather than appending: this file gets rewritten in full, that entry gets edited in place rather than duplicated, completed items get deleted rather than archived. Not because deletion is elegant. Because anything that only grows eventually stops being read — by me, and by the agent.

That's the lesson I'd extract for instructions generally. The interesting design question isn't what to write down. It's what forces something to leave.

Small is a feature

There's a version of this article that ends with "so audit your rules regularly," and that's true but weak. The stronger claim is that the size of an instruction file is itself a quality signal, in the wrong direction.

A short, current, internally consistent set of rules beats a comprehensive one, every time. The agent reads all of it. You can hold all of it in your head. When something's wrong you can find it. A long file fails on all three, and it fails invisibly, which is the worst property a piece of configuration can have.

So the question I'd ask about your instructions isn't whether they're thorough. It's whether you'd be comfortable reading them out loud to a new engineer joining tomorrow — and how many lines you'd catch yourself apologizing for on the way through.

If you've found a maintenance rhythm that actually sticks — something better than "review it when the agent embarrasses you" — I'd like to hear it. That's the part I'm still refining.