Russell East's blog

Ask an LLM to modify an existing system, and it will often produce convincing code.

But ask it questions such as:

• What business capability owns this behaviour?
• What guarantees does this process provide?
• Which outcomes are possible?
• What happens if an external dependency fails?
• Which teams or systems would be affected if this service disappeared?

And the answers quickly become uncertain. The problem isn’t necessarily the model. The problem is the representation.

We Optimised Architecture For Humans, Not AI

Discuss how current architectural artefacts evolved.

Current architectural artefacts evolved over decades to help humans manage complexity. We created a rich ecosystem of specialised tools, each serving a distinct purpose:

• Source code: Defines implementation logic.
• APIs: Expose integration contracts.
• Sequence diagrams: Visualise runtime interactions.
• C4 diagrams: Map structural boundaries and relationships.
• Infrastructure diagrams: Illustrate deployment topology.
• ADRs: Capture historical decisions and trade-offs.
• Wiki pages: Provide narrative context and onboarding material.

These artefacts remain enormously valuable. They have helped generations of engineers build increasingly complex systems.

But they were designed primarily for human consumption.

They partition knowledge across multiple views, each describing only part of the system. None provide a complete semantic description of system behaviour.

Structural representations such as C4 are extremely effective at explaining what a system is made of. They do not, however, capture business intent, guarantees, outcomes, or operational expectations.

Humans compensate for these gaps remarkably well.

AI cannot.

The Missing Semantic Layer

Humans excel at filling in the blanks using intuition and tribal knowledge. AI cannot do this. While current artefacts explain the how and the where it runs, they rarely make explicit:

• Time: how behaviour evolves over time.
• Business responsibility: what the system is actually accountable for.
• Intent: why a capability exists.
• Outcomes: the complete set of possible results.
• Invariants: Conditions that must always remain true.
• Guarantees: reliability, consistency, security, and operational expectations.
• Effects: the downstream mutations and side effects of an action.

Because these elements are often missing, scattered, or implicit, AI struggles to reason about systemic change.

This matters because architecture increasingly lives outside the codebase.

Important knowledge frequently exists as:

• tribal knowledge shared in conversations
• PowerPoint diagrams
• wiki pages
• framework conventions
• Slack discussions
• institutional memory

Humans can navigate this ambiguity. Machines struggle.

AI Understands Structure Better Than Ambiguity

Large language models exhibit remarkable linguistic capabilities, but they do not possess intuition.

They cannot reliably infer missing architectural context or resolve conflicting information.

To reason effectively about software systems, AI performs best when information is:

• Explicit: avoiding hidden assumptions.
• Finite: bounded and well-defined.
• Structured: organised predictably.
• Causally connected: tracing clear paths from intent to outcome.
• Semantically clear: using unambiguous terminology.

Unfortunately, much of our architectural documentation looks very different.

Typical engineering documentation is:

• prose-heavy
• incomplete
• contradictory
• stale
• fragmented across multiple tools

When AI encounters this ambiguity, its usefulness declines rapidly. Instead of reasoning about architecture, it starts guessing.

The result is hallucinated behaviour, misunderstood boundaries, and inconsistent implementations.

The English Language Paradox

We currently use AI to consume large volumes of documentation because natural language is the universal interface shared by humans and machines.

English is the bridge between human intent and machine execution. But treating natural language as the sole source of truth for architecture may be a design flaw. Natural language is excellent for explanation. It is much less effective as an executable architectural model.

This creates several problems:

• The Translation Tax: We force AI to continuously translate vague prose into logical structures.
• The Hallucination Trap: Natural language is inherently ambiguous, requiring AI to infer missing context rather than compute facts.
• The Scale Limit: Complex distributed systems become increasingly difficult to describe precisely using prose alone.

The goal is not to eliminate natural language. The goal is to stop treating natural language as the only source of truth for architecture. Natural language should explain architecture, not define it.

Source Code Is No Longer Enough

Historically, human engineers held the system’s entire architectural blueprint in their heads and manually translated that vision into code. The source code was the ultimate artefact because humans controlled the context.

Increasingly, this dynamic is flipping. AI is transitioning from a passive autocomplete tool to an autonomous agent that translates high-level intent into functional code. As artificial intelligence takes on the bulk of implementation work, code ceases to be the primary constraint. Instead, the quality and precision of the underlying architectural representation become the ultimate bottleneck.

The Cost of Abstract Context

When AI is tasked with generating code without a formal architectural model, it operates in a vacuum. If a system’s true architecture remains trapped in legacy formats, the AI is starved of essential context.

We drastically limit AI capabilities when architecture is left as:

