Architecture Before Code: Designing Systems AI Can Build Inside

The most common failure of AI-assisted work is not that the output is wrong in isolation. It compiles, it renders, it passes a smoke test. The failure is that it does not fit: it ignores a boundary, duplicates a responsibility, reaches into a module it should not know about. Fixing that after the fact is expensive. Designing it up front is architecture — and it happens before code, whoever writes it.

What "Fit" Means

Fit is decided, not discovered. Before a change is generated, the important questions already have answers:

When those answers exist, a capable drafter — human or AI — produces work that slots in. When they do not, every addition nudges the system toward entropy, and the drift stays silent until it bites.

Who decides, and when

The vague version of this advice is "design first", which is easy to agree with and easy to defer. Concretely: fit is decided by whoever is accountable for the system, at the moment the change is accepted into the plan — and it is recorded in the repository before generation starts.

That timing is the whole point. Decide fit during review and you are choosing between rejecting finished work and accepting a compromise; decide it at the plan and the draft arrives inside the shape. And "recorded" is not a formality: a boundary that lives in a design conversation is not a constraint, it is a recollection — the next contributor, human or machine, will produce something that quietly contradicts it.

Boundaries First

Well-defined boundaries are the highest-leverage structure you can draw:

• Modules with one responsibility, so a change has an obvious home.
• Explicit dependency direction, so layers do not tangle.
• Narrow interfaces, so internal changes stay internal.

AI accelerates whatever shape it finds. Inside clear boundaries it produces more of that clarity. Inside a tangle it produces more tangle — faster than any human could. The fix is not better prompting; it is a better shape to prompt inside.

The trade-off is real and worth naming: every boundary costs indirection. Draw too many and a change that should be one edit becomes five, each with its own ceremony. The skill is not maximising structure; it is choosing the few boundaries that carry weight — the seams where change is expected, or where a mistake is expensive — and leaving the rest alone.

Codify the Map

Architecture that lives in someone's head is not architecture; it is memory. The durable form is a version-controlled map in the repository that records:

• the structure — modules, layers, boundaries, and how they connect;
• the conventions — naming, error handling, configuration, testing;
• the decisions — what was chosen, why, and what it replaced.

A new engineer reads that map to get oriented. An AI session reads the same map for the same reason. Neither of them owns it; the repository does, and every change to it is a reviewed change.

Cheap to State, Expensive to Rediscover

The most valuable conventions are the ones that cost one line to write and weeks to rediscover: where configuration belongs, how a service reports failure, when something may cross a boundary, what naming pattern keeps logs and dashboards searchable.

Codify those, and every draft inherits them for free. Leave them out, and you will spend review cycles explaining them one generated change at a time — teaching the same lesson repeatedly, to a reader who will not remember it next session.

What It Buys You

• Faster, safer regeneration. When callers depend on a contract, an implementation can be rewritten — by a person or a model — without touching the rest of the system.
• Smaller blast radius. A change with an obvious home touches less, so it needs less review and carries less risk.
• Predictable review. A reviewer checks the change against a stated boundary instead of reconstructing the architecture from memory.
• Onboarding that scales. The map answers the questions a new contributor would otherwise ask a colleague — including when the new contributor is an agent.

Architecture Is a Judgement Call

None of this removes the engineer. Choosing boundaries means trading off coupling, reuse, ownership, and cost — and defending the trade-off. Those are judgement calls, and judgement is exactly what the orchestrator keeps. A model can draft options and even analyse trade-offs; deciding which system you are willing to maintain is human work, and it stays human.

The Orchestrator's Takeaway

Decide the boundaries at the plan, not at the review, and write them where both a new engineer and an agent will read them. A boundary that is not written down is not a constraint — it is a memory, and memory is not architecture.

Next in the Series

Structure that is designed still needs to be trusted. Part 3 covers how quality becomes a property of the process: automation and gates that enforce the standards on every change, with no express lane for generated code.

For the full method, see The DevOps Engineer's Guide to Effective AI Usage.