Can Clean Architecture Help AI Coding Agents Write Better Code? A Real-World Test

A Neglected Question: Does Architecture Affect AI Coding Efficiency?

When AI coding agents take over software development, we tend to assume that good software architecture still matters. But does that assumption hold? A developer shared a hands-on controlled experiment on Reddit, attempting to answer exactly this question: when the one writing code is an Agent rather than a human, is Clean Architecture a help or a hindrance?

The experimental design was deliberately restrained. The author built two versions of the same Java sample application. One used Hexagonal Architecture, complete with ports, adapters, and architecture tests. The other had no architectural guidelines or rules whatsoever — a "flat version." Both versions had to pass the same suite of external test cases to verify correct behavior. The test environment consistently used a locally deployed Qwen model running through OpenCode, with one task executed at a time.

Hexagonal Architecture was introduced by Alistair Cockburn in 2005, also known as the "Ports and Adapters" pattern. Its core idea is to place business logic at the center, interacting with the outside world through abstract "ports" (interfaces), while "adapters" translate concrete external technologies (databases, HTTP, message queues, etc.) into the format defined by those ports. This design means that replacing any external dependency requires no changes to the core logic. "Clean Architecture" is Robert C. Martin's generalized version of a similar philosophy, emphasizing that dependencies should always point toward the inner business rules. These architectural styles are widely praised in traditional human-led development because they reduce cognitive coupling between modules, allowing developers to focus on a single layer at a time. Whether this advantage of "layering to reduce cognitive load" holds equally when an AI Agent is doing the work is precisely what this experiment set out to explore.

What Was Measured and How

The author's measurement dimensions are worth noting. He recorded the time each task took from implementation through testing and bug-fixing until it passed, while also tracking token consumption and tool call counts. Initial project setup time was excluded from the statistics, to avoid unfairly penalizing the architecture version for its more complex scaffolding.

The experiment proceeded in phases. The first phase covered nine functional features, followed by six more challenging tasks completed on separate branches. The author then added fifteen sequential changes, including modifications to earlier requirements — a deliberate simulation of the rework pressure that comes with evolving requirements in real development. By the later stages of the experiment, both projects had grown to roughly 12k and 15k lines of production-level Java code respectively — well beyond toy-project scale.

OpenCode, used in this experiment, is a terminal-based AI coding tool that connects local or remote large language models to a codebase and executes multi-step development tasks. Qwen is Alibaba's open-source large language model series. Local deployment means the experiment ran in an offline, controlled environment, eliminating network latency and cloud-side model version drift — but also means the model's capabilities were constrained by local hardware and may fall short of frontier models like GPT-4o or Claude 3.5 Sonnet. Token consumption (both input and output) is the standard metric for measuring LLM call costs: input tokens represent how much context the model needs to "read," and output tokens represent the content the model generates. More complex architecture means more related files, which typically results in longer input contexts per task — directly reflected in the token count.

A Surprising Result: The Flat Version Was Faster Overall

The core finding is striking: in every round of the experiment, the flat version with no architectural constraints was faster overall.

The Hexagonal Architecture did win on certain individual tasks, but in aggregate it consumed more input and output tokens. In other words, the orderliness that architecture brings did not translate into overall efficiency gains for the Agent. Instead, the need to understand and maintain abstract layers like ports and adapters increased the model's cognitive and generation costs.

This result challenges the intuition that "cleaner architecture means easier AI coding." For human developers, clear boundaries reduce mental load. But for current coding agents, more structural layers may mean longer contexts, more file traversal, and higher token overhead.

Hexagonal Architecture's Moment to Shine: Database Extension

The author then designed a scenario theoretically favorable to the ports-and-adapters pattern: adding PostgreSQL support while keeping SQLite fully functional.

This is precisely the strength Hexagonal Architecture claims — using adapters to isolate external dependencies so that replacing or adding underlying implementations requires no changes to core business logic. The experiment confirmed this: the hexagonal version completed the task in just about 39 minutes, with its core application code remaining unchanged; the flat version took 71 minutes.

But the author honestly added two critical caveats: first, this time saving was not enough to offset the cumulative time gap from the preceding fifteen-feature sequence; second, this was purely backend-level database support work, not a real live migration involving data movement. The architectural benefit was real, but in the experiment's overall ledger, it wasn't enough to turn the tide.

How to Interpret This Experiment Rationally

The author was admirably measured in acknowledging the experiment's limitations — arguably the most commendable aspect of this report. He explicitly noted: this was a single service, a single model, with no repeated trials. It measured the goal of "getting changes to pass tests," not years of maintainability or production reliability.

These constraints are crucial. The core value of software architecture typically manifests in long-term maintenance, team collaboration, and system evolution — not in the speed of a single feature delivery. An experiment running a few dozen tasks with a single model cannot capture the compounding effects of architecture over a multi-year lifecycle. Furthermore, the local Qwen model's performance may not be representative of more capable frontier models — different models may vary significantly in how well they handle abstract structures.

The full report and measurement data have been published on Zenodo (record number 22806994). The author also transparently acknowledges that AI tools assisted in writing the evaluator, orchestration, charts, and manuscript.

The long-term value of software architecture typically manifests through "maintainability compounding": as systems grow in scale, teams turn over, and requirements keep evolving, well-defined boundaries can exponentially reduce the cost of change. The famous "broken windows effect" is especially pronounced in codebases without architectural constraints — early rapid delivery often comes at the cost of technical debt repaid later. Moreover, this experiment measured a single success criterion: "passing tests." The value of architecture in production environments also shows up in code review efficiency, onboarding speed for new team members, ease of fault localization, and traceability for compliance audits — none of which can be quantified in a short-term delivery experiment. Therefore, extrapolating this experiment's conclusions into an "architecture is useless in the AI era" argument requires extreme caution.

Takeaways for Developers

This experiment doesn't deliver a final verdict on "whether to use Clean Architecture," but it offers a valuable counter-intuitive perspective:

• On short-term delivery speed, letting agents work in an unconstrained flat structure may be faster and more token-efficient;
• In specific extensibility scenarios (such as replacing infrastructure), good architectural isolation can still save significant time;
• Architecture's "investment" requires a long enough time horizon and enough changes to pay off — a single experiment has difficulty capturing that return.

For teams exploring AI-assisted development workflows, perhaps the real question isn't "architecture or no architecture," but rather "at what scale and over what time horizon does architecture's benefit outweigh the additional cost it imposes on the Agent?" That question demands more samples, more models, and longer-term validation.