Most enterprise architecture ends up in one of two places: a slide deck that gets presented once, or a Confluence page that nobody can find when they need it. The knowledge exists. It just does not reach the people making decisions at the point they make them.
That has always been a problem. It is about to become a much more visible one.
“Architecture as code” keeps stalling because it codifies the wrong layer.
“Architecture as code” sounds like the right idea. Express architecture in forms that can be versioned, validated, and enforced programmatically. The Infrastructure as Code movement transformed operations by doing exactly this. Why not apply the same thinking to architecture?
In practice, the parts that get codified tend to be the easy parts: naming conventions, security scanning rules, deployment guardrails. The hard parts, domain boundaries, integration strategy, data ownership, capability decomposition, trade-off guidance, remain in slide decks, wiki pages, and people’s heads.
The metaphor borrows from IaC, but the analogy breaks in a specific place. Infrastructure is deterministic and verifiable. You declare desired state, apply it, and the system either matches or it does not. The feedback loop is tight and binary.
Architecture does not work that way. It spans business capability, data, integration, security, and deployment simultaneously, and it is interpretive: two competent architects can apply the same principle and reach different valid designs depending on context. The right answer depends on the domain, the team’s maturity, the regulatory environment, and the existing estate.
Judgment does not compile.
When organisations try to force all architectural knowledge into executable form, they get one of two outcomes. Rigid rules that do not account for context, which teams route around because the rules do not fit their situation. Or an executable layer that covers only trivial checks, while everything that matters stays in documents that rarely reach people at the point of decision.
There is a third problem underneath both of these, and it may be the more damaging one. Architecture declares a strategic direction, but the platform capabilities to support it are not yet available. A technology gets named as strategic, but six months pass before it is curated, integrated, and actually usable by delivery teams. In the meantime, teams have work to deliver. They make pragmatic choices with whatever is available today, and those choices accumulate as technical debt.
The debt is real, but it is not caused by teams ignoring architecture. It is caused by a gap between strategic intent and operational readiness. Teams need to know not just “what is strategic” but “what is available now, what is coming, and what to do in the meantime.” Without that, strategic placement becomes a source of debt rather than a way to prevent it.
All three of these patterns reinforce the perception that EA is disconnected from delivery. That is a recognised problem across the industry, and it is one that AI-assisted development is about to make harder to ignore.
Two complementary layers
The core idea here is not new. It draws on the ADR movement (Michael Nygard, Michael Keeling), domain-driven design’s bounded context work (Eric Evans, Vaughn Vernon), and the policy-as-code discipline built on tools like Open Policy Agent and Hashicorp Sentinel. These pieces connect differently when AI-assisted delivery becomes the forcing function.
Architecture operates in two complementary layers.
The first is architecture as context. This is the consumable, navigable, decision-supporting body of architectural knowledge. Decision records that explain why, not just what. Domain boundaries with explicit ownership. Business capability maps linked to solution domains, so teams can navigate from business intent to the right architectural starting point. Principles expressed as trade-off guidance rather than commandments. Intent routing: if you are building capability X in domain Y, here is the entry point, the patterns, the owners, the constraints, the prior decisions.
The key property is that context does not need to be executable. It needs to be findable, unambiguous, and current.
The second is architecture as code. This is the subset that can be deterministic and automated: API contract validation in CI/CD pipelines, data classification checks enforced at ingestion, pattern compliance for approved templates, cost governance rules evaluated before deployment, schema validation against published data contracts. These are guardrails. They are valuable precisely because they are automated and non-negotiable. But they are derived from the context layer, not a replacement for it.
A CI/CD check can tell you that a service violates a naming convention. It cannot tell you that the service belongs in the wrong domain, solves the wrong problem, or duplicates capability that already exists elsewhere. That requires context.
Context shapes what gets built. Code validates what gets shipped. Both are necessary.
Why this matters now
AI agents need context to be useful. A model generating a new service has no inherent knowledge of your domain model, integration patterns, data ownership rules, or regulatory constraints. Without context, it will produce code that works in isolation but does not fit the wider system. At enterprise scale, “does not fit” compounds into structural debt that takes years to unwind.
Product and engineering teams can prototype in hours. EA guidance arrives in weeks. The organisation draws its own conclusions about relevance, and those conclusions stick. If architecture depends on tribal knowledge and meeting memory, AI tools will not wait for it. They will generate without it, and the results will be harder to correct after the fact.
Some organisations respond to the pace pressure by doubling down on automated checks: more gates, more scanners, more policy-as-code. Necessary, but not sufficient. Teams pass the checks but the overall system drifts because the intent layer is not being actively shaped. Enforcement alone does not make architecture.
What this means practically
Make architecture navigable, not just publishable. The test is not “does this architecture document exist?” The test is “can a developer or an AI agent, starting from a business requirement, navigate to the right architectural guidance in under five minutes?” Entry points organised by business capability and domain, not by EA team structure. Decision records that are linked, searchable, and current. Explicit “start here” paths for common scenarios.
Separate what requires judgment from what can be automated. Not everything needs to be code. Not everything should stay as prose. The discipline is drawing the line clearly. Naming conventions, security scanning, schema validation, cost threshold alerts, deployment policy checks: automate these. Domain boundary placement, integration strategy selection, data ownership decisions, build versus buy trade-offs, capability decomposition, migration sequencing: these require judgment, context, and human review. Trying to automate the judgment column produces brittle rules. Leaving the automation column as guidance produces inconsistency.
Make context consumable by AI agents. This is the near-term forcing function. Architecture decision records in version-controlled, structured formats. Domain models expressed in forms that fit an agent’s context window. Pattern libraries with clear applicability criteria, not just reference diagrams. Principle documentation that includes decision logic, not just the conclusion.
Treat the context layer as a product. Stale context is worse than no context because it creates false confidence. Explicit ownership per domain. Currency indicators: when was this last validated? Readiness state alongside strategic direction, because the delivery lag problem means teams need to know what to do while they wait, not just where the organisation is headed. Feedback loops from delivery teams. Regular pruning of outdated content.
The harder question is what it takes to make this work at organisational scale, where the context is distributed across dozens of teams and hundreds of services, and the knowledge is held by people who do not always have time to write it down.
That is the real challenge, and “architecture as code” does not solve it. Architecture as context might.