• Tribal knowledge: Unwritten rules shared only during human conversations.
• PowerPoint diagrams: Static, non-computable shapes boxes floating on a slide.
• Wiki pages: Outdated text files decoupled from the actual production environment.
• Framework conventions: Hidden assumptions embedded silently inside software libraries.

The AI Implementation Tax

Deprived of a rigorous semantic blueprint, an LLM cannot guess the broader systemic constraints. It treats every code generation task as an isolated problem.

This information deficit directly forces the AI to produce:

• Hallucinated behaviour: Creating logical pathways that violate unwritten system rules.
• Inconsistent implementations: Solving the same technical problem three different ways across different files.
• Accidental complexity: Introducing bloated, redundant code paths because it lacks a bird’s-eye view of the system.
• Weakened guarantees: Silently breaking critical architectural boundaries, security protocols, and data consistency models.

What Might Better Representations Look Like?

When code is generated at machine speed, structural rot happens at machine speed too. We cannot safely delegate implementation to AI until we can formally feed it the architectural guardrails.

To bridge the gap between human intent and AI execution, we must move away from passive text and static boxes. Future architectural representations must be machine-readable, deterministic data models. They need to transform abstract concepts into explicit, computable parameters.

An AI-optimised architectural representation must explicitly define eight core dimensions of a system:

• Responsibility: The precise domain boundaries and business capability ownership. It clearly states exactly what a specific component is accountable for.
• Intent: The underlying business logic and technical justification. It records why a particular piece of software or architectural pattern exists.
• Outcomes: A complete, finite matrix of all possible technical and business results. It eliminates guessing by mapping out every valid end-state.
• Rules: The core system invariants and business logic conditions that must always hold true, acting as unbreakable guardrails for AI code generation.
• Effects: A clear inventory of all downstream mutations, state changes, data emissions, and external interactions that occur across system boundaries.
• Guarantees: The operational baselines, detailing the exact security protocols, reliability targets, latency SLAs, and data consistency expectations.
• Time: The temporal lifecycle of the system. It models how data state changes, how events flow, and how system behaviour evolves over time.
• Causation: The deterministic lineage of system events. It provides a clear trace explaining exactly why a particular outcome occurred.

By formalising these dimensions into a unified, machine-computable semantic layer, we give AI the missing blueprint it needs. This allows automated agents to safely write code, predict systemic failures, and evolve architectures without human intervention.

My Experiment

Theory is valuable, but execution is the ultimate validation. Over the last few months, I have been actively experimenting with a Declarative Capability Language (DCL) to see if a structured semantic layer could fundamentally change how artificial intelligence interacts with software architecture.

The most striking, unexpected outcome of this experiment has been just how naturally large language models reason over capability-based descriptions.

Testing the AI’s Cognitive Limits

Instead of overwhelming the models with thousands of lines of syntax, I provided them with explicit, deterministic definitions of a system’s core parameters:

• Capabilities: What the system is fundamentally equipped to do.
• Intent: The objective behind any given operation.
• Outcomes: The explicit, finite end-states of an action.
• Effects: The downstream mutations and side effects.
• Policies: The strict governance, security, and operational rules.
• Lifecycle progression: How system states evolve chronologically.

The Results: Autonomous Systemic Reasoning

When provided with this blueprint, multiple LLMs independently recognised DCL as a highly optimal representation format for AI systems. Because DCL exposes semantic intent rather than granular implementation details, the models were able to reason about the system at a much higher, more sophisticated level than when given raw source code alone.

DCL’s core interaction model explicitly maps system behaviour as a direct causal chain:

Intent → Outcomes (via Capability).

By removing the noise of loops, variables, and framework boilerplate, we create a unified language designed from the ground up to be “implementable by both humans and AI.” It proves that when we give AI the right structural context, it stops guessing and starts engineering.
Intent → Outcomes (via Capability) and is designed to be “implementable by both humans and AI”.

Closing thoughts

As software development transitions from human-written code to AI-assisted generation, the discipline of software architecture must fundamentally evolve. The traditional methods we use to document, map, and discuss systems are no longer sufficient for a world run by autonomous agents.

The core question driving software engineering is permanently shifting.

We are moving away from the legacy paradigm:

• “How should we represent systems so humans can implement them?”

And rapidly moving toward an entirely new frontier:

• “How should we represent systems so both humans and AI can reason about them?”

This shift represents more than a mere change in tooling. It demands a complete philosophical overhaul of how we define system boundaries, intent, and guarantees. Solving this problem will become one of the most critical and defining architectural challenges of the coming year.

This is precisely why I am building the Declarative Capability Language (DCL). By moving away from ambiguous prose and focusing strictly on intent, outcomes, and capabilities, DCL provides the exact machine-computable semantic layer this new era demands. It bridges the gap between human strategy and machine execution, offering a concrete answer to how we will design, validate, and safely scale AI-driven software systems.