Design choices that worked when humans wrote and maintained your code start behaving differently once an agent is in the loop. The smart abstraction that was a joy to extend for a senior engineer becomes a maze for an agent. The "self-documenting" pattern that worked for your team confuses an agent that has never had the watercooler conversation. The clever DRY refactor that compressed three similar files into one parameterized module turns into a debugging tax. None of this is the agent's fault. The design was optimised for a reader the code no longer has.
This chapter is about designing systems that age well when an agent is doing a meaningful share of the reading, writing, and maintenance.
Architecture textbooks list a dozen quality attributes — modularity, coupling, cohesion, encapsulation, reusability. They all still matter. But three properties have moved up the priority list specifically because an agent is now part of the maintenance team.
How much of what you need to understand a piece of code is right there, in the file you're reading. High locality: one module that defines its types, helpers, main logic, and exports in one place. Low locality: a small file that imports from twelve others, each of which imports from twelve more.
Humans tolerate low locality because they build a mental model over weeks. Agents — even with massive context windows — pay a real cost every time they have to chase an import to understand a function. The cost compounds across a long task.
How likely a fresh reader is to find the right place when looking for something. High discoverability: file names match concepts; module structure mirrors the domain; conventional naming guides search. Low discoverability: clever names, files organised by technical layer instead of feature, abbreviations only the author remembers.
The name says what the thing does, plainly, with as much specificity as the domain allows. calculateMonthlyRecurringRevenue, not calcMRR. renderUserProfileSidebar, not renderUPS.
This sounds banal. It is banal. It's also the single highest-ROI design change you can make for agent maintainability. Agents read names literally, infer purpose from them, and write new names by analogy. A codebase where every name is obvious is a codebase the agent can extend without surprise.
"Don't repeat yourself" was sound advice when code was expensive to write and humans had to maintain it manually. With agents in the loop, the calculus shifts. Agents make duplication cheap to fix later — a careful refactor across files takes minutes. And aggressive DRY today extracts a real cost in locality right now.
The classic over-abstraction goes like this: two similar functions — say, "create user" and "create team" — get refactored into one generic "create entity" that takes a schema, a table, an email template, and a field name as parameters. The result looks cleaner by line count. To extend either path independently, an agent now has to either add a parameter (cascading changes through every caller) or branch on a discriminator inside the abstraction (defeating the abstraction). The original two functions were easy to evolve independently. The "DRY" version isn't.
The revised rule of thumb: abstract when you have three instances that are genuinely the same shape and you've observed them stay the same shape over time. Until then, write the duplication. Agents will help you keep duplicates in sync; they can't easily help you un-abstract a premature abstraction.
The Rule of Three, 2026 edition. The original rule said don't abstract until you see the pattern three times. With agents, extend it: don't abstract until you see the pattern three times and all three instances have been stable for at least a quarter. Stability is what predicts the abstraction will still fit after the next product pivot.
Most comments are either redundant ("increment i") or stale (commenting on code that's been refactored). Useful comments answer questions the code itself can't:
A comment like "we retry up to 3 times because the Stripe webhook delivery occasionally drops the first attempt during their daily maintenance window — see incident 2026-03-14" survives every refactor. A comment like "loop through the array" does not. The first documents something outside the code that the code can't tell you. The second restates what the next line already says.
The discipline shift for teams: review comments the same way you review code. Strip the noise; preserve the signal. Agents will write both kinds; you keep the signal.
One of the most useful design heuristics for agent-friendly code is to treat the file as the unit of context. An agent often loads one file, decides whether it needs more, and acts. A file that holds a complete feature gives the agent everything it needs in one read. A file that's a fragment, with helpers in utils/ and types in types/ and constants in constants/, costs four or five reads to assemble.
This doesn't mean monolithic files. It means organising by feature, not by technical layer. A "by-feature" layout pulls everything an agent needs to modify "user behavior" into one folder. A "by-layer" layout scatters it across four. Same code; very different agent experience — and, increasingly, the same applies to humans.
| By layer (older convention) | By feature (preferred now) |
|---|---|
| types/ handlers/ validators/ db/ | user/ team/ invoice/ |
| Each layer subdivides by entity | Each feature contains its own types, handlers, validators, db |
| A change to "user" touches four directories | A change to "user" touches one |
Not every codebase is yours to redesign. When you inherit one that's hostile to agents — and to humans, if you're honest — three low-risk moves capture most of the value:
uam, txr, cmp — and rename it to the full word. Modern tooling makes this safe. Over a year you reverse the entropy.None of these are real refactors. None require buy-in. They incrementally raise the floor on what an agent can do in your codebase, at near-zero cost. They're also the moves that survive the political conversation about refactoring better than a "let's redesign everything" pitch ever will.
The architecture that holds up in an agent-maintained codebase tends to be boring: feature folders, plain functions, obvious names, comments that explain why, abstractions that wait for proof of repetition before they're built. The clever stuff that won design review in 2018 — generic table components, dynamic dispatch via configuration, runtime type assembly — costs more now than it pays.
This is uncomfortable for senior engineers whose identity is partly tied to the cleverness of their abstractions. It is also, in 2026, the right call. The team that ships features and the team that admires its own architecture have always been different teams; the difference has just gotten more expensive.
The "give your code to a stranger" test. If a senior engineer joining your team next month would need a week of pairing to be productive in a given module, an agent will struggle with that module too. The fixes for one are usually the fixes for the other.
Take a file from a personal project. Show it to a coding agent and ask: "If you had to extend this file, what would slow you down? What's confusing or non-obvious?" Read the answer. Most engineers find at least one piece of feedback that lands.
Find a place in your codebase where you have an "agent often does the wrong thing here" pattern. Look at the design: is the file low-locality? Are names obscure? Is there hidden cleverness an agent can't be expected to pattern-match? Try one change — typically renaming or co-locating — and see if subsequent agent runs improve.
Audit your folder structure. Is it organised by layer or by feature? Layer-organised codebases were the dominant pattern of the 2010s; feature-organised is dominant now, partly because agents handle it better. Plan a migration over a quarter, not a sprint. Wins compound; cost stays low if you do it gradually.
Next chapter: Coding — the day-to-day with an agent. The actual pair-programming dance, when to delegate the whole task, when to pull back and steer, and the small habits that separate the engineers who get 2× from agents from those who get 0.5×.
Sign in to join the discussion and post comments.
Sign in