Sign in Subscribe
Software Architecture

The Architecture Harness: Why Software Architecture Has to Become Executable in the Agentic Era

In this blog post, I want to show you where software architecture stands in the agentic era, why architecture erosion now happens at machine speed and how the Architecture Harness helps you keep your architecture alive.

The Architecture Harness: Why Software Architecture Has to Become Executable in the Agentic Era

Table of Contents

Motivation

In the past months, I've been asked the same questions again and again by CTOs, tech leads and software architects:

  • Do we still need software architecture if Claude writes the whole software system?
  • Is the software architect role obsolete now?
  • Why should we still write ADRs? The agent can just read the code.
  • Do we still need module boundaries if we can regenerate everything in a few days?
  • Who reviews 40 pull requests a day - and what do they actually review?

A lot of questions. And honestly, I asked myself some of them too 😄.

But wait... are these even the right questions?

Recently, I worked with a team that tripled its output within twelve months. Three times more pull requests. Every pull request reviewed. Every pipeline green.

Then we ran a dependency analysis on the codebase 👇

  • The billing module was reading directly from the customer database.
  • The domain layer imported HTTP clients.
  • Two bounded contexts had quietly merged into one.

The module boundaries still existed. In Confluence.

Nobody broke the architecture on purpose. Not the developers. Not the agents. The agents simply never read it.

In my role as tech lead and software architect, I've seen this pattern in several organisations now. And it's always the same trap: Teams invest heavily in agentic AI tooling, but the software architecture stays where it always was - in documents written for humans.

That's why I believe the question isn't whether we still need software architecture. The question is what form software architecture has to take when agents write the code.

The state of software architecture in the agentic era

Architecture erosion isn't new. Every codebase drifts away from its intended architecture over time.

But erosion always had a natural brake: humans are slow. A shortcut through the layers took a developer an afternoon. And usually someone noticed it in the code review.

With agentic AI, this brake is gone. Let's break down why 👇

Agents optimise locally: The shortest path wins

The job of an agent is to close the ticket. And the shortest path to a green test often runs straight through your layers.

This is not malicious. It's efficient. If the agent doesn't know your module boundaries, a direct database call is simply the most reasonable solution.

Research confirms this. In their paper Architecture Without Architects: How AI Coding Agents Shape Software Architecture, Konrad et al. call it vibe architecting: agents make architectural decisions like choosing frameworks or wiring integrations within seconds - mostly without any human review. In their case study, changing only the wording of the prompt led to structurally different systems.

Output scales, review doesn't: Structure is the first thing to go

When reviewers face three times the pull requests, they check whether the code works. Not whether it fits into the architecture.

In my experience, structural feedback is the first thing that drops out of a code review under load.

Every violation becomes a template: Erosion compounds

Agents learn from the code in front of them. One shortcut that slips through becomes the example the next agent copies.

Erosion used to grow linearly. Now it compounds.

Erosion used to happen at human speed. Now it happens at machine speed.

And the bill doesn't arrive in the next sprint. It arrives in year two - when every change touches five modules instead of one. The cost of change goes up. Exactly the thing agents were supposed to make cheap.

Documented architecture vs. enforced architecture

Most of the architecture work I see in organisations is built for human readers: diagrams in a wiki, architecture principles in a slide deck and an architecture board that meets every two weeks.

Don't get me wrong - I love good software architecture documentation. But all of these techniques rest on two assumptions:

  1. The people building the system read the architecture.
  2. There is enough time to check whether they followed it.

With agents, both assumptions break:

  • The wiki is invisible. An agent works with what's in its context: the code, the ticket, the files it opens and its instructions. Your Confluence page isn't in there.
  • The diagram is outdated by Friday. At agent speed, a hand-drawn diagram describes a system that no longer exists.
  • The architecture board becomes a bottleneck. Or it gets skipped. Usually it gets skipped.
Documented architecture is a suggestion. Enforced architecture is a constraint.

And here's the good news: Agents respect constraints. A failing architecture test stops an agent exactly like a failing unit test. It reads the error message - and fixes the code.

Agents can be more disciplined than humans. If you give them something to be disciplined about 😉.

Does Conway's Law still exist?

Whenever I discuss this topic with software architects, someone asks: Does Conway's Law still hold when one person with ten agents builds the whole system?

My short answer: Yes - more than ever. But the organisation looks different.

Conway never said that teams determine the architecture. He said that systems mirror the communication structures of the organisations that design them. And these communication structures are changing fast.

