Maintainable for whom?

If an agent is taking care of the code, what is “maintainable” even meaning? Maintainable for humans, or for agents?

That question got stuck in my head, because “but is it maintainable?” is the most senior-sounding question in every code review. It ends discussions. Nobody is against maintainability, like nobody is against safety.

But the word has a hidden assumption we never had to spell out. For decades the answer was so obvious nobody asked: maintainable for a human, with a human’s working memory, a human’s reading speed and a human’s patience. If agents write and maintain most of the code, that assumption breaks… and I don’t think the word gets useless then, it just needs a new definition.

TL;DR

• “Maintainable” always meant “maintainable by a future human hand-editing this file” → that part was never questioned
• A lot of it survives the shift: clear names, one obvious pattern, discoverable structure help agents exactly like they help humans
• But some rules invert: verbosity, repetition and “too many” comments are cheap for agents → implicit conventions and tribal knowledge, which humans tolerate, are the deadly part now
• My new definition: maintainable is what a fresh context window can safely change

What survives

The good news first: most classic maintainability advice was never really about humans, it was about readers, and agents are readers too. A fresh agent session is structurally a new joiner: no tribal knowledge, only what’s discoverable. So everything that helps a new joiner still holds:

• self-explaining names and structure
• one way to do a thing, not three half-migrated ones
• the why written down where the code can’t say it
• tests that state the intended behavior, not the implementation

If your codebase is a mess, agents won’t save you. They’ll just produce mess faster. So no, maintainability is not obsolete, it’s what the agents themselves depend on.

What inverts

Now the uncomfortable part. Some rules we treated as timeless were actually workarounds for human limitations, and those flip:

• “Don’t repeat yourself, ever.” DRY exists because humans forget to update the second copy. An agent greps all copies in seconds. Aggressive abstraction to save keystrokes (keystrokes are free now) often just adds indirection a fresh context has to unwind first. Some duplication with local clarity beats a clever abstraction three files away.
• “Comments are a smell.” This one I really reversed on completely. The old logic: comments drift, humans hate maintaining them, code should speak for itself. But agents read every comment on every session and update them while they edit. An inline “why” comment is context exactly where it’s needed, paid for exactly when it’s needed. The opposite of a bloated CLAUDE.md that taxes every session.
• “Keep files short.” Human-sized files were about scrolling and cognitive load. For agents the unit that matters is not file length, it’s whether a change is local: can you touch this behavior without holding five distant files in context?
• “Clever and compact is elegant.” Nobody is reading the code for pleasure anymore. Boring, explicit, maybe even verbose code that a model can’t misread wins against the clever one-liner every time.

And the things humans tolerate best (implicit conventions, “everyone knows we do it like this”, knowledge living in one colleague’s head) are exactly what agents can’t survive. We optimized for the weaknesses of a reader who is not the main reader anymore.

The new definition

The definition I landed on for myself: code is maintainable if a fresh context window can safely change it. Safely meaning: find the right place, understand the local why, make the change and verify it, without a human feeding it tribal knowledge and without unintended blast radius.

To be clear, this doesn’t mean humans stop reading code. You’ll still read code, on the level of review, architecture and “is this actually what I meant”. And a codebase a fresh agent can safely change is one a human can safely read too. The reader changed, not the care.

So next time “but is it maintainable?” ends a discussion, ask the hidden question out loud: maintainable for whom? If the honest answer is “for a kind of maintenance that stopped happening”… then maybe you are not defending quality anymore, just a habit.