What Is Spec-Driven Development? (And Why It Fixes Vibe Coding)

45% of AI-generated code samples introduced OWASP Top 10 vulnerabilities across 100+ tested models (Veracode, 2025). 66% of developers say their top AI frustration is output that’s “almost right, but not quite” (Stack Overflow 2025 Developer Survey). The models keep improving. The failure mode hasn’t changed.

The gap is the spec. Without a contract describing what you want, an AI fills the void with plausible-looking code that drifts from intent — three rewrites later you’re still not shipping. Spec-driven development closes that gap by making the specification, not the prompt and not the code, the source of truth your tools and agents build from.

If you’ve been vibe coding and watching your AI rewrite the same dashboard six times in a row, the fix isn’t a better prompt. It’s a spec.

What Is Spec-Driven Development?

Wikipedia’s definition is the cleanest: “Spec-driven development is a software engineering methodology where a formal, machine-readable specification serves as the primary artifact from which implementation, testing, and documentation are derived” (Wikipedia, 2026).

The practitioner framing from GitHub’s Den Delimarsky is more operational: “Instead of coding first and writing docs later, in spec-driven development, you start with a 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” (GitHub Blog, September 2, 2025).

Both definitions share one idea: the spec is upstream of everything. Code is a compilation target. Tests are a consistency check. Documentation is a projection. The spec is what you author, review, and version.

The Term Is Older Than It Looks

Spec-driven development didn’t arrive with AI. Wikipedia traces it to 1960s NASA workflows and a formal academic treatment by Ostroff, Makalsky, and Paige at the XP 2004 conference. Formal methods, contract programming, and model-driven engineering all sit in the same lineage. What changed in 2025 is that large language models made the cost of “write the spec first” collapse: the spec itself can be drafted, refined, and turned into code by the same agent, as long as the spec is the artifact everyone argues about.

The Problem Vibe Coding Created

Vibe coding made it possible to describe a feature in plain English and get working code back in seconds. That’s the upside. The downside shows up at scale, and the data from the last twelve months is unambiguous.

A Veracode 2025 study cited in the Cloud Security Alliance’s April 4, 2026 research note found 45% of AI-generated code introduced OWASP Top 10 vulnerabilities across 100+ tested LLMs; Java samples failed 72% of the time, and 88% were vulnerable to log injection (CSA Research Note). Apiiro’s enterprise telemetry in the same note showed AI-assisted developers produced commits at 3–4x the rate of peers, while security findings rose roughly tenfold and privilege-escalation paths climbed 322% over six months.

Productivity data is just as stark. A July 2025 METR randomized controlled trial found experienced open-source developers were 19% slower when using AI coding tools, despite predicting a 24% speedup (METR RCT, July 2025). The Stack Overflow 2025 Developer Survey (n = 48,945) found 84% of developers use or plan to use AI, but only 33% trust AI accuracy while 46% actively distrust it.

The pattern is consistent: AI writes fast, generates superficially plausible code, and leaves you to clean up architectural drift and security gaps. The Stack Overflow team connected the dots explicitly in their 2025 write-up, calling out “spec-driven development” by name as the structural response. We covered the full scaling picture in Vibe Coding Has a Scaling Problem.

How Spec-Driven Development Works

GitHub’s Spec Kit is the clearest reference implementation. It formalizes a four-phase workflow every spec-driven project moves through, and the phases work whether you’re using Claude Code, Cursor, Copilot, Gemini CLI, or any of the 20+ other agents Spec Kit targets.

The Four Phases

1. Constitution. Project-wide invariants. Your stack, your conventions, the things every feature inherits. This is the document every downstream spec references.
2. Specify. A feature-level spec: goals, non-goals, constraints, acceptance criteria. This is what the agent reads before it starts planning.
3. Plan. The agent decomposes the spec into architectural decisions and task breakdowns, then hands the plan back for human review.
4. Tasks / Implement. Only now does code get written. Each task traces back to an acceptance criterion in the spec, which means divergence is visible rather than silent.

An optional Clarify phase sits between Specify and Plan; the agent asks the questions a human reviewer would ask before committing to an approach. The Spec Kit repo is open source, MIT-licensed, and sat at roughly 90,000 stars with active v0.7.x releases as of April 2026 (github.com/github/spec-kit).

The Three Maturity Levels

Birgitta Boeckeler’s October 2025 article on martinfowler.com breaks spec-driven development into three ascending levels of commitment (Boeckeler, October 2025):