Less communication: Fewer boundaries

When one person builds an entire system with agents, nobody has to negotiate an interface with anybody. No team boundary turns into a module boundary.

The result is often a system without inner boundaries. One communicator, one big ball of mud. That's Conway in its purest form.

Remember the eleven realities? Five people celebrated that they don't have to talk to a colleague anymore. Conway would say: your architecture will notice.

Agents are new members: The context becomes the boundary

An agent communicates through its context: the prompt, the instruction files, the skills and the files it reads. What isn't in its context doesn't exist for the agent.

The context boundary becomes the communication boundary. And with that, the system boundary.

The harness is the new org chart: Inverse Conway for agents

The Inverse Conway Maneuver used to mean: shape your teams the way you want your architecture to look.

Now it also means: shape the contexts and constraints of your agents the way you want your architecture to look.

To be fair, Conway gets a little weaker. When code is cheap, a boundary is cheaper to rebuild. But the expensive boundaries - data, contracts, ownership and on-call - are still organisational.

Whoever designs the contexts of your agents designs your architecture. Deliberately or by accident.

What is the Architecture Harness?

The Architecture Harness is an approach to make your software architecture readable, executable and continuously verifiable for humans and agents.

With the Architecture Harness, I mean the environment your agents work in: what they see, what they're allowed to do and what tells them they're wrong. In the agentic era, software architecture work becomes the design of exactly this environment.

With the Architecture Harness you can:

  • Give your agents the architectural context they need to make the right local decisions
  • Turn your most important architecture rules into fast, automated feedback
  • Design your system so that agents can change it safely
  • Detect architecture drift continuously instead of in the next audit
  • Keep the important architecture decisions where they belong - with humans

The idea of the Architecture Harness

The idea isn't new. Fitness functions from evolutionary architecture, architecture tests, ADRs and the C4 model have been around for years.

What's new is that these techniques move from nice-to-have to the foundation of your software architecture work. Because they're the only parts of your architecture an agent can actually see and feel.

And the term harness isn't mine either 😄. In February 2026, OpenAI described how one of its teams built a product with around a million lines of code, written by Codex agents (summary on InfoQ). A key part of their harness: a strict layering (Types, Config, Repo, Service, Runtime, UI) that is enforced by structural tests.

Shortly after, Birgitta Böckeler picked up the topic in Harness Engineering - first thoughts on martinfowler.com. She describes the harness as the guides and sensors that keep coding agents in check - and admits that she is still missing concrete examples of how architectural constraints work in practice.

That's exactly the gap I want to close: the Architecture Harness is harness engineering from the perspective of the software architect.

The Architecture Harness explained

Let's go through each layer of the Architecture Harness and discuss its purpose.

Context: Make your architecture readable for agents

In this layer, you put your architecture decisions, principles, module boundaries and domain glossary where agents actually look: instruction files like CLAUDE.md or AGENTS.md, agent skills and a short architecture summary in the repository.

Not your full arc42 documentation. A dense extract - think of the Software Architecture Canvas for your agents.

Interestingly, this is where most teams stop. Galster et al. analysed 2,853 GitHub repositories in their study Harness Engineering for Agentic AI Coding Tools: context files are by far the most common way to configure coding agents - often the only one - and AGENTS.md is becoming the cross-tool standard. More advanced mechanisms like skills and subagents are rarely used.

If an architecture decision isn't in the repository, it doesn't exist for your agents.

Constraints: Make your architecture executable

Here you turn your most important architecture rules into architecture tests and fitness functions, for example with ArchUnit, dependency-cruiser, import linters or module boundary checks.

And you run them where the agent works: in its loop, as a hook after every change. Not only in the CI pipeline two hours later.

Every important rule in the context layer deserves a test in the constraints layer. Fast feedback is what makes an agent correct itself.

Neal Ford and Mark Richards, the authors of Building Evolutionary Architectures, take this one step further in How Agentic AI Empowers Architecture Governance. Classic fitness functions often break because they depend on implementation details. Their idea: use MCP and agents as an intermediary layer, so architects define the governance goals and the teams handle the specifics.

Sonar argues in a similar direction in How to keep your architecture intact when agents write the code: combine fitness functions with commit checkpoints and an independent verification layer around the agents.

Structure: Design for the context window

The context window is the new cognitive load. A module an agent can hold completely in its context is a module it can change safely.

This is why clear bounded contexts, modular monoliths with enforced boundaries and small, explicit interfaces become even more important.

Modularity matters more in the agentic era, not less.

