Yes, partially. Spec-driven development solves the front of the loop. The back of the loop is where most large-codebase failures happen, and that’s where architectural grounding has to come in. The two compose.
Specs handle intent. Architecture-aware development handles the system the intent has to live inside. Agent context spans both, or you ship code that satisfies the spec and breaks the codebase.
What spec-driven development gets right
Ad-hoc prompting fails because intent is ambiguous, and ambiguity propagates into the code. Spec-driven development fixes this by capturing intent up front, in a structured artifact, before the agent generates anything.
Most spec-driven tools converge on three stages: requirements, design, tasks. Each stage produces a versioned artifact the agent reads before generating code.
This beats prompt-driven workflows for two reasons. The spec stays persistent, so the agent reasons against the same artifact across iterations rather than against a fresh prompt each time. The spec stays reviewable, so the team aligns on intent before the agent decides how to implement.
Intent capture is the foundation layer of coding with agents. Prompt-driven workflows skip it. On greenfield work, intent capture is often enough. Spec defines what to build. Agent generates code. No system in the way.
The question is what happens on an existing codebase.
Where large codebases reveal the gap
A production codebase carries relationships no spec can fully encode. A change to one service ripples through APIs, shared libraries, event streams, database contracts.
The spec describes the change you want. The system carries everything the change will hit.
Four failure modes show up: specs grow verbose to compensate, context selection becomes fragile, impact stays invisible until late, and implicit constraints get lost.
Specs grow verbose to compensate
Teams notice the gap and try to close it inside the spec. Service boundaries get described in detail. Contract versions get spelled out. Deployment ordering goes in.
Then the downstream consumers, and the constraints on each one. The spec turns into a parallel codebase, less maintained than the code it generates and stale by the time it ships.
Review effort shifts from code to markdown. The team ends up debating a document that already describes a system the team changed last week.
Context selection becomes fragile
The agent still has to load code into context to generate anything, and the spec stays silent on which code matters. So the agent guesses, and on a large codebase the guesses get architecturally expensive.
Two or three retrievals later, the agent has the wrong slice of the codebase loaded, and the generated code reflects whatever neighborhood the embedding picked up.
You see this most when the spec is technically clear but the change crosses files the spec author didn’t anticipate. The agent satisfies the spec inside the loaded slice and stays silent about everything else.
Impact stays invisible until late
The spec describes what to change. It says nothing about what the change touches.
So the agent generates code that satisfies the spec, the PR clears review, and the downstream consumer breaks two weeks later because the spec never named it. Staging if you’re lucky. Production if you’re not.
The failure is quiet at every individual point. The spec is right. The code matches the spec. The review covered everything in the diff. The thing nobody owned was the surface outside the diff, which is where the break actually happened.
Implicit constraints get lost
Some constraints live nowhere the spec can reach. The defensive check that exists because of an outage two years ago. The retry pattern that exists because a vendor rate-limits a specific endpoint. The schema column populated because a downstream auditor reads it.
The spec never sees any of these. The immediate code carries none of the reasoning. The reasoning lives in postmortems, design docs, and threads from eighteen months ago, which the agent has no path to.
This is the gap. Specs handle intent precisely. The system itself goes unmodeled. Closing it requires modeling the system the same way the spec models intent.
What architecture-aware development adds
The fix is structural. Architecture-aware development models the system the way specs model intent: as a queryable artifact the agent reads before generating code.
Where the spec says what to build, the architectural model says what already exists. The agent reasons against both. Three primitives carry the work:
- Code graph. A typed, directional model of every service, file, function, and dependency in the codebase. The agent traverses from one entity to another, instead of retrieving similar text chunks.
- Dependency tracing. Follows outbound calls from the change point to every downstream consumer. The agent sees the full call chain across services, beyond the immediate file.
- Change-impact propagation. Walks outbound edges from the proposed change to every entity it touches. The agent sees which consumers break if the change ships in isolation.
The primitives sit underneath the spec. The spec captures intent. The primitives capture system reality. The agent operates on both.
The differentiation against code search is the structural model underneath. Code search indexes code chunks and retrieves them by similarity. These primitives operate on a typed graph built from code, business context in tickets, tribal knowledge in design docs, and runtime configuration. Three of those four inputs sit outside a code-only index, and they carry the reasoning that fails the spec on large codebases.
A vendor claiming architecture-aware development should demonstrate three things during a pilot, in the first session, on your codebase. The agent should name the services affected by a proposed change before editing any file. It should surface downstream consumers that the spec didn’t name. It should reference existing patterns and shared libraries by name when generating code.
If the agent asks you to clarify which services exist in your own codebase, what you’re looking at is file-level reasoning dressed in architecture-aware marketing.
How AI coding agents understand software architecture is fundamentally structural work. The four signal classes feed a typed graph that the agent traverses, and the three primitives above operate on top of that graph.
How the two approaches compose
Specs and architectural grounding compose at three points across the agent’s work.
When the agent generates a plan, the spec says what the change should do. The graph says what currently exists and what the change will touch. Without the graph, the plan covers what you wrote down. Without the spec, the plan has no destination.
Together, the plan accounts for the change you want and the system you have.
When the agent writes code, the spec says what behaviour to implement. The graph says which existing pattern to extend, which library to import from, which boundary to respect. The code lands inside the system rather than next to it.
When the agent validates, the spec defines acceptance criteria. The graph defines impact surface. The spec answers does the code do what we asked. The graph answers does the code work in the system we have.
A piece of code can pass the spec and fail the graph. Both checks have to clear before shipping.
The tribal knowledge problem matters here too. Specs capture intent. The institutional memory of why the system is shaped the way it is sits outside the spec. When the agent starts shipping code faster than the team can update its architectural understanding, the design context falls behind the code being generated against it.
What software architects need from AI coding tools is different from what developers measure on a daily basis. Tools that ace the developer test sometimes fail the architect’s, and the gap shows up most clearly when both layers are in play.
Without the architecture, the agent writes code that satisfies the spec and breaks the system. Without the spec, the agent has no destination. You need both before the agent edits.
Bottom line
Spec-driven development works on large codebases only when you pair it with architectural grounding. Alone, it solves the easier half and leaves the harder half exposed.
The intent layer is well covered today. Spec tools have solved the front of the loop. The architectural layer is where the gap sits, and most tools claiming to address it operate at the code search layer rather than at the structural one.
Agent context needs to span both layers. Build only one and the codebase pays for the missing half over the next eighteen months.
