Executable Architecture: Why AI Agents Make It Worth Building

Somewhere in your repository there is a CLAUDE.md that started as ten lines. It now runs to pages of rules about which components may talk to which, where data is allowed to live, and how integrations are supposed to work. It is your architecture diagram, rewritten as prose and re-read by a model on every task. This post is about the alternative, which I call executable architecture.

A best practice is something a person follows. Architecture is what the system enforces.

A team of disciplined engineers who layer their code well, keep their modules cohesive, and write testable components is a team with good practices. That alone does not make an architecture self-enforcing. Architecture is, among other things, what you get by pushing those practices up the stack, out of individual habit and into the structure of the solution. They have to hold on the day the disciplined engineer is on vacation, has rolled off the project, or was never on it in the first place. That last case used to be hypothetical. Now it describes every AI agent on every task.

What Executable Architecture Means

Executable architecture is architecture that lives in the platform instead of in documentation or diagrams. The solution’s boundaries, relationships, and rules take the form of things that run and enforce themselves. Think of context boundaries the build refuses to let you cross, contracts with tests that define what two systems owe each other, and extension points that make the intended pattern the easiest one to follow. The diagram still exists, but now it comes from the system instead of describing what the system should become.

The term has older uses. In RUP it named the early build that proved the architecturally significant requirements, and in defense modeling it names an architecture description formal enough to simulate. By executable architecture I mean something more literal. The architecture itself runs, as build rules, contract tests, and extension points.

The opposite is architecture as intention. Diagrams, decision records, wiki pages, the standards deck from 2023. All of it describes what the system should be, and none of it can make the system be that. The system doesn’t read documents, and the agent that does treats them as suggestions.

Not every architectural decision becomes executable. Quality attribute tradeoffs, decomposition choices, and technology selection remain judgment, and writing them down is still the right move. Even there, the split holds. The rationale for a decomposition belongs in the decision record, while the system can still enforce its consequences, the module boundaries and dependency rules. The distinction the rest of this piece leans on is between knowledge and structure. Knowledge is procedural and contextual, and documents and context are its natural home. Structure is a claim about what must hold in the system, and every structural claim that can be enforced stops being an expectation placed on contributors and becomes a property of the solution.

The Diagram Was Never the Deliverable

During my career, I’ve often observed the push up the stack stopping at documentation. We took the practices, abstracted the principles, drew the boxes, and called the drawing architecture. Then we relied on humans to close the gap between the drawing and the code. Review culture, onboarding, tribal knowledge, and the one senior engineer who remembers why that boundary exists and catches the pull request that violates it.

It sort of worked, because humans persist. An engineer learns your conventions once and carries them for years. The cost of architecture-as-intention was real, but it was diffuse and slow. The boundary erodes over eighteen months, the coupling shows up as rework two quarters later, and nobody can trace the bill back to the decision. So the gap between drawn architecture and executable architecture never felt urgent enough to close.

Agents Don’t Attend the Brown Bag

An agent has no tenure. It didn’t sit through onboarding, it wasn’t in the room for the design review, and it won’t remember this session next week. Everything it knows about your solution arrives through its context window, at a cost, on every task.

Which means the gap between intended architecture and executable architecture is no longer diffuse. It gets paid per task, in tokens read, retries burned, review comments on conventions the agent had no way to know, and rework on code that compiled fine and coupled things that should never have met.

That is why instructions files keep growing. The rules in them are the architecture diagram, reincarnated as prose, followed probabilistically instead of enforced deterministically. It’s the same gap, rebuilt in a new place and paid for per token.

Push the Practice Into the Platform

The fix is the move that was always architecture’s job. Take the thing a careful engineer does and convert it into a property of the solution.

Boundaries the build enforces

Brian Ball, a colleague at SEP, wrote about bounded contexts in agentic development, and the same idea applies at the level of the solution’s structure. A boundary is only real if something enforces it. Separate compilation units, module visibility, dependency rules that break the build when one context reaches into another’s internals.

Contracts between systems

The same move applies to the seams between systems. The understanding between two services, the one that used to live in a design review and a hallway conversation, becomes a published contract with tests attached. The contract, rather than knowledge of the other system’s internals, becomes the basis for integration, which means an agent can build against a system it has never read. Integration is where solutions usually break, and it’s also where an enforced agreement replaces the most tribal knowledge.

The domain itself

The most valuable version of this is the domain itself. Concerns like authentication, data access, and observability are the easy cases, because plenty of frameworks and platforms provide those slices. The harder move is building the domain’s own rules and patterns into the structure of the solution. The ways your system is expected to vary sit behind defined interfaces as strategies. A new pricing rule, routing decision, or eligibility check is then one new implementation in one designed place. The extension point carries the convention.

Following best practice becomes the lowest-friction way to build, because the shape of a correct answer is already defined. Future complexity has a place designed to receive it instead of arriving as modification of what already works. For an agent, that structure is the difference between a task that resolves to implementing one interface and a task that starts with a search through the codebase.

Constraints and reduced complexity do different jobs. Some decisions become constraints, where the build or the registration step rejects the violation outright. Others become reduced complexity, where extension points make the intended change local and straightforward without making every alternative impossible. Both take architecture out of contributor habit, but only the first guarantees anything. That’s fine, because stopping the wrong thing is only half of architecture’s job. Providing a designed place for the right thing is the other half.

