# Maintainable for whom?

> Our whole quality vocabulary (maintainable, readable, clean) silently assumes a human will hand-edit the code later. If agents do the maintaining, the definition doesn't die, it inverts in surprising places.

- Author: Jonas Rohde (@edhor)
- Published: 2026-07-20
- Canonical: https://edhor.me/blog/maintainable-for-whom/
- Tags: ai-agents, maintainability, code-quality, agentic-coding, developer-experience

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](/blog/good-for-new-joiners-good-for-agents/): 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](/blog/how-to-claude-md/) that
  [taxes every session](/blog/be-aware-of-the-context-window/).
- **"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.