What is spec-driven development? How it differs from vibe coding, in plain English

The short version

• Spec-driven development: describe what you’re building and why, let an AI write it up as a detailed spec, then build from the spec in small, reviewable steps.
• The spec is the source of truth, not the code. When something is unclear, you go back to the spec.
• Compared with vibe coding: vibe coding goes by feel and never reads the code. Spec-driven development writes the intent and the rules down first.
• The catch: a spec is still a guess about what you want, and people rarely know until they can use the thing. Even GitHub calls the spec a living document.
• For an app your business relies on: put the rules in up front, and find the rest by reacting to the real app.

What is spec-driven development?

GitHub, which released Spec Kit for it, defines it like this: "Instead of coding first and writing docs later, in spec-driven development, you start with a (you guessed it) spec. This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code."

Writing a specification before building is as old as software. What is new is who does the writing. You give the AI a plain description, it drafts the detailed spec, and then it builds from that spec. In GitHub’s words: "Your primary role is to steer; the coding agent does the bulk of the writing."

How spec-driven development works

GitHub’s process has four steps, with a checkpoint after each one.

1. Specify. You give "a high-level description of what you’re building and why", and the AI writes a detailed spec. This step is "about user journeys, experiences, and what success looks like", not about technology.
2. Plan. Now the technical choices: the tools, the structure, the constraints, any compliance requirements. GitHub’s explanation: "a coding agent needs to understand the rules of the game before it starts playing."
3. Tasks. The AI breaks the work into "small, reviewable chunks", each one testable on its own.
4. Implement. The AI builds task by task, and a person reviews "focused changes that solve specific problems" instead of "thousand-line code dumps".

The person’s job runs through all four: "Crucially, your role isn’t just to steer. It’s to verify."

Spec-driven development vs vibe coding

Vibe coding, which we explained in what is vibe coding, is the opposite habit: describe what you want, accept what comes back, and go by results without reading the code. GitHub’s launch post describes the problem it set out to fix: "you describe your goal, get a block of code back, and often… it looks right, but doesn’t quite work." And: "This “vibe-coding” approach can be great for quick prototypes, but less reliable when building serious, mission-critical applications or working with existing codebases."

Its diagnosis is a good one: "We treat coding agents like search engines when we should be treating them more like literal-minded pair programmers."

• Where the intent lives. Vibe coding: in your head and the chat history. Spec-driven: in a written spec anyone can check.
• Where the rules live. Vibe coding: nowhere in particular. Spec-driven: in the plan, before any code is written.
• What a person reviews. Vibe coding: the result on screen. Spec-driven: the spec, the plan and each small change.
• What it suits. Vibe coding: quick experiments. Spec-driven: software that has to be relied on, built by a team or added to an existing system.

They aren’t strict opposites. Spec Kit’s own documentation says it supports a range of approaches, "from vibe-coding to AI-native development".

The catch: a spec is a guess about what you want

A spec is written before anyone has used the thing, and people are bad at knowing in advance what they want from software. The computer scientist Fred Brooks wrote in 1986 that "the client does not know what he wants", and thought it "really impossible for a client, even working with a software engineer, to specify completely, precisely, and correctly" what they need "before having built and tried some versions of the product he is specifying." Watts Humphrey put it more simply: "What the users think they want will change as soon as they see what we develop."

Spec-driven development’s authors know this. GitHub says the spec "becomes a living artifact that evolves as you learn more about your users and their needs", and Spec Kit "does not prescribe how teams preserve or mutate" the spec "after requirements change". GitHub’s own checklist starts with the right question: "Does the spec capture what you actually want to build?"

So the question isn’t whether the spec will change. It will. The question is how you find out what to change it to: by reading a document about the software, or by using the software.

What this means if you’re commissioning an app

If you run a business rather than write code, you will probably never see a spec file. What matters is what you are asked to approve. Approving a document about an app is hard, because most people can’t picture an app from a description. Approving the app itself is easy: you tap through it on your phone and say what’s wrong.

The sensible middle takes the best of both. Some things you do know in advance, and they belong in the rules from the start: the law on personal data, the App Store and Google Play rules, and a sound structure the app can grow on. That is GitHub’s "rules of the game". The rest, what the app should actually do and how it should feel, you find out by reacting to the real thing.

That is how we build apps at Lola Squared. The rules are built into our own platform, the real app is on your phone from the first version, and you steer by saying what’s right and what isn’t. There’s more on our mobile apps page.

What argues the other way

• A spec wins when many people must agree in advance: a large team, an existing system, a fixed contract, or two pieces of software that have to talk to each other. Spec Kit has a separate approach, Contract-Driven Development, for that last one.
• Writing it down is cheaper than it used to be. When the AI drafts the spec, being explicit costs minutes, not weeks.
• A working app can mislead too. Real screens pull attention towards colours and wording before the bigger questions are settled, so reacting needs some discipline.
• We sell the reacting approach, so we aren’t neutral. Every quotation is linked so you can judge for yourself.

Sources, and what we checked

• Den Delimarsky, GitHub Blog, “Spec-driven development with AI: Get started with a new open source toolkit”, 2 September 2025.
• Spec Kit documentation, “What is Spec-Driven Development?”, read on 3 October 2026.
• Frederick P. Brooks, Jr., “No Silver Bullet: Essence and Accidents of Software Engineering”, University of North Carolina technical report TR86-020, September 1986. Watts S. Humphrey, “Some Programming Principles: Requirements”, first quarter 2003, in The Watts New? Collection (CMU/SEI-2009-SR-024).
• Every quotation above was tested automatically against the text of its source before publication.