• Spec-first. You write a spec before prompting. The spec informs the AI but isn’t regenerated as code changes. Simplest, lightest, most teams start here.
• Spec-anchored. Spec and code stay in sync. When code drifts, the spec is updated; when the spec changes, code is regenerated. This is where Spec Kit and Amazon Kiro live.
• Spec-as-source. The spec is the only thing humans author. Code is fully derived output, closer to how Terraform generates infrastructure from HCL. Tessl Framework is the most public example.

Most teams don’t need level three. Moving from unstructured prompting to spec-first captures most of the reliability gain.

A Spec-Driven PRD You Can Copy

The four phases are easier to trust once you see the artifact they revolve around. Here is a complete one-page spec for a real, security-sensitive feature: organization-scoped API keys. Copy it, swap the stack names and routes for your own, and hand it to the agent before you ask for any code.

# Spec: Organization API Keys

## Goals
- An org owner can mint, name, and revoke API keys for their organization.
- Each key authenticates requests to /api/v1/* and is scoped to one organizationId.
- The full key value is shown exactly once, at creation; only a hash is stored.

## Non-Goals
- No per-key permission scopes in v1 (a key inherits the owner's role).
- No expiry or rotation reminders. Revoke is manual.
- No usage-analytics dashboard (tracked as a separate spec).

## Constraints
- Stack: Next.js App Router, PostgreSQL + Prisma, Clerk for the owner session.
- Every query MUST filter on organizationId. No cross-org reads, ever.
- Keys are hashed with SHA-256. The raw key is never logged or persisted.
- Only the `owner` role may create or revoke keys (server-side RBAC check).

## Acceptance Criteria
- [ ] POST /api/keys returns the plaintext key once and stores only its hash.
- [ ] GET /api/keys lists name, prefix, and created date, never the secret.
- [ ] A revoked key returns 401 on its next request.
- [ ] A non-owner calling either route receives 403.
- [ ] A request signed with org A's key cannot read org B's data.

That spec is the contract. GitHub Spec Kit then walks it through four phases, run inside whichever agent you use (Claude Code, Cursor, Copilot, Gemini CLI):

Constitution   # project-wide invariants: stack, conventions, guardrails
Specify        # the feature spec above: goals, non-goals, constraints, criteria
Plan           # the agent drafts architecture + a task breakdown; you review
Tasks          # code is written task-by-task, each tied to one acceptance line

Spec Kit exposes these as slash commands inside your agent (the exact command names vary by version); the order is fixed: set the invariants once, specify the feature, review the plan, then generate code where every task traces back to a line you wrote. The same discipline keeps agentic features honest. When an AI agent can take real write-actions in your app, like inviting a member or changing a role, the spec defines which actions are in bounds and which need a human approval step. That approve-or-deny guardrail is exactly the kind of agentic write-action we ship in our AI agent starter kit.

Spec-Driven Development vs. Vibe Coding: Which to Use When

Spec-driven development doesn’t replace vibe coding; it constrains it. The two answer different questions at different points in the workflow.

The healthy version of the two is layered: vibe-code inside a well-written spec. The spec bounds what the AI is allowed to do; the prompt fills in the how. When the output drifts, you fix the spec, not the prompt. The clearest way to feel the difference is to build the same feature both ways.

The Same Feature, Both Ways: A Stripe Checkout

Start with the vibe path. You prompt, “add Stripe checkout so users can upgrade to Pro,” and the agent wires up a checkout session, a success redirect, and a webhook. The happy path works in the demo, so it looks finished. Then the gaps surface in production: the webhook trusts the incoming request without verifying the Stripe signature, the plan limit is checked in the UI but not on the server, a user who closes the tab mid-payment lands in a half-upgraded state, and downgrades were never handled because nobody asked for them. Each gap is another re-prompt, and each re-prompt risks rewriting the parts that already worked.

Now the spec path, same feature. You spend fifteen minutes on a half-page spec first. Goals: a logged-in user upgrades to Pro and the entitlement is live within seconds. Non-goals: proration, annual plans, and tax all stay in v2. Constraints: verify the webhook signature, enforce limits server-side, make the webhook idempotent. Acceptance criteria: a replayed webhook never double-grants, a failed payment leaves the plan unchanged, a downgrade revokes Pro features at period end. The agent builds against that list, so the edge cases that bite in week three are in scope from the first prompt. Same model, same agent, same feature. The only difference is whether the failure modes were named before the code was written or discovered after a customer hit one.

When to Use Which: The Decision Rule

So which do you reach for? Use vibe coding when the cost of being wrong is a page refresh: a landing section, a chart, an internal dashboard, a throwaway prototype. Reach for a spec the moment a feature touches money, auth, or shared data, where “almost right” means a security hole or a corrupted record. A fast test: if you’d want a code review before this shipped, write a spec before it’s built. The two aren’t rivals. You vibe-code the upgrade screen with whichever AI coding tool you prefer, inside the spec that locks down the billing logic underneath it.

Context Engineering — The Layer Below Specs

A spec says what to build. Context engineering decides what the AI already knows when it reads that spec. The two sit one on top of the other: the spec is the contract for a single feature, and context is everything the agent loads before it starts work, like your file conventions, the existing data model, and the helper functions it should reuse instead of reinventing.

Skip the context layer and even a flawless spec produces code that ignores your patterns: a second auth helper next to the one you already have, a query that bypasses your tenant scoping, a component that re-implements a hook already in your library. The spec told the agent what to build; nothing told it what already exists. So in practice the two work as a pair. Context (an AGENTS.md, scoped rules, and feature READMEs) keeps the agent inside your codebase’s conventions, and the spec keeps it inside the boundaries of the feature. Read the full guide to context engineering →

The Tools Shipping Spec-Driven Workflows

Three tools define the current state of spec-driven development. Each takes a different position on the Boeckeler maturity ladder.

• GitHub Spec Kit. Open source, MIT-licensed, roughly 90,000 stars as of April 2026. Supports Claude Code, Copilot, Cursor CLI, Gemini CLI, Codex CLI, Qwen, opencode, and more. Lives at the spec-anchored level: specs and code evolve together through the Constitution/Specify/Plan/Tasks flow.
• Amazon Kiro. Commercial AWS offering, same spec-anchored tier. Kiro emphasizes tight AWS integration and specification reuse across services.
• Tessl Framework. Commercial, the most aggressive of the three. Pushes toward spec-as-source: humans author specs, everything else is generated. Thoughtworks’ Technology Radar flagged all three by name when it placed spec-driven development in its “Assess” ring in November 2025 (Thoughtworks Radar Vol. 33).

The tools handle generation. They don’t handle enforcement. That’s where harness engineering picks up — the tests, type checks, and quality gates that verify the generated code actually matches the spec. Specs and harnesses are complements: the spec is what you wanted, the harness proves you got it.

When Spec-Driven Development Backfires

Spec-driven development has a credible set of critics. Ignoring them produces the exact overhead they warn about.

François Zaninotto at Marmelab documented the most concrete example in November 2025: a single feature to display the current date required 8 files and roughly 1,300 lines of specification using Spec Kit (Marmelab, November 12, 2025). His argument is that SDD is a rebranded waterfall optimized for removing developers from the loop.

SDD is a step in the wrong direction. It tries to solve a faulty challenge: “How do we remove developers from software development?” — François Zaninotto, Marmelab

Thoughtworks’ Technology Radar was more measured but still cautious, placing SDD in “Assess” rather than “Trial” or “Adopt” and warning the workflows are “elaborate and opinionated” and may represent “a bitter lesson — that handcrafting detailed rules for AI ultimately doesn’t scale.” Boeckeler, a qualified supporter, has flagged the same failure modes: review overload for small features and non-deterministic LLM output undermining the promised control.

The practical heuristic: spec-driven development is overhead for anything simpler than a feature spec. Use it where the cost of architectural drift is high (auth, billing, multi-tenant data, API contracts) and skip it where the cost of being wrong is a page refresh.

How to Start Without Rewriting Everything

You don’t need Spec Kit, a Constitution document, or a four-phase workflow to practice spec-driven development. You need a one-page spec and the discipline to hand it to the AI before you prompt.

1. Write a one-page PRD before prompting. Goals, non-goals, constraints, acceptance criteria. Fifteen minutes. This single step is the biggest reliability gain most teams will see, and it costs nothing.
2. Use AGENTS.md as your Constitution. Stack choices, conventions, architectural rules, forbidden patterns. Next.js 16.2 now ships AGENTS.md in create-next-app by default; we walk through a full AGENTS.md-first workflow in our step-by-step tutorial.
3. Treat the spec as the diff target. When the AI produces something wrong, revise the spec first, then regenerate the code. Don’t re-prompt your way around a spec gap — that’s the vibe-coding failure mode.
4. Pair the spec with a harness. Specs without automated tests and type checks drift silently. The spec says what you want; the harness proves the code matches. See harness engineering for the enforcement layer.
5. Graduate to Spec Kit when the overhead earns itself. Once you have a handful of features that share a Constitution, formalizing with Spec Kit or Kiro starts paying back. Before that, a directory of markdown specs works fine.

The point of spec-driven development isn’t specs. It’s getting AI to build the thing you actually wanted, the first time, at the architectural level your future self will have to maintain. A one-page PRD beats a four-hour debugging session. Every time.

Frequently Asked Questions

Have more questions? See our full FAQ →