by Guillermo Quiros
Spec-Driven Development has real value. It helps humans and AI agents understand what needs to be built. But if you have ever watched a building site, you already understand its limitation too: a specification alone is not enough to align everyone around the same structure.
Why SDD Needs to Be Extended with Architecture Driven Development
Imagine a client walks up to a team of builders and says:
I want a house. Four bedrooms, a kitchen, and a patio.
That is a specification. It describes what the client wants.
The builders nod. They are professionals. They get to work.
The result may be technically correct. It may even be well built. But it is still a gamble.
Not because the builders are bad at their jobs, and not because the specification is useless. The problem is that every person on the site has formed their own private picture of what "four bedrooms, a kitchen, and a patio" means.
One builder imagines an open-plan kitchen flowing into the patio. Another assumes the kitchen is separate. One assumes the master bedroom faces the garden. Another places it at the front. Nobody is wrong. They are all working from the same words, filling in the blanks with their own experience, their own defaults, and their own interpretation of what the client probably meant.
The client, of course, may have had a completely different picture in mind.
By the time anyone compares notes, walls are already up. Decisions that looked local now have global consequences. Changing the kitchen layout may mean moving load-bearing structure. The cost of correction is far higher than the cost of alignment at the start.
This is how building projects become expensive: not because the initial specification had no value, but because the specification was asked to do a job it was never designed to do.
A specification captures intent.
A floor plan captures structure.
You need both.
Software Has the Same Problem
Software development has lived with this problem for decades.
In the 1980s and 1990s, teams tried to close the gap between business intent and implementation by writing better requirements documents. Business Analysts wrote detailed specs. Developers received them and built the system.
This was useful, but it had limits.
A requirement can tell you what the system should do. It rarely tells you how the system should be shaped. It does not define service boundaries. It does not explain which component owns which responsibility. It does not reveal which dependencies are intentional and which ones are dangerous. It does not describe the load-bearing structure of the system.
So developers filled in the gaps.
Different developers made different data model choices. Different teams drew different service boundaries. Different interpretations produced different systems.
This is not a failure of SDD. It is a limitation of SDD.
Spec-Driven Development is good at expressing desired behaviour. But software systems are not just collections of behaviours. They are structures. They have boundaries, dependencies, ownership, constraints, and long-term consequences.
That is where SDD needs to be extended.
Why AI Makes This More Urgent
With AI coding agents, the industry is rediscovering this problem at much higher speed.
An AI agent can take a specification and generate code in seconds. That is powerful. It makes SDD more valuable, not less. A clear spec gives the agent direction. It reduces ambiguity at the feature level. It helps describe the expected outcome.
But the agent still needs to know where the work fits.
It needs to know that an Email Service already exists. It needs to know that the Export Worker should publish an event rather than send notifications directly. It needs to know that token generation belongs in the Token Service. It needs to know that two containers were deliberately decoupled because of a painful lesson from eighteen months ago.
A feature specification usually does not contain that information.
So the agent makes reasonable local decisions. It writes working code. The code may pass tests. The feature may behave correctly. But the system slowly becomes less coherent.
This is the central limitation of SDD in the AI era:
SDD can tell an AI agent what to build. It does not reliably tell the agent where that work belongs inside the system.
And when agents are producing code faster than human teams can review it, that missing context becomes expensive quickly.
The Floor Plan Metaphor
Consider two ways to commission a house.
The first is specification-driven:
I want a three-bedroom home with a garage and a swimming pool.
A skilled builder can produce a good result from that brief. But ask five builders to work from the same brief and you will get five different houses. Different layouts. Different proportions. Different relationships between rooms. Different structural decisions.
The second is architecture-driven:
You hand the builders a floor plan. Walls, dimensions, load-bearing structure, room relationships, utility routes, entrances, constraints.
Now ask five builders to work from that plan. The results may still vary in small implementation details, but the core structure will converge. Everyone is building the same house because everyone is working from the same architectural model.
Software needs the same distinction.
A specification tells the team what should exist.
An architecture tells the team how it fits together.
SDD gives us the brief.
ArDD gives us the floor plan.
SDD Is Necessary, But Not Sufficient
The point is not to abandon Spec-Driven Development.
That would be the wrong lesson.
SDD is valuable because software teams and AI agents need clear descriptions of desired behaviour. Without specifications, implementation becomes vague, subjective, and difficult to validate.
But SDD alone is not enough for modern software development, especially when AI agents are involved.
Why?
Because most important software failures are not purely feature failures. They are structural failures.
The feature works, but it lives in the wrong service.
The endpoint works, but it bypasses the intended boundary.
The new workflow works, but it duplicates existing logic.
The integration works, but it introduces coupling that will be painful later.
The agent followed the spec, but the system became harder to understand.
In all of these cases, the specification may have been correct. The missing piece was architectural context.
That is why SDD should be extended with Architecture Driven Development.
What Architecture Driven Development Adds
Architecture Driven Development, or ArDD, extends SDD by making the living architecture model a primary source of context for developers and AI agents.
In practice, this means maintaining a clear model of the system: the containers, components, responsibilities, boundaries, and relationships between them.
The model answers questions that a feature spec usually does not:
- Where does this capability belong?
- Which component owns this responsibility?
- Which existing service should be reused?
- Which dependencies are allowed?
- Which boundaries should not be crossed?
- Why was this part of the system designed this way?
This is the architectural context an AI agent needs before it writes code.
With SDD alone, the agent receives the task.
With ArDD, the agent receives the task and the map of the system.
That difference matters.
How SDD and ArDD Work Together
The strongest development process is not SDD or ArDD. It is SDD extended by ArDD.
SDD defines the desired behaviour:
- What should the user be able to do?
- What should the system produce?
- What rules should the feature follow?
- What acceptance criteria define success?
ArDD defines the structural context:
- Where should the feature live?
- Which container or component owns it?
- How should it interact with the rest of the system?
- Which architectural constraints must be respected?
- What should the agent reuse instead of recreate?
Together, they create a much stronger instruction set for both humans and AI agents.
The specification says: build this.
The architecture says: build it here, in this way, respecting these boundaries.
That is the extension SDD needs.
What This Changes for AI Agents
An AI coding agent should not be treated as a simple requirements executor.
It is closer to a fast developer: capable, productive, and highly dependent on context.
Like any developer, it makes better decisions when it understands the system it is working in. Without that understanding, it optimises locally. It solves the task in front of it. It chooses plausible patterns. It fills in missing information with assumptions.
That is exactly where architectural drift begins.
An agent with architectural context behaves differently. It knows that a service already exists. It knows which component owns a business capability. It knows where not to place new logic. It knows which dependencies would violate the intended design.
The result is not just faster code generation. It is more coherent code generation.
This is the real promise of extending SDD with ArDD: not replacing specifications, but making them safer and more effective by grounding them in architecture.
What This Changes for Teams
The benefits go beyond individual AI-agent tasks.
Teams work from a shared model instead of private mental models. Ask five engineers to describe the same system and you often get five different answers. That does not mean the team is incompetent. It means the architecture lives in people's heads, and those mental models quietly diverge.
ArDD makes the architecture explicit.
It gives teams a shared reference for deciding where features belong, how components should interact, and what each part of the system owns. Conversations start from the same map instead of competing interpretations.
It also makes change easier to trace. When a feature is implemented within an architectural model, you can see not only what code changed, but what part of the system changed. You can review implementation against structure, not just against local correctness.
And as teams scale, this becomes even more important. Adding more developers or more AI agents increases output. Without shared architecture, it can also increase inconsistency. ArDD helps scale contribution without losing coherence.
The Vibe Coding Problem
There is a failure mode in AI-assisted development that has become increasingly visible: vibe coding.
Vibe coding means using AI to generate code without deeply understanding what the code does, how it fits into the system, or why it was written that way.
SDD alone can reduce some of this risk by making the requested behaviour explicit. But it does not fully solve the problem, because the agent can still produce code that satisfies the spec while damaging the architecture.
ArDD addresses the deeper issue.
It gives the human team and the AI agent a shared structural model. The agent does not just know what the feature should do. It knows how the feature should fit. The team does not just review whether the code works. It reviews whether the code respects the architecture.
That is how AI-assisted development becomes more disciplined.
Not by limiting AI, but by giving it the right context.
Getting Started
Extending SDD with ArDD does not require a perfect architecture model before work begins.
It requires a commitment to treating architecture as a first-class development artefact.
Start by modelling what you already have. Even a small set of containers with clear responsibility descriptions is enough to create value.
Put the model in the repository alongside the code. Make it versioned. Make it visible. Make it part of the development process, not a static diagram hidden in a documentation tool.
Connect AI agents to the model so they can access live architectural context before implementation begins.
Then evolve the model as the system evolves. When a feature requires a new container, update the architecture first. When a boundary changes, make that explicit. When an implementation drifts from the model, detect it and correct either the code or the architecture.
The goal is not documentation for its own sake.
The goal is alignment.
The Deeper Point
The software industry learned long ago that writing better requirements documents was not enough. Clear requirements matter, but shared understanding matters more.
AI does not remove that lesson. It makes it more important.
AI agents are the new builders. SDD gives them the brief. But a brief is not a floor plan.
To produce coherent software at speed, agents need architectural context. They need to understand the system they are changing, the boundaries they must respect, and the structure their work must fit into.
So the message is not:
Spec-Driven Development fails.
The better message is:
Spec-Driven Development is necessary, but not sufficient. It needs to be extended with Architecture Driven Development.
Do not stop at specifying your AI.
Architect the context around it.
Suggested Closing Line
Architecture Driven Development extends Spec-Driven Development by adding the missing system context: the living architecture model that tells humans and AI agents not just what to build, but where it belongs and how it should fit.