Agent-Native Architecture: Designing Software Systems That AI Can Understand, Operate, and Evolve
Your codebase was designed for humans. Now agents are writing most of it. And they navigate very differently.
If it’s not in the repository, it doesn’t exist to an agent. No colleague to ask, no memory of last month’s architecture discussion, no intuition filling the gaps. Agents follow structure: explicit types, enforced boundaries, discoverable dependencies. Most codebases weren’t built for that.
The advice teams have absorbed (clean code, good tests, use TypeScript) solves only a narrow slice of the problem. It’s necessary. It’s nowhere near sufficient. Agents don’t slow down when code is hard to understand. They replicate whatever patterns they see, good or bad. The throughput that makes agents valuable is also what makes architectural flaws compound faster.
This article proposes a framework for what makes a codebase understandable and maintainable for agents. Three dimensions, grounded in research and production evidence. Today’s choices about module boundaries, observability, and documentation set the ceiling on what agents can do in your system for years.
What “Agent-Native” Means
The term “agent-native” already exists in two forms.
The first means designing products so that AI agents can use them as consumers: API parity, granular tool primitives, composable capabilities. This is a product design question: can an agent call your API?
The second means designing codebases so that AI agents can develop, operate, and evolve them. This is an architecture question: can an agent reliably understand, modify, and maintain your system?
These are related but distinct. This article is about the second definition.
The precedent for this framing is cloud-native architecture. “Cloud-native” described systems designed for the cloud as their execution environment: stateless, containerized, horizontally scalable. The cloud wasn’t an afterthought. It was the design constraint. Agent-native architecture follows the same pattern: the agent is the primary developer, and the architecture is designed around that constraint.
Working definition: agent-native architecture is designed so that agents can reliably understand the system from the repository, validate their own work during execution, and maintain coherence as they generate code at scale.
Three dimensions make this possible. None is optional. Each builds on the one before.
The Inversion
Software architecture has always optimized for human developers: readable, navigable, intuitable.
Agent-native architecture shifts that target. Not “can a developer understand this during onboarding?” but “can an agent understand this from the repository alone?” Agents can run for six hours without fatigue, operate many instances in parallel, and apply rules systematically across an entire codebase at a pace no reviewer could sustain.
OpenAI’s Harness Engineering team built a million-line codebase entirely with AI agents over five months: “The resulting code does not always match human stylistic preferences, and that’s okay. As long as the output is correct, maintainable, and legible to future agent runs, it meets the bar.”
That is a real shift in optimization target. Most teams haven’t made it explicitly.
The Three Dimensions
Structural Legibility
Can an agent understand the system from the repository alone?
In a March 2026 study of real-world codebases with dozens of interdependent modules (arXiv:2603.00601), four frontier models were tested. The finding: models that solve standard coding benchmarks “with ease produce incoherent results when modifying real codebases.” Approximately one-third of architectural dependencies (API calls via dynamic dispatch, registry wiring, runtime injection) are invisible to import-following. Agents navigating by syntax miss a third of what’s actually happening.
Different models respond differently to the same codebases. Some perform better with sequential active exploration. Others perform better with full codebase visibility upfront. One model loses previously-discovered components between queries. Structural legibility is not a binary property, and it is not purely a model problem. Architectures that expose dependencies syntactically (through explicit imports, typed interfaces, and enforced layer boundaries) reduce the cognitive burden on every model, regardless of its exploration strategy.
What structural legibility looks like in practice:
Layered domain architecture with mechanically enforced boundaries. Not documented constraints. Enforced ones. Custom linters that block code from depending on layers it shouldn’t touch. Harness Engineering: “By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation.”
Semantic naming. File paths, types, and schemas that encode intent. When an agent reads a file path, it should be able to infer what that module does without reading the implementation.
Small, focused files. Context windows are finite. A 3,000-line module forces the agent to hold more state than it can reliably manage across a complex task.
Documentation as infrastructure. A short AGENTS.md (roughly 100 lines) navigates agents to deeper specs rather than encoding everything upfront. A February 2026 study of production agent deployments (arXiv:2602.20478) describes the emerging pattern: hot memory always in context, domain specialists routed by file pattern, cold on-demand specs that update when source code changes. Harness Engineering tried the “one big AGENTS.md” approach and abandoned it: “When everything is important, nothing is.”
For agents, the repository is the system. Everything else is invisible.
Technologies with stable APIs and strong representation in model training data are more legible to agents. Harness Engineering found it was sometimes cheaper to have agents reimplement a subset of a library’s functionality than to work around opaque upstream behavior. Boring tech is a legibility choice.
Runtime Observability
Can agents validate their own work while running?
Without runtime signals, agents operate in a narrow loop: they write code, run tests, and work from test output alone. They can tell if the code compiled and if the tests passed. They can’t tell whether the system performed correctly, behaved correctly at the UI layer, or met non-functional requirements.
Harness Engineering addressed this systematically. They made the application bootable per git worktree, so each agent instance operates its own isolated copy. They wired in Chrome DevTools Protocol for UI interaction. They gave agents access to logs via LogQL and metrics via PromQL. The result: prompts like “ensure service startup completes in under 800ms” became tractable, because the agent could measure it directly. Single runs operated for up to six hours on tasks humans weren’t awake to supervise.
Boris Tane, writing in February 2026, describes the architectural principle behind this: “Monitoring moves from passive dashboarding to an active feedback mechanism. Production observations directly inform agent corrections in the next loop iteration.”
The design implication: the application produces structured, queryable signals that agents can use to verify correctness and performance, not just signals for human operators to read on dashboards.
The production-time extension of this principle is agent-managed canary deployments. The pattern: an agent deploys a change to a small percentage of traffic, reads error rates and latency metrics scoped to its own deployment, and decides whether to expand or roll back.
The individual pieces of this pattern exist and are in use. AI-assisted rollout progression and autonomous rollback are available in production tooling today (LaunchDarkly, Statsig, Harness). Per-worktree isolated environments work in development. In production deployments, teams report 68% reductions in deployment incidents and 85% faster incident detection.
The full end-to-end loop (a single agent writing code, deploying its own canary, reading production signals scoped to its deployment, and deciding to ship or roll back) is still an emerging pattern rather than standard practice. The architecture determines whether it becomes achievable. Teams that design observability in as a first-class concern will be able to close that loop as tooling matures. Teams that treat observability as an ops add-on will need to retrofit it against a codebase that wasn’t built for it.
For the pattern to work, the architecture must provide four things: feature flags as structured, queryable artifacts; observability signals agents can read directly; automated rollback triggers defined as code rather than manual gates; and isolated environments per agent worktree, so one agent’s deployment signals don’t contaminate another’s.
The evaluation question: can an agent query the system’s own behavior, or only its test results?
Evolutionary Coherence
Can the system resist drift as agents generate code at scale?
Agents replicate patterns. That’s the mechanism behind their productivity: they observe existing code and extend it consistently. When the existing patterns are good, this is leverage. When they are bad, this is compounding.
Harness Engineering discovered this directly. Before automating the problem away, they spent every Friday, 20% of the engineering week, cleaning up what they called “AI slop.” Unsophisticated patterns and inconsistencies that agents had propagated throughout the codebase, each one individually small, collectively significant.
Wes McKinney, writing in February 2026, describes the same dynamic from a different angle. He calls it the “agentic tar pit”: parallel AI sessions generate code faster than humans can evaluate it, and agents can’t reliably distinguish essential complexity from accidental complexity.
Documentation and style guides don’t solve this. Agents read them, but they also read everything else in the codebase. When documented style conflicts with visible patterns in the code, agents often follow the code.
Evolutionary coherence requires mechanical enforcement:
Custom linters with remediation in error messages. Not just failure flags: instructions. When an agent violates an invariant, the error message tells it how to fix the violation. Harness Engineering found that “once encoded, they apply everywhere at once.”
Automated recurring cleanup tasks. A background agent that scans for deviations from established principles, updates quality grades per domain, and opens targeted refactoring pull requests. Harness Engineering runs these daily; most take under a minute to review and automerge.
Visible debt surface area. Quality grading per domain, tracked over time. The alternative is invisible accumulation.
The tradeoff is real: mechanical enforcement creates rigidity. In a human-first workflow, pedantic rules feel constraining. In an agent-first workflow, they are the enforcement mechanism. Agent-native architecture trades some human flexibility for agent reliability. That’s a design choice, not a side effect.
Three properties, each addressing a distinct failure mode. Structural legibility: can agents understand the system? Runtime observability: can agents verify their work? Evolutionary coherence: will quality hold as agents generate code at scale? A codebase strong in all three gives agents reliable leverage. Weak in any one, and you get a specific kind of failure.
Getting There
For teams starting from scratch, the path is clear: design all three dimensions in from the beginning. Harness Engineering credits early architectural investment as the reason throughput increased as the team grew, rather than degrading. “This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it’s an early prerequisite.”
For teams working with existing codebases, the answer is harder.
McKinney identifies what he calls the “brownfield barrier”: large codebases, regardless of structural quality, significantly slow agent productivity. The invisible dependency problem worsens as module count grows. Existing patterns are already embedded and will be replicated.
Agent-native properties can be adopted incrementally, but the return on investment order matters.
Structural legibility has the highest immediate impact and the most incremental path. Start with AGENTS.md as a navigation map. Enforce existing layer boundaries mechanically. Improve naming in the modules agents touch most. These changes benefit every agent run immediately.
Evolutionary coherence can be introduced at any point. Linters and cleanup tasks don’t require architectural changes. They layer on top of an existing codebase.
Runtime observability is the most infrastructure-dependent. If you have structured logging and accessible metrics, agents can use them. If your observability stack was designed for human dashboards only, the rework is significant.
One honest constraint: Harness Engineering describes their experience at the five-month mark. No published evidence exists for what agent-native codebases look like at two or three years. The framework is grounded in production evidence; the long-term properties are still being learned.
Start this quarter:
- Write AGENTS.md as a navigation map: under 100 lines, pointing agents to the right modules and deeper specs. This is the highest-leverage single change for most codebases.
- Identify one layer boundary agents could cross undetected and add a linter to enforce it. Mechanical enforcement compounds.
- Pick one runtime metric (startup time, error rate, response latency) and make it queryable directly by an agent, not just visible on a dashboard.
What Changes for Engineering Leaders
When agents are the primary developer, the human contribution shifts. Not away from engineering. Toward a different layer of it.
Design judgment, scope discipline, and architectural coherence vision matter more, not less. McKinney: “Knowing what to build, when to say no, and maintaining coherent design vision matter more than ever, exactly as Brooks predicted.” The agent generates code fast. The human decides what gets built and whether the architecture remains coherent as it scales.
The three-dimension framework also gives leaders a concrete evaluation tool. When reviewing an architectural proposal (a new service, a module boundary decision, an observability investment), the question set becomes explicit:
Does this improve structural legibility? Can an agent understand it from the repo alone?
Does this improve runtime observability? Can an agent validate its own work while running?
Does this improve evolutionary coherence? Will it resist drift as agents generate code at scale?
Consider a team deciding whether to introduce a new service or extend an existing module. Running the three questions makes the tradeoffs explicit before the decision is made.
On structural legibility: a new service boundary clarifies domain ownership if the split is genuinely distinct. If the boundary is artificial, the new service adds an indirect dependency that import-following won’t surface. Agents navigating the codebase will miss it.
On runtime observability: a new service needs its own instrumentation. If that instrumentation isn’t wired before agents start writing against it, they’ll validate their work only against unit tests. Behavioral correctness and performance constraints become invisible.
On evolutionary coherence: a new service boundary is only enforceable if enforcement is mechanical. A documented boundary that agents can cross without a linter catching it will be crossed. The documentation and the codebase will drift.
The questions don’t produce automatic answers. They surface the right tradeoffs. An experienced engineer reviewing this proposal probably has intuitions about all three, but without the vocabulary to name them, the review stays implicit. Implicit design decisions compound the same way implicit architectural debt does.
Making the answers explicit, before the decision is made, is the form of design review agent-native organizations need.
The Architecture You Choose Today
Software architecture has always reflected its primary builder. Mainframe constraints produced batch architectures. The need to scale teams independently produced microservices. Each shift in primary builder produced a corresponding shift in design thinking.
Agents are the next shift. And they don’t adapt to the architecture they inherit. They scale it.
Agent-native architecture gives you leverage instead of drift: systems agents can understand, systems they can verify, systems that stay coherent as they grow. These properties compound over time. They don’t have to be perfect at once.
For most existing codebases, the honest answer is partial at best on all three. Pick one dimension. Improve it this quarter.
Agents will scale whatever you give them.