Your coding agent copies your worst code
Coding agents copy the architecture they see. Learn which architectural facts to write down, as quality attributes, boundaries and ADRs, and how to test the effect.
Software architecture · Software foundry · Architecture documentation

The diff that looked fine
This is a concrete diff from one of my example projects. The coding agent has added a feature, the tests pass, the type check is clean, the review looked fine. But the new code in the billing module imports the data store from the orders module and reads the orders directly from the data store of the other module.
Was the code bad? No, it was correct, it was readable and it was tested. Just nobody had told the agent that this call is forbidden.
This happened in a customer project more than once, and when I gave the same task to 5 fresh agent sessions, it happened 5 times out of 5 as well. I'll show you what actually stopped it.
After this Episode you can look at an agent's bad output and ask which architectural fact was actually missing. You can then write that fact down where the agent reads it. You will see a small, concrete setup and a way to test whether it works: the same task, the same model, the same prompt, run several times, before and after.
Agents copy what they see
Here's what surprised me. On the clean version of my example, the agent did not make that mistake. Five sessions out of five kept billing out of orders' data without being told. Clean code actually carries its architecture, and the agent reads it.
So I changed one thing. I made the code base look like a real one after a few years, where somebody has already taken a shortcut. They imported the orders datastore directly here in the users module to read the user's order count. The order count is read down here directly by access to the orders datastore. And nobody told them that this was a mistake, and it wasn't written down anywhere either.
These are the diffs from the agents that worked on the code. On that eroded code, every session copied the shortcut. Three of them even wrapped it nicely: a port in billing plus an adapter in billing that imports orders. That looks like ports and adapters, but the dependency points the wrong way. Tests were green every time.
Most bad agent output is a correct local solution. The agent follows the precedent it finds in the code, and only the team knows that the precedent is wrong.
The agent sees the files it opens, not your history. Quality attributes, context boundaries and rejected options live in the heads, in wikis nobody opens, and in old meetings.
One example: an agent breaks the boundary, we correct it in the review, the next session it breaks it again. Corrections in chat vanish with the session. Only what is in the repo persists.
You might say now: "A better model will infer the architecture in the future." On clean code, it already does, but it can only infer what the code shows. Once the code contradicts your intent, the agent can't tell the rule from the exception, and it doesn't know why billing must not read data from orders.
What to write down
Three kinds of knowledge change agent output most: quality attributes, context boundaries, and decisions with their reasons.
You should have quality attributes as testable statements. Not only "our system must be really fast and scalable", but "300 milliseconds for checkout in 95% of the cases, under normal load". Billing can be deployed without orders. These guide the agent. "Scalable" alone does not.
Bounded contexts: name them, list who may talk to whom, and say how, like events or APIs, never the other module's datastore. One paragraph and one small diagram in text form.
And ADRs: context, decision, consequences, and especially the rejected alternatives. The agent otherwise proposes the rejected alternative again, confidently. And in an eroded codebase, the rejected alternative is often right there in the code, waiting to be copied.
Example: the ADR for my sample. Billing reads order data only through a port of its own. I'm using the Y-statement format, which is a six-part sentence. It reads like this. In the context of issuing invoices for orders, facing the concerns that we face, separate releases of billing and orders is one, and separate data ownership is the other one. What did we decide? We decided for a port in billing that the composition root fills from the Orders module's public API, and we neglected other options like billing importing the orders store and an adapter inside billing that imports orders. We're trying to achieve that billing can be deployed without orders, accepting one more function to wire.
You might say: "That's a lot to write." Right, so here's a tip for you to save some time. Start with the one decision your agent has already broken. Write the ADR from the review comment you gave. Then do the same next time your agent doesn't do what you want.
Put it where the agent reads
Knowledge only helps if it's in the agent's context at the right time, and if it's short enough to be used.
In my example it actually took very little. A short CLAUDE.md file that says: each module owns its data, a module imports only its own files, when it needs something from another module it declares a port, and the composition root, src/app.ts, fills the ports. Plus that empty composition root, so there is an obvious place for the wiring.
In a real system, CLAUDE.md grows to hold the system purpose, the three top quality attributes, the context map, and rules like "before changing anything across modules, read docs/adr/", and an index of ADRs with one-line summaries. This index matters. The agent opens the ADR relevant to the task instead of loading everything. So keep ADR titles as claims, like "A bounded context never reads data from other bounded contexts".
Before: billing reads the orders store. After: billing declares a port, orders publishes the read method, and src/app.ts connects the two. In all five sessions.
To be fair, that's one model, one feature, five runs each. Your agent and your codebase may of course behave differently, so measure it on your own code. Run the same task a few times before and after and compare the diffs.
Enforce it, keep it alive
Documentation the agent reads is the first layer. Checks that fail the build are the second. The agent makes keeping docs current cheap.
Turn the most important rules into fitness functions: an architecture test like, for example, ArchUnit, import-linter or equivalent, that fails on every import across a module boundary. Legacy violations, if they exist, go on a list that only shrinks.
Here's what surprised me again. In my runs, the test never went red. The agents read it before their first edit and followed it. Even without CLAUDE.md, the test and the empty composition root kept all five sessions inside their boundaries. So the test is documentation too, and one that cannot go stale, fortunately, without the build telling you.
Will this test catch an agent that ignores everything? My runs couldn't show that, because no agent did. That's exactly why it's here. It costs nothing while the agent behaves, and it stops the merge when it doesn't. It also makes a good judge. Run it after any agent session, and every red line names a new import that crosses the boundary.
You might think: "That's just documentation, we never kept it up to date before." Well, there's one thing that has changed when we introduce coding agents. Before, documentation had no reader who acted on it daily. Now they have one. A stale ADR visibly produces wrong code within days, so staleness gets noticed.
Make the agent part of upkeep. When a change contradicts an ADR, the agent must either follow it or propose a new ADR in the same pull request. A human reviews that decision, not the prose.
So, keep it small. Ten accurate ADRs are way better than a hundred unread ones. Of course, all this doesn't replace proper reviews, and even an ADR can be wrong. But at least it makes the disagreement visible.
Close and try it yourself
Remember: your agent copies the architecture it sees. If your code no longer shows it, write it down where the agent reads it.
So check this out. Take the last three review comments where you told an agent or a colleague, "we don't do it that way here". Write each as a short ADR or a quality-attribute line, link them from CLAUDE.md, and rerun one of the same tasks. Compare the diffs. Optionally, add one architecture test for the rule that mattered most.
Want to try this in practice? Use the link to Architecture Practice Lab in the description of this video. You get the eroded example repo from this Episode. Give it the same task with your own agent, Claude or another, and see whether it keeps the boundaries. Then write down the architecture, try again, and get feedback from my reviewer agent that I trained on rules for good architecture.
See you soon!