Architecture is for Agents
The architectural boundaries that once made a codebase legible to a new hire now make it tractable to an agent.
The architectural boundaries that used to make a codebase legible to a new hire now make it tractable to an agent. The contracts that used to protect teams from each other now protect agents from themselves. The same patterns we used to enforce for organizational reasons, such as modularity, typed interfaces, observable side effects, turn out to be the patterns agents need to operate safely.
That changes what architecture is for. The boundaries we drew so a new hire could find their way around turn out to be the same boundaries that keep an agent from getting lost. The contracts we wrote so teams wouldn’t step on each other keep agents from stepping on themselves. We didn’t build architecture for agents. They need it more than we ever did.
What an Agent Sees
Open a codebase and try to make a small change. As a human, you have a strategy you don’t even notice. You read function names and trust them. You skim a module and intuit its shape. You see a long file and decide whether to scroll or grep. You hold a mental model of “the part that probably handles this” and navigate toward it. When the code surprises you, you adjust. When the code lies to you (e.g., a function named validate that also writes to the database) you remember, and you compensate.
An agent has none of this.
An agent reads what’s in front of it. It follows the call graph it can see. It infers behavior from names, signatures, and comments. When the code lies, the agent believes it. When the boundary between two systems is implicit—encoded in a Slack thread from 2022—the agent doesn’t know to look. When a function’s real job is hidden behind three layers of indirection, the agent will modify the wrong layer.
The agent isn’t broken. The codebase has been keeping these secrets for years — the agent is just the first reader naive enough to believe it.
Architecture is the act of making a codebase communicate. The better it communicates, the more capable the agent operating on it.
Codebases That Punish Agents
Some codebases are hostile to agents. They share specific properties, and once you start looking, you see them everywhere.
Implicit state. Globals, singletons, module-level caches, environment variables that change behavior in non-obvious ways. The agent reads a function and concludes it’s pure. It isn’t. The bug shows up in production.
Long functions with no internal structure. A 600-line method that handles five concerns. The agent makes a local change. It also breaks an unrelated path it never realized it was touching.
Names that lie.
getUserthat also creates one.processthat does seven different things depending on a flag.utils.pycontaining nothing but business logic. The agent trusts the name and gets it wrong.No clear boundaries. Code that crosses freely between domains, layers, and concerns. The agent can’t tell where one system ends and the next begins, so it makes changes that ripple unpredictably.
Implicit contracts. Two services that share data, but the shape of that data exists nowhere except in the code that produces and consumes it. A schema change breaks something three repos away.
You can survive these in a human team. You compensate with experience. You assign the change to the person who remembers. You catch the breakage in review because someone happens to have context. The codebase punishes you, but slowly, in ways spread across many people and many quarters.
Hand the same codebase to an agent and the punishment compounds in a single afternoon.
What Agent-Friendly Looks Like
The architectural patterns that help agents aren’t new. They’re the patterns engineers have always recommended for “clean code,” now upgraded from style preferences to operational requirements.
Small, named units. Functions and modules that do one thing and announce it. The agent reads the name, reads the signature, and forms an accurate model of what’s inside.
Typed contracts at every boundary. Not just inside the language—across services, across modules, across teams. The agent can reason about what it’s allowed to send and what it can expect back.
Explicit side effects. Pure functions where possible. Where impure, the impurity is named and contained. The agent knows where the danger is, because the code says so.
Clear ownership. Each piece of behavior lives in one place. The agent doesn’t have to choose between three candidate sites for a change.
Observability as a first-class concern. Logs, traces, and metrics that explain what the system did, not just what it was supposed to do. The agent can verify its own changes by reading the system’s behavior.
Documentation that’s actually true. Not aspirational diagrams from the kickoff—living documents the agent can read, trust, and use to navigate. If the docs lie, the agent gets lost. If the docs are accurate, the agent can plan.
None of this is exotic. All of it is what we’ve always meant by “well-architected.” The difference is who’s paying the bill if it’s missing.
The Inversion
Here’s the move. We used to think architecture was downstream of engineering quality. Good engineers produced good architecture as a byproduct of caring about the system.
That gets inverted by agents.
Now, architecture is upstream of everything an agent can do. A messy codebase doesn’t just make the agent work slower. It makes agent work unsafe. The agent will produce changes that pass tests, look reasonable in review, and quietly break production. Not because the agent is incompetent, but because the codebase didn’t tell it the truth.
The implication is uncomfortable. If you want agents to be useful—really useful, not demo-useful—you don’t start by adopting an agent. You start by paying down architectural debt you’ve been postponing for years. The agent isn’t a tool you can drop in. It’s a tenant moving in, and your codebase is the building. The shape of the building decides what the tenant can do.
This is why the best agentic teams aren’t the ones with the fanciest models. They’re the ones with the cleanest boundaries, the strictest contracts, the most honest names. Their codebases were already talking to the people who worked on them. Now they talk to agents too, and the conversation continues without breaking.
What’s at Stake
The teams that don’t do this work will hit a wall. They’ll bring agents into codebases that lie, and they’ll watch the agents produce confident, plausible, wrong code. They’ll conclude that agents aren’t ready. They’ll be half right. The agents aren’t ready for them.
The teams that do this work will discover something else. Architecture, the thing they used to argue about in design reviews and skip when shipping mattered, becomes the most leveraged investment they can make. Every hour spent clarifying a boundary returns hours of agent productivity. Every typed contract pays for itself the first time an agent stays inside it.
The agent doesn’t change what good architecture is. It changes who notices when it’s missing.