Kindling as a worked example of executable architecture

This is the thinking behind Kindling, an open-source Spark orchestration framework we’ve been building at SEP. The decisions that would normally live in a data platform standards document (how streaming sources are managed, where slowly changing history lands) are properties of the framework instead. Engineers declare pipelines and their data entities, and the framework derives dependency ordering and execution from the declarations. The shape of the solution comes from the code rather than living beside it. Platform variation sits behind a service layer, so the same declarations run on Fabric, Synapse, Databricks, and plain local Spark. Local execution matters as much as any cloud target. A pipeline runs and tests on a laptop or in CI without a workspace or credentials. That is the deterministic feedback loop an agent needs to check its own work.

The conventions work the way described above. Declaring a derived dataset or a slowly changing dimension is a single declaration that lowers to a small vocabulary of tags, which the framework validates when the entity registers. The syntactic sugar makes the best-practice shape the cheapest one to write, and the tags keep everything overridable when a case doesn’t fit the existing semantics. Because engines read only the tags, a new storage backend or platform target is an implementation behind an existing interface. Registration is where the constraint side shows up. Declare an entity as a slowly changing dimension without naming its business keys, and it never registers. The framework rejects at declaration time what would otherwise surface downstream as a merge with no way to identify its records.

What this adds to fitness functions

None of these mechanisms is novel. Architects have called the constraint half fitness functions since Ford and Parsons named them, and tools like ArchUnit and contract-testing frameworks have been failing builds over them for years. A reasonable reaction is to ask what executable architecture adds. Fitness functions cover the constraint half. What changed is the extension-point half, where the platform makes the intended change the cheap one, and the economics, now that agents attach a per-task cost to everything left in prose.

Each architectural rule you enforce in the platform stops depending on repeated explanation for compliance. Each convention you build makes the intended change the easy one, for people and agents alike. Documenting an enforced rule is still useful. The difference is that the documentation is no longer the mechanism keeping it true. If prose is the only thing preventing a structural violation, the rule is living in the wrong layer. Kindling’s own agent instruction files are a working test of this. They stay short, mostly orientation and process, because much of what they would otherwise have to explain is enforced by the framework instead.

Executable Architecture Beside Skills and Context Management

Teams are already working around the growing instructions file, and the workarounds are becoming more effective. Instructions get split into per-directory files so an agent only reads what’s near the code it’s changing. Skills, which are packaged instructions an agent loads only when a task calls for them, hold procedural knowledge instead of sitting in every prompt. Subagents run with a scoped context of their own. All of this is progressive disclosure, routing the right prose to the right task at the right time. It lowers the cost of carrying conventions as text.

Executable architecture doesn’t replace any of it, because they’re solving different problems. Skills and scoped context are the right home for knowledge, such as how to run the release, what the domain terms mean, and how this team approaches migrations. Those things are procedural and contextual, and prose is their natural form.

Structural rules are different. A rule about which components may depend on which, what shape a new pricing rule takes, or what two systems owe each other can be delivered as perfectly routed prose and still be interpreted rather than enforced. It still drifts from the code it describes, and it is still followed only probabilistically. Enforcement does what routing can’t. It checks the encoded rules against the actual system, without depending on the agent remembering or interpreting them. The sorting question for any given line is whether it’s knowledge or structure. Knowledge goes where context management can find it, and structure goes where the system enforces it.

The Economics of Executable Architecture Have Changed

There’s a fair objection to all of this, and it’s much of the reason architecture stopped at diagrams. Executable architecture was expensive. The enforcement layer, the platform capabilities, the contract suites, and the reference implementations all meant serious engineering effort spent on things that never shipped a feature. What did get built was often brittle, tied to one moment in the solution’s life and painful to change when the architecture evolved. Most organizations looked at that bill and made a rational call. Draw the intent, staff good people, and hope the review process holds. The diagram was what the economics allowed.

AI changed both sides of that equation. It made unenforced architecture more expensive to live with and enforced architecture cheaper to build. The same agents that pay the cost of the first supply the labor for the second. They also reduce the effort of keeping the enforcement layer current as the architecture evolves. An architect working with agents can turn an integration decision into a contract suite the same week the decision is made. They can stand up the platform capability instead of writing the standard that describes it.

The proof of concept that used to be sketched and thrown away becomes the first real version of a component or a service. The prototype that demonstrated a pattern becomes the framework that enforces it, and the framework becomes the platform that provides it. That progression isn’t hypothetical. It’s the path Kindling has followed, with agents doing a real share of the build. The distance between deciding something and making it real in the system is far shorter now.

Cost was a large part of why this work stayed in documents, and it no longer carries the weight it used to.

The Deliverable Is the Platform

If your architecture lives in a diagram, it’s a suggestion. If it lives in the platform, it’s a property of the system. Agents changed the price on both sides of that distinction. Ignoring it went from a slow leak nobody could measure to a line item on every task. Building it went from a program that rarely got funded to work an architect can drive directly.

Any team investing in agentic development can test this with one question. How much of your architecture would survive a contributor who never met your team, never read your wiki, and forgets everything between sessions? Whatever survives that test is your executable architecture. The rest is still intention.

✨ AI Post Recap