Spec-driven development went mainstream this year, mostly on the back of coding agents. GitHub shipped Spec Kit. Amazon built Kiro. Frameworks like Tessl and BMad showed up promising the same basic trade: write the spec first, let the agent handle the rest.

This approach creates a question: once an agent writes the code, is the truth held in the code? Or is it held in the human-written specification? 

The answer changes how a team should build, review, and maintain software going forward. Right now, most teams are answering it by accident rather than on purpose.

What is spec-driven development?

At its simplest, spec-driven development shifts work from writing code directly to writing a specification. An LLM reads the spec and writes the code. Increasingly, the spec serves as a primary artifact for an agent that loops through write, test, and refine stages until the code passes the tests.

For best results, this means the developer must assemble a proper spec. Beyond a feature list and a description of a procedure, a proper specification earns its value by including requirements, constraints, edge cases, and the reasoning behind design decisions.

At its best, spec-driven development hastens builds, reduces rework, and minimizes surprises once something ships. Measure twice, cut once. Except here, you save the measurements for later; the next person doesn't have to remeasure from scratch.

Intent never survives the trip to code cleanly

Hand the same specification to a thousand developers and you'll get a thousand defensible codebases. That's not new. 

Over time, organizations built conventions and review processes that pushed code toward predictable and understandable patterns—at least within their organization. Agents remove this slow human sanding process, but they don't remove the underlying nondeterminism that made it necessary. If anything, they amplify it. 

Ask the same agent to build the same piece of code twice and you may get two different implementations. That's fine for a first draft. It's a problem if you're building something that should serve as an enduring piece of infrastructure.

That's not an argument against spec-driven development. It's the reason for it. The spec was never supposed to make every implementation identical. Its job is to make sure the reasoning behind whatever gets built survives, no matter which version an agent happens to produce.

Reverse-engineering intent from code doesn't work

A specification shouldn’t be necessary when code can speak for itself, right? That’s a trap. At best, code tells you what it does. It often can’t even do that; aspects of its behavior may be controlled by upstream systems or out-of-view configuration files. 

Even when it can tell you what it does, it can’t tell you why. Many of us have looked at scripts and been confused by the previous dev’s choices—only to realize that we were the previous dev. If we can’t reason through our own past decisions, how are we going to reason through fifteen-year-old legacy code written by someone who left the company?

Writing software requires trade-offs to fit within constraints. The code bears the fingerprints of those influences, but it doesn’t spell them out. Interrogate the code long enough, and maybe you can understand its trade-offs. Maybe. A specification saves you that pain. It not only spells out the constraints and trade-offs, but explains the logic behind major choices.

What’s wrong with vibe coding?

The complexity and criticality of enterprise systems are why development teams often spend weeks assembling a specification for each new build. If they skip that work and go straight to their coding agent of choice, the bill comes due later. With interest.

Without design intent established before the build starts, coding agents repeat logic across the codebase. They don’t separate concerns. They build inconsistent error handling and logging from one module to the next.

That inconsistency has consequences in production: when logging isn't consistent, root-cause analysis during an incident takes longer. Every minute an on-call engineer spends confused by the format or content of a log line is a minute the incident stays open.

This is the velocity trap. Skipping design gets you to a rough draft faster. But the cost of every subsequent change climbs. Sustained velocity comes from making architectural decisions when they matter: at the start. The alternative leaves your team patching around the absence of a decision after it's already caused a problem.

A plan is not a spec

Some products have cut a compromise between spec-driven development and vibe coding. We call it “Prompt, Plan, Build.” We’ve seen it in domains where technical teams work through a platform layer that sits between them and the underlying code.

“Prompt, Plan, Build” goes like this: through an AI IDE, a user describes what they want to achieve—connecting Salesforce to SAP, for instance. The AI IDE uses the platform’s MCP to access tools and returns a plan. Once the user approves the plan, the agent runs with it. 

This improves on vibe coding, but not enough. Users can disagree with the plan and ask for changes, but the system doesn’t probe the users’ blind spots. 

To counter this pattern, we built the Digibee Digital Worker (DDW). The DDW creates a dialogue that explores edge cases and trade-offs instead of making assumptions and sprinting to the build phase. The first phase takes longer than it would with Prompt, Plan, Build, but it creates a detailed specification to guide the build and refer to later.

When Prompt, Plan, Build systems create something that resembles a spec at all, it tends to show up as a byproduct after the build. It’s a summary of what happened, rather than the artifact under review before anything gets built.

That gap matters. Without the upfront interview, the trade-offs get decided by default, without any human agreeing to the AI’s assumptions.

A lot of customers that I've spoken to, documentation is an afterthought. Sometimes there isn't documentation. So, you get that for free even before you do the build.
‍
- Jeyaram Deivachandran, Digibee head of forward deployed engineering

Durability favors the spec

Code doesn’t last as long as it used to. Frameworks come and go. A stack that felt current three years ago feels dated today. If the only record of your business logic resides in a script on a vendor tool scheduled for deprecation, you have a problem.

This is where the spec earns its keep. These detailed documents may initially keep a coding agent on task, but they endure into the future. The reasoning contained within them survives a framework migration. It survives a team turning over. It survives a model upgrade that changes how the agent writes code. 

Of course, this means that your team must update the spec alongside production code. That’s actual work that has to be completed, but Digibee builds it into the DDW. Update the spec, and the DDW rebuilds the integration.

The code will get rewritten. The reasoning, if you kept it somewhere durable, doesn't have to be rediscovered from scratch every time.

What a real spec buys a team

A real spec captures input from every role (architect, developer, tester, business analyst, etc.) in one place, instead of leaving it scattered across siloed conversations. Everyone can see the open questions, why they matter, and how complete the spec actually is. It becomes a place where you can hand a business stakeholder or a system admin their part of the problem and know it's tracked. 

This helps surface conflicts before a test fails downstream and someone has to go find out why. It also produces documentation as a byproduct of the build instead of an afterthought—an often neglected afterthought.

The spec preserves the full rationale of the system outside the context window, so it isn't lost to compaction or a session reset. And it acts as a guardrail: when trade-offs get surfaced proactively instead of left implicit, output quality stops depending so heavily on how senior the person doing the prompting happens to be.

One Digibee customer said the DDWs’ approach to spec-driven design would save time by eliminating back-and-forth between business teams and developers. Non-technical people could read the system’s flowcharts and process descriptions. This lets them understand expected integration behaviors directly instead of learning them through a developer’s filter.

Different artifacts, different jobs

Code goes under change control. It's what gets trusted at 3:00 am when something breaks. It gets judged on determinism: does it do the same thing every time, reliably, under load, at the edges?

The spec is the reviewed rationale for why the code looks the way it does. It gets judged on durability: does it still explain the system correctly a year from now, after the framework's been swapped out and half the original team has moved on?

Neither works alone. Code without a spec becomes archaeology every time someone new has to touch it. A spec without working code is just a well-organized opinion. They win on different axes. The mistake teams keep making is trying to swap one in for the other. They treat the spec as if it should determine behavior with the precision of code, or treat the code as if it should explain itself the way a spec does.

Get the split right and the payoff compounds: decisions get made and reviewed once and get reapplied across every future project that touches the same problem. Otherwise, someone must re-explain code from scratch, to every new session, every new hire, every new agent that comes along after.
‍
[Get early access to the first AI-native integration platform →]