Spec-driven development: what it is and how to write a spec an AI team can build from
Spec-driven development is what happened when teams noticed that AI agents are excellent at writing code and terrible at guessing what you meant. In spec-driven development a short, versioned specification is the source of truth, and the code is generated from it by AI agents that senior engineers direct and review. Change the product, change the spec first, regenerate what it touches. It is the reason an AI-first team can ship the same scope 3 times cheaper and 3 times faster than hand-written development: the arguing happens on one page before the build, not across four months of rewrites.
We have run every project this way since we moved to an AI pipeline, so the advice below is what we ask clients for, not a summary of a tool's README.
What spec-driven development is (and what it is not)
The definition that holds up: the spec declares intent, the code realizes it. Everything else is degree. The community distinguishes three levels:
- Spec-first. A spec seeds the first generation, then the code drifts and the document is forgotten. Cheap, and worth little after week two.
- Spec-anchored. Spec and code evolve together, and automated tests prove the code still does what the spec says. This is where production systems should sit, and where we sit.
- Spec-as-source. Humans edit only the spec and never touch generated code. Real for emulators and ports, not yet for products that meet customers.
It is not a return to 80-page requirements documents. A buildable spec for an MVP is two to five pages, lives in the repository, and is edited more often than the README. It is also not a tool. GitHub's Spec Kit shipped v1.0.0 on 21 August 2026 and crossed 132,000 stars the same month, AWS has Kiro, and Claude Code, Cursor and Codex all ship plan modes, but the tools only enforce a habit. Thoughtworks keeps spec-driven development in the Assess ring of its Technology Radar for that reason, and we think that is the right call: adopt the discipline, be agnostic about the tooling.
Why spec-driven development took off in 2026
Three numbers explain it. JetBrains found that 90% of professional developers used AI coding agents at work at least weekly in May to July 2026, and 68% used them daily. McKinsey reported that nearly a third of organisations had decided against buying at least one software product because they could build it internally with agents. And the vibe-coding wave of 2025 left behind a generation of apps that demo well and fail with real users, a subject we covered in how to make a vibe-coded app production ready.
Put those together: more software is being generated than ever, from prompts that were never precise enough to review against. The spec is the missing artifact. Early adopters report several times higher first-pass success from agents working from a spec instead of a chat thread; those are vendor numbers, but they match our own pipeline. An agent given a spec and a test to pass finishes. An agent given a paragraph guesses, or declares victory early.
The uncomfortable part is that the spec is a human document. Clients do not lie in discovery, but they describe the product they wish they had already built. The "MVP" has six integrations and a custom dashboard. The spec is where those get pushed until a few of them fall over.
How to write a spec an AI agent (or an agency) can build from
Seven parts, in this order. If a part is missing, the agent will fill it in with the most statistically likely answer, which is rarely your business.
- The one job. One sentence: who does what, and what changes for them. If it needs an "and", it is two products.
- Users and roles. Every role, and for each one what it can see and change. This is the section that prevents the most expensive class of bug, one user reading another's data. On Pulzio the rule was fixed before the schema existed: anonymity lives in the data model, not in the copy, so responses were stored without a link to the employee from day one, because that guarantee cannot be retrofitted.
- The core flow, then the unhappy paths. The happy path as numbered steps, then for each step what happens when it fails: the payment declines, the webhook arrives twice, the file is 400 MB. Vibe coding skips this section and production finds it for you.
- The data model in plain words. The entities, how they relate, and which fields must never be null. No SQL needed. On Sanction Finder the crucial requirement was that name matching can be neither string equality nor so loose that it floods the customer with false positives; that one sentence shaped the whole matching layer.
- Acceptance criteria an agent can test. Use the event shape: WHEN a user submits a booking for a slot that was taken in the meantime, THE system SHALL reject it and show the next three free slots. Each criterion becomes a test the agent must pass before the task counts as done.
- Non-goals. What is deliberately out of scope for this version, written down so nobody, human or agent, builds it helpfully.
- Definition of done. Tests green, a senior engineer reviewed the change, deployed to staging, monitored. An agent will report success on code that does not run; this is how you stop taking its word for it.
A spec with these seven parts fits on a few pages and takes a founder and a senior engineer three to five days, most of it on parts 2, 3 and 6.
Spec-driven development vs vibe coding vs a classic requirements document
| Vibe coding | Classic requirements document | Spec-driven development | |
|---|---|---|---|
| Source of truth | The chat history | A signed PDF | A versioned spec in the repo |
| Length | A paragraph | 40 to 120 pages | 2 to 10 pages |
| When it changes | Never, you just re-prompt | Through a change request | Before the code does |
| Who verifies | Nobody | QA, at the end | Tests derived from the acceptance criteria, on every change |
| Fails when | Real users arrive | Reality differs from the PDF | The spec is skipped "just this once" |
The middle column is why many founders flinch at the word "spec". The right column is a different thing: it is closer to a well-written ticket than to a contract.
What a written spec changes in cost and timeline
These are our numbers. They are low because the spec removes the hours that traditional projects spend rebuilding the wrong thing, and because AI generates the code while senior engineers direct and review it. Traditional hand-written development typically costs 3 times as much and takes 3 times as long on the same scope.
| Stage | Price | Timeline | What you get |
|---|---|---|---|
| Discovery and spec | $500-1,500 | 3-5 days | The seven-part spec, stress-tested with a senior engineer, credited against the build |
| Simple MVP built from the spec | $2,000-5,000 | 1-2 weeks | One core flow, basic auth, no heavy integrations |
| Medium MVP built from the spec | $5,000-12,000 | 2-4 weeks | Payments or a key integration, roles, a light admin panel |
| Spec update for a new feature | $200-600 | 1-2 days | The spec revised, affected code regenerated and re-tested |
The full ranges by tier are in our MVP development cost breakdown. The line that matters here is the last one: with a spec in the repository, a change is a one-page edit and a regeneration, not a renegotiation.
How we do spec-driven development at DForce
We treat the first days of a project as a stress test, not a honeymoon. We push on the must-haves until a few fall over, ask what ships if the dashboard does not, and ask who the actual user is, because the founder has often not spoken to one in months. The output is the spec, and it is the first thing we deliver.
From there the AI pipeline generates code against the spec, task by task, and senior engineers own what is expensive to get wrong: the architecture, the data model, authorization, payments and anything that touches production data. Every acceptance criterion is a test the agent has to pass, because the best thing we ever did for the speed of our agents was to stop believing them. The spec is updated with every feature, so the next engineer, human or agent, reads one current document instead of a year of chat logs.
Frequently asked questions
What is spec-driven development? Spec-driven development (SDD) is a way of building software where a written, versioned specification is the source of truth and the code is generated from it, usually by AI coding agents directed by engineers. The spec describes users and roles, the core flow and its unhappy paths, the data model, acceptance criteria and non-goals. When requirements change, the spec changes first and the affected code is regenerated. It became mainstream in 2026 as the fix for vibe coding, where agents produced plausible code that drifted from what the product needed.
Is spec-driven development just waterfall with AI? No. A waterfall spec was a document written once, signed off and then ignored while the code diverged from it. In spec-driven development the spec is short, lives in the repository next to the code, and is edited every time the product changes, so it never goes stale. It is also much cheaper to be wrong: a wrong spec costs a day and a regeneration, not a quarter of hand-written code. Thoughtworks still lists SDD under Assess rather than Adopt, which is fair: the discipline matters more than the tooling.
Do I need to write a spec before hiring a development team? You need to know the answers, not to write the document. A good team writes the spec with you in discovery and treats it as the first deliverable: who the users are, what the one job of the product is, what happens when things fail, and what is deliberately out of scope. Arriving with a feature list is fine. Arriving with a signed feature list nobody has stress-tested is how projects lose a month in week four.
How long does a spec take and what does it cost? With an AI-first team, discovery plus a written spec takes 3 to 5 days and costs $500 to $1,500, credited against the build. The build itself then runs about 3 times cheaper and 3 times faster than traditional hand-written development, because the AI pipeline generates code against a spec the engineers have already argued over, so far fewer hours go into rework. A simple MVP built from a spec is $2,000 to $5,000 in 1 to 2 weeks.
If you have a product idea and a feature list you suspect is a wish list, book a discovery call and we will turn it into a seven-part spec in a week, with a fixed price and a date attached to it.
What we do about this
Let's talk about your product and growth goals.
Keep reading
How to make a vibe-coded app production ready (and what it costs to fix)
Your Lovable, Bolt or Cursor app works in the demo and breaks with real users. Here is why vibe-coded apps fail in production, the checklist an AI-built app has to pass before launch, the difference between vibe coding and agentic engineering, and what a production pass costs with a team that builds with AI every day.
How much does it cost to build a SaaS product in 2026?
SaaS development cost is not the cost of an app plus a Stripe button. Subscription billing, workspaces and roles, onboarding and the monthly bill after launch all move the number. Here is what each part costs, what the first version should contain, and how AI-first teams build the same product 3 times cheaper.