Architecture as Code to Teach Humans and Agents About Architecture
Neal Ford and Mark Richards · rss · 2026-04-15 Reader 🖥️
Software architecture should be defined as code — capturing structural constraints deterministically — so that both human developers and AI agents can receive fast feedback on whether implementations conform to design intent.
practical · argumentative — A short promotional essay for the forthcoming O'Reilly book 'Architecture as Code.' It argues that architects should define architectural constraints in code so that both humans and AI agents can use them as deterministic guardrails.
Structure
| Part | Role |
|---|---|
| Origin story: iterative book development and the industry shift | Context — establishes how the authors' original 'architecture as code' idea (feedback loops for architects) was overtaken by the arrival of agentic AI, giving the concept new urgency. |
| The feedback-framework concept | Core mechanism — explains how defining components, dependencies, and structural constraints in code creates a feedback loop (not a testing framework) that alerts architects when implementations diverge from design. |
| Agentic AI needs deterministic constraints | New motivation — argues that AI agents require the same deterministic architectural constraints to guide code generation toward acceptable solutions, e.g., cyclomatic-complexity limits preventing brute-force solutions. |
| The nine intersections | Scope claim — lists the nine areas (implementation, engineering practices, infrastructure, generative AI, team topologies, business concerns, enterprise architecture, data, integration) where architecture can be expressed as code. |
| Future outlook and book teaser | Call to action — positions defining architecture precisely and objectively as the emerging job of architects and developers, and previews the forthcoming book. |
Key terms
- Architecture as Code Evolutionary Architecture & Fitness Functions
Expressing all aspects of software architecture — structure, constraints, relationships, dependencies — in executable, version-controlled code rather than diagrams or prose, so that conformance can be verified automatically. - feedback framework (vs. testing framework) Evolutionary Architecture & Fitness Functions
A system that notifies architects when implementation diverges from design, framing divergence as information (potential feedback) rather than as failure (test breakage). A new component is not an error — it is a signal to assess. - deterministic constraints Evolutionary Architecture & Fitness Functions
Objective, measurable architectural rules (e.g., cyclomatic complexity limits, dependency direction rules) that can be evaluated computationally without human judgment. - foundational constraints vs. desired behavior Guardrails
A separation in agentic AI between inviolable rules (hard architectural boundaries) and goals the agent works toward. Foundational constraints are non-negotiable; desired behavior is aspirational. - nine intersections Evolutionary Architecture & Fitness Functions
The nine areas where software architecture intersects other parts of the development ecosystem: implementation, engineering practices, infrastructure, generative AI, team topologies, business concerns, enterprise architecture, data, and integration architecture.
Propositions
- explicitdevelopedDefining architecture as code creates a fast feedback loop that lets architects detect when implementation diverges from design.conf: highextends ←Presentation: Clean Architecture for Serverless: Business Logic You Can Take Anywhere · p6 — Gradle module dependency configuration is a stronger, prevention-time version of 'architecture as code': rather than only giving fast feedback when implementation diverges from design, it makes the divergent code physically uncompilable.
- explicitArchitectural divergence is feedback, not failure — a new component appearing is a signal for the architect to assess, not an error to fix.conf: high
- explicitestablishedAI agents can only work toward acceptable solutions when deterministic constraints exist to define success.conf: highsupportsAgents don't know what good looks like. And that's exactly the problem. · p5 — Independently asserts the core guardrails thesis: agents can only reach acceptable solutions when deterministic constraints define success.refines11) AI-spesial med Vilde Opsal og Anders Sveen · p2 — Reconciles the 'chasing LLM determinism is a category error' claim: determinism belongs in the guardrails/constraints that define success, not in the model itself.supports ←Addy Osmani's Post · p5 — Both claim agents can only be trusted to produce acceptable output when deterministic constraints (tests/metrics here, architecture-as-code there) define success, rather than relying on human judgment per instance.supports ←Article: Agentic Fitness Functions: Extending Evolutionary Architecture Beyond Deterministic Rules · p1 — Agrees that agents/AI judges can only be trusted to converge on acceptable outcomes when deterministic constraints bound the space first.supports ←Comprehension at AI Speed: Building a Context Store for Evolutionary Architecture · p6 — Both treat deterministic, executable constraints (fitness functions here, architecture-as-code there) as the mechanism by which architectural intent becomes something AI agents, not only humans, can act on and be judged against.supports ←DoorDash Used Copilot to Convert Its XCTest-Based iOS Test Suite to Swift Testing · p2 — Empirical instance: AI migration became reliable only when strict deterministic reliability gates defined success.
- explicitSeparating foundational constraints from desired behavior is becoming standard practice in agentic AI for code generation.conf: medium
- explicitcorroboratedLLMs tend toward brute-force solutions unless constrained by measurable architectural rules like cyclomatic complexity limits.conf: highsupports ←Coding Models Are Doing Too Much · p1 — Measured over-editing gives empirical backing to the claim that LLMs default to doing more than necessary unless explicitly constrained.
- implicitThe same code-based architectural constraints that serve human developers are directly applicable as guardrails for AI agents.conf: high
- implicitdevelopedArchitecture can be objectively and precisely defined across all nine intersections of the development ecosystem.conf: mediumrefines ←Three more static code analysis sensors · p6 — Bounds the claim that architecture is objectively definable everywhere: structural tools only encode what imports, file names, and folder structure can express.
- implicitArchitects who cannot express their design intent in deterministic, executable form will be unable to guide AI-assisted development.conf: medium
Arguments
Architecture should be defined as code to create feedback loops between architects and developers. strength: medium
Explicit premises:
- Architects design components with careful thought about coupling, cohesion, and structural concerns.
- Once a design is handed to a team, the architect has no way to verify the team implements it correctly.
- Defining components in code with verifications allows architects to both illustrate and get feedback on the design.
- Design should sometimes change to reflect implementation realities.
Implicit premises:
- Diagrams and documents alone are insufficient to maintain architectural integrity over time.
- The gap between design intent and implementation is a significant source of architectural drift.
- Architects are not embedded deeply enough in implementation to catch divergence through code review alone.
Inferences:
- Therefore, architecture-as-code is not just documentation but a living governance mechanism.
- Therefore, the architect's role shifts from upfront designer to continuous feedback processor.
Architecture as Code is essential for effective agentic AI in software development. strength: medium
Explicit premises:
- Agentic AI can work toward a solution as long as deterministic constraints exist.
- LLMs tend toward brute-force solutions without explicit constraints.
- Architectural constraints (complexity limits, coupling rules) can prevent brute-force code generation.
- Separating foundational constraints from desired behavior is an increasingly common agentic AI practice.
Implicit premises:
- AI agents will play a significant and growing role in software implementation.
- The quality of agent-generated code is primarily bounded by the quality of constraints provided to the agent.
- Human code review alone is insufficient to catch architectural violations in agent-generated code at scale.
Inferences:
- Therefore, the architect's primary deliverable shifts from designs to constraints.
- Therefore, organizations without codified architectural constraints will get worse outcomes from AI agents than those with them.
Narratives
- The authors started writing a book about architecture-as-code through their usual iterative process (workshops, conference presentations, online classes), then 'the entire industry shifted' with the arrival of agentic AI, giving their concept an unexpected new audience and purpose.
→ Establishes the timeliness and serendipity of the concept — it was designed for human architects but turns out to be exactly what AI agents need, lending it a sense of inevitability. - An architect defines components via a diagram, hands the diagram to a team, and cannot be sure the team implements it correctly. With architecture-as-code, a new component triggers a notification rather than silently drifting.
→ Illustrates the feedback-framework concept and the key distinction from testing: divergence is information, not error. - An LLM asked for an algorithm that touches all 50 US states generates a 50-stage switch statement — brute force. A cyclomatic complexity limit would force it to find a better solution.
→ Concrete example of how deterministic architectural constraints prevent pathological agent behavior. The only specific example in the essay.
Questions addressed
- ✅ How can architects maintain design integrity when implementation is done by others (humans or agents)?
By defining architecture as code with verifications, creating a feedback framework that alerts architects to divergence. - ✅ How can AI agents be guided to produce architecturally sound code?
By providing deterministic architectural constraints as foundational rules, separating them from desired behavior. - ⭕ What aspects of architecture can be expressed as code?
Nine intersections are listed (implementation, engineering practices, infrastructure, generative AI, team topologies, business concerns, enterprise architecture, data, integration) but none are elaborated beyond naming. - ⭕ What tooling, languages, or frameworks support architecture-as-code?
Not addressed at all. The essay describes the concept without any concrete tooling. - ⭕ How effective is architecture-as-code in practice — does it actually reduce architectural drift or improve agent output quality?
Not addressed. No empirical evidence, case studies, or metrics are provided.
Gaps
- incompleteThe essay names nine intersections where architecture can be expressed as code but elaborates on none of them. The reader is left with a taxonomy but no understanding of what architecture-as-code looks like in practice for any specific intersection.
Read next: The forthcoming O'Reilly book 'Architecture as Code' by Ford and Richards; also ArchUnit (Java), NetArchTest (.NET), and fitness-function frameworks from 'Building Evolutionary Architectures' (also by Ford and Richards).closed byPresentation: APIs for Agents: Rethinking API Programs in the MCP Era — That essay names nine intersections where architecture can be expressed as code but elaborates none of them. This talk is the concrete, in-production elaboration — patterns, templates, decorators, control requirement/configuration schema, CALM Hub, and automated deployment gates — with a documented before/after (2 years to 1-2 weeks to ship a new API). - incompleteNo tooling, languages, or implementation approaches are mentioned. The concept is presented entirely abstractly. A reader who is convinced by the argument has no idea where to start.
Read next: ArchUnit, NetArchTest, Structurizr (architecture-as-code for C4 diagrams), jqAssistant; also emerging LLM guardrail frameworks like Guardrails AI.closed byThree more static code analysis sensors — Supplies the missing concrete tooling: dependency-cruiser rule sets with LLM-facing error messages, a custom coupling-analysis CLI, and LLM modularity-review skills as working architecture-as-code implementations. - incompleteThe claim that agents require deterministic constraints rests on a single example (cyclomatic complexity). Whether architectural constraints can meaningfully guide agents across all nine intersections — especially softer ones like team topologies or business concerns — is not examined.
Read next: Research on LLM code-generation quality with varying constraint types; agent benchmarks like SWE-bench that test structural compliance; the emerging literature on AI coding guardrails.closed byThree more static code analysis sensors — Examines which constraint types actually guide agents: import/folder rules work (with a meta-rule preventing folder escape), while modularity constraints defeat deterministic sensors and require semantic LLM review. - incompleteThe essay does not address the inherent tension between the 'feedback framework' philosophy (divergence is information, not error) and the 'inviolate rules for agents' philosophy (constraints are non-negotiable). These two framings are presented sequentially but never reconciled.
Read next: Consider whether the human-facing and agent-facing modes require different constraint strictness levels; look at how 'soft' vs 'hard' constraints are handled in constraint-satisfaction literature.closed byArticle: Agentic Fitness Functions: Extending Evolutionary Architecture Beyond Deterministic Rules — The earlier essay left the tension between 'divergence is feedback, not failure' and 'constraints are inviolate for agents' unreconciled. This article resolves it by naming two distinct layers explicitly: deterministic gates stay inviolate, while agentic checks are advisory feedback signals that can escalate to humans and, once stable, get promoted into a new deterministic rule — giving the reconciliation the earlier piece lacked. - uninformedThe essay does not engage with existing architecture-as-code tools and practices that already exist (ArchUnit, fitness functions from their own prior work, Structurizr, ADRs). It presents the concept as novel when significant prior art exists — including from the same authors.
Read next: 'Building Evolutionary Architectures' (Ford, Parsons, Kua) for fitness functions; 'Software Architecture: The Hard Parts' (Ford, Richards, et al.) for structural analysis tooling.closed byComprehension at AI Speed: Building a Context Store for Evolutionary Architecture — Explicitly engages the prior art that gap flagged as missing — Ford, Parsons, Kua, and Sadalage's evolutionary architecture and fitness functions, ArchUnit, and dependency-cruiser — situating 'architecture as code' as an application of an existing toolkit rather than presenting it as novel.
Related documents
- DoorDash Used Copilot to Convert Its XCTest-Based iOS Test Suite to Swift Testing
- 11 Tips For AI Coding With Ralph Wiggum
- Addy Osmani's Post
- Agent Skills: Google-Backed AI Coding Agent Workflow
- Have your agent record video demos of its work with shot-scraper video
- Agentic AI and Code Reviews
- Article: Agentic Fitness Functions: Extending Evolutionary Architecture Beyond Deterministic Rules
- Agents don't know what good looks like. And that's exactly the problem.
- Presentation: From AI Agent Demo to Production: Automated Testing and Evaluation
- Accelerating Delivery: How AI Agents Can Own the Initial Code Draft