Context is maintenance, not a build

Every team serious about agentic coding eventually writes the file.

CLAUDE.md, AGENTS.md, whatever the tool calls it. The document telling an agent how this codebase actually works, which conventions are real, which shortcuts are load-bearing, where the bodies are buried. Writing it is a genuine investment, and elsewhere in this track I argue for building it in-house rather than buying it, on the grounds that nobody else has the knowledge.

What almost nobody plans for is the day after.

The file gets written in one concentrated burst, usually straight after a bad experience where an agent did something wrong for lack of context. Then it sits. The codebase keeps moving and the file doesn't.

Six months later it's telling an agent the payments service uses one pattern, when three people have since migrated it to another. The agent has no instinct that anything changed. It follows the stale instruction with complete confidence.

Why this rot is quieter than it sounds

A wrong comment in code gets noticed eventually. A human reading it trips over the thing, fixes it, or complains loudly enough that somebody else does.

A stale line in a context file doesn't get read by a human at all, most of the time. It gets read by an agent, and an agent doesn't experience confusion the way a person does. It acts on what it was told, produces something subtly wrong, and the wrongness surfaces later, downstream, disconnected from its cause.

Whether anyone traces it back turns on one belief the team holds.

An org that thinks of the model as the program blames the model. The tool got worse, the vendor shipped something, we should look at alternatives. An org that knows the context is the program reads exactly the same evidence the other way round, because degraded output is what a context problem looks like from the outside.

The tells are unglamorous and already on dashboards you have. Code quality falling. More failed builds.

Neither says "go and open the markdown file." That's precisely what they mean.

That's the actual risk.

Not that the file goes stale. Every document does eventually. That staleness in this particular document is silent, and confidently acted on, rather than loud and obviously wrong.

Whoever touches it last, and one name above them

The instinct is to fix this with a calendar: a quarterly audit, a standing review slot, somebody going through the file every few months to check it still holds. That's tidy on an org chart and it doesn't survive contact with a busy quarter. A scheduled audit competes with everything else on that person's plate, loses most weeks, and the file drifts anyway, just on a documented schedule instead of an undocumented one.

The rule that holds is smaller and much less official. Whoever changes the behaviour a context file describes updates the file in the same change.

Not a separate ticket. Not a follow-up. The same pull request. Migrating the payments service to a new pattern means the line describing the old pattern is part of what you're changing, exactly the way a test asserting the old behaviour is part of what you're changing.

It isn't a new category of work. It's the existing one, applied to a file that happens to be markdown.

On purpose, this isn't a calendar reminder. It's an extension of the instinct that already governs a good pull request. You don't leave a comment that lies about what a function does. You shouldn't leave a context file that lies about what the system does, same reason, enforced the same way, by whoever's already in there.

What it does need is a name above it.

The team does the maintaining, and one leader carries whether the file is still true, the same way they carry whether the service is up. Distributed accountability rarely works, and a file everyone maintains and nobody answers for drifts exactly like a system everyone owns and nobody runs.

Responsible is plural. Accountable is singular. And it belongs to whoever is already accountable for the code the file describes, not to a context owner invented for the purpose.

The check that catches drift anyway

Some drift is inevitable even so, because not every behaviour change is obviously a change to something the file describes.

The cheap backstop: when an agent gets something wrong in a way that traces to bad context, treat it as a bug report against the file rather than only against the output. Confidently wrong because it was confidently told wrong? Fix the file in the same breath as the code.

That failure is a gift. It just told you which paragraph is lying.

What this isn't

This isn't an argument for a smaller file, or for skipping the investment.

A thin accurate file beats a thick stale one, but size was never the point. The point is that a context file behaves more like a live system than a document. It degrades the moment nobody maintains it, and the maintenance has to be as unglamorous and automatic as updating a test, or it simply won't happen.