Spec-Driven Development: Why the Spec Is Becoming the Real Source Code

The hardest part of software used to be writing and reviewing code. That is no longer where the difficulty lives. With a capable model sitting in your editor, the bottleneck has moved: the hard skill now is telling the machine precisely what you want built.

That shift is the whole argument behind spec-driven development, the topic of a recent IBM Technology video by Cedric Clyburn. Here is what it covers, plus my notes on where it lands in practice.

First, what vibe coding actually is

Vibe coding is the loop most people picture when they hear "AI-assisted coding":

1. You open a coding agent, in the browser or on your machine.
2. You write an initial prompt: build me an app that does X, in Python.
3. The model generates code based on what it infers you want, plus everything it learned in training.
4. The result is close but not right. You edit the prompt: actually, use a different library.
5. Back and forth, a few rounds, until you land on something acceptable.

This is genuinely great for boilerplate and for testing an idea fast. It feels like magic, and for throwaway work it usually is.

The problem is what happens underneath. Why did the model make that particular architectural choice? Run the same prompt a hundred times and you can get a hundred different implementations. There is no artifact that explains the decision, because there was no decision, there was an inference. And that unpredictability is not a model bug. It is a process gap.

The step vibe coding skips

Traditional software engineering has a lifecycle for a reason. The SDLC runs roughly: plan and design (the PRD), then implement, then test and QA, then deploy (dev to staging to production), then maintain.

Vibe coding jumps straight from a one-line prompt to implementation. Every stage before the code, the requirements, the design, the agreed-on behavior, gets collapsed into a sentence and handed to a model to guess at. Spec-driven development puts those stages back, but keeps the LLM doing the typing.

How spec-driven development works

The loop looks superficially similar, it still starts with a prompt, but what you are prompting for is different. You are not prompting for an implementation. You are prompting for what the system should do: its behavior and its constraints.

1. Prompt to specification. You describe behavior and constraints, not code.
2. Specification to requirements. The spec becomes a contract. This requirements document is the top of the hierarchy: how the agent writes code, how it tests, how it documents, how it verifies, all of it hangs off this.
3. Review gate. Are you happy with the requirements? If not, edit them. Nothing has been implemented yet, so editing is free.
4. Requirements to design document, with to-dos broken out per implementation item.
5. Second review gate. Happy with the design? Then release the agent to implement it. Not happy? Keep iterating on the design, still no code written, still cheap.
6. Implement. Now the agent codes, against a document instead of a vibe.

The two review gates are the point. Both sit before any code exists, which is exactly where changing your mind costs almost nothing.

Spec-driven development is test-driven development and behavior-driven development on steroids.

Where it sits next to TDD

The ordering is the whole story:

• Traditional: code first, documentation after, starting from intuition.
• Test-driven (TDD): tests first, then the code that satisfies them.
• Spec-driven (SDD): spec, then requirements, then design, then code.

Same instinct as TDD, writing the contract before the implementation, pushed one level further up. TDD pins down behavior at the function level. A spec pins it down at the system level, before you have decided what the functions even are.

A concrete comparison

Vibe coding a login page:

We need a /login page for our users to authenticate.

Perfectly reasonable request. But the model has thirty ways to build that, and you have no idea which one is coming. You will go a few rounds correcting it, and sometimes that round-tripping takes longer than just writing the thing yourself.

Spec-driven, same feature:

Feature: User authentication

  Endpoint:  POST /login
  Variables: user, pass
  Failure:   error code if username missing

  Test: valid credentials -> 200

Nothing is implemented yet. This is purely the planning phase. But now every downstream decision is pinned: the endpoint and method are fixed rather than guessed, the parameter names are fixed, the failure path is defined before the happy path is written, and the test cases fall out of the spec for free, because you already stated the expected behavior. When the implementation arrives, you can trace every line back to a sentence you approved. The "why did it do that?" question finally has an answer.

The actual takeaway

The point is not that vibe coding is bad. It is fast, and it is the right tool for prototypes, spikes, and quick edits on the fly.

The point is ambiguity reduction. Coding agents are exceptionally sensitive to instruction quality, and a spec beats letting a model guess which solution best fits your request. Spec-driven development flips the traditional model so that the spec, not the code, becomes the primary artifact. Implementation, tests, documentation, and verification all become downstream products of it.

That is a meaningful role change for developers: less typing, more specifying. You become the supervisor and the strategist, and the agent handles the keystrokes. If you are building anything you intend to maintain, that is the trade worth making.

Based on "Spec-Driven Development: AI Assisted Coding Explained" by Cedric Clyburn, IBM Technology.