most instruction files rot for one reason: they’re doing two jobs at once.

there’s the standing rules job. always commit as this author. never push straight to main. run the linter with this flag. things that are true every single time, and expensive when the agent guesses wrong.

then there’s the stuff that crept in. the current sprint. the name of the bug we fixed last month. which library version we’re on. facts that were accurate the day someone typed them.

the first job is what the file is for. the second is what kills it.

the difference that fixes most of it

rules are things that are always true. memory is things that became true.

“commits use this email” is a rule. it was true last year, it’s true now, it’ll be true next year, and an agent that gets it wrong costs you a rejected push.

“we migrated off the old auth service” is memory. it’s a fact with a timestamp on it. six months from now it’s noise, but it’s still sitting in the file being read into context on every single run.

the failure isn’t that memory is bad. it’s that memory belongs somewhere that can be updated, superseded, and forgotten. an instruction file has no mechanism for forgetting. everything you put in it is permanent until a human deletes it, and nobody ever deletes anything.

so the file grows, and the ratio of signal to stale trivia gets worse, and eventually the useful rules are buried in the middle of two hundred lines where they get the least attention.

the test i’d apply to every line

three questions, and a line has to pass all three.

is it always true? not usually true, not true this quarter. if it has an expiry date, it’s memory.

would the agent get it wrong otherwise? if it’s discoverable from the repo in one look, cut it. “this is a typescript project” is visible from the files. you’re spending context to say something the agent can already see.

does getting it wrong actually cost something? a rejected commit, a broken build, a leaked address, an angry customer. if the worst case is mild stylistic drift, it’s a preference, and preferences aren’t worth permanent context.

most lines in most instruction files fail at least one. usually the second.

what this looks like on ours

we run a fleet of agents, each with its own instruction file, so we get to see which lines earn their keep over months rather than days.

the ones that survive are almost boring. commit authorship, because the wrong email fails a check. which directories belong to which agent, because two agents editing the same file is a real collision and not a hypothetical one. which environments are safe to ship to without asking. every one of them is a rule that’s always true, non-obvious from the code, and costly to get wrong.

what got deleted, repeatedly, was context that felt useful when written. project status. architecture explanations that the architecture then outgrew. one file accumulated a careful description of a service that had been decommissioned, and it sat there being read into every session for weeks.

nobody notices that happening. that’s the thing. a stale line doesn’t throw an error, it just quietly makes every run slightly worse.

where the other stuff should go

if it’s a fact the agent learned, it wants a memory store: something written per-fact, updated when it changes, deleted when it’s wrong. we keep ours as separate files with a one-line index, so a fact can be revised or dropped without touching anything else.

that distinction matters more than it sounds. a rule you edit by hand, deliberately, because policy changed. a memory you let accumulate and prune. putting the second kind in the first kind’s file is what produces the two-hundred-line document nobody trusts.

one thing to try

open your instruction file and run the three questions down it, line by line. always true, non-obvious, costly if wrong.

cut every line that fails two of them. i’d expect you to remove between a third and half of it, and i’d expect the agent to behave slightly better afterwards, because what’s left is actually getting read.

if a line hurts to delete, that’s usually a sign it’s memory you care about. it doesn’t belong in the file, but it does belong somewhere.

---

5dive runs a company of AI agents on your own box, on the Claude plan you already pay for. each agent keeps its own instruction file and its own memory, separately, for exactly the reasons above. spin one up at 5dive.ai.

it’s open source too: github.com/5dive-ai/5dive