Feedback: Make drift visible

Even with constraints, drift happens. So generate the actual architecture from the code on a regular basis - for example as a C4 model with Structurizr DSL - and compare it with the intended architecture.

Drift should be a metric. Not a surprise.

Decisions: Keep the judgement human

Which quality goal wins a trade-off? Which boundaries really matter? Which technical debt do you accept on purpose? These decisions stay with humans.

But every decision flows back into the harness: as an ADR into the context layer and as a test into the constraints layer. That's what closes the loop.

The Architecture Harness in action (an example)

Let's look at the following example 👇

Editor's note: This is an illustrative example. Replace or adapt it with a case from your own projects.

A product team builds a SaaS platform as a modular monolith in Java with three modules: Customer, Contract and Billing. The team uses coding agents for most of the implementation work. After a few months, the billing module started to read customer data directly from the customer database.

Decisions

The team decided that modules only communicate through their public APIs and that each module owns its data. The main quality goal behind it: maintainability, so that each module can evolve independently.

Context

The decision was captured as an ADR in the repository. A short architecture summary in the CLAUDE.md lists the three modules, their responsibilities and the rule: no module accesses the data of another module.

Constraints

An ArchUnit test checks that no class outside the customer module accesses the customer repository. The test runs as a hook after every change of the agent - not only in the CI pipeline.

Structure

Each module is small enough that an agent can hold its code and its public API completely in its context. The public APIs are explicit and documented in the module itself.

Feedback

Once a month, the team generates a C4 component view from the code and compares it with the intended model. New dependencies between modules show up as a diff - and become input for the next decision.

Outcome

  • The good: architecture violations are caught within seconds, and the agent fixes them itself.
  • The bad: the team had to invest time in writing tests for architecture rules that used to be "common sense".
  • What's open: who owns the harness when more teams work on the platform.

What this means for software architects

The role of the software architect is shifting. From drawing boxes to building guardrails.

Before

In the agentic era

Main output

Diagrams and documents

Context, tests and boundaries in the repository

Audience

Humans

Humans and agents

How rules are enforced

Reviews and architecture boards

Architecture tests in the agent loop

How drift is found

Occasional audits

Continuously: actual model vs. intended model

What stays the same

The hype says everything changes. In my experience, it doesn't:

  • Trade-offs: There is still no best architecture - only the least bad one for your quality goals. And agents don't know your quality goals unless you tell them.
  • Quality goals: Security, availability, performance and maintainability still drive your architecture. An agent will happily optimise for whatever is easiest to measure: a green test.
  • Domain knowledge: Good boundaries come from understanding the domain, not from the code. That's why domain knowledge now matters most.
  • Socio-technical thinking: Conway still applies. The organisation just got new members.

Ionut Balosin comes to a similar conclusion in Software Architecture in the AI Era: What Doesn't Change, What Does: understanding the problem, weighing trade-offs and making decisions remain human work - even if AI speeds up creating the artifacts.

The Architecture Harness doesn't replace architectural thinking. It makes architectural thinking enforceable.

The uncomfortable part

Reviewing agent output for structure - not just for function - is a senior skill. Every software architect I know learned it by being a junior for a few years.

If we cut the junior roles today, we cut the pipeline for exactly the people who will design these harnesses tomorrow.

How to get started

You don't need a big transformation programme to build your Architecture Harness. Start small 👇

  1. Pick your top three rules: Choose the three architecture rules that hurt most when they're broken.
  2. Write them down where agents read: Capture each rule as an ADR in the repository and reference it in your agent instructions.
  3. Make them executable: Add an architecture test for each rule.
  4. Run them in the agent loop: Execute the tests as a hook after every change - not only in CI.
  5. Measure drift: Generate your architecture from the code once a month and compare it with the intended architecture.

Final Thoughts

Your agents will never read your architecture documentation. So stop writing your software architecture only for humans.

The Architecture Harness is more than just a set of architecture tests - it's a shift in how we think about software architecture work. Away from documents that describe the system, towards an environment that shapes it.

Architecture erosion at machine speed is real. But so is the opportunity: for the first time, we can enforce our architecture at the same speed as the code is written.

Make your architecture the harness your agents work in.

Further reading

If you want to go deeper, here are the sources I referred to in this post 👇

Contact

If you have any questions or feedback about the Architecture Harness, please contact me. I'm curious how you keep your architecture alive in the agentic era.

Do you want to build an Architecture Harness for your teams? Let's work together 🛠️.

Read next

Comments ()