What is Spec-Driven Development? The New Way to Code With AI

Introduction

AI coding agents follow the words in front of them and fill every gap with a guess. A written specification closes those gaps before any code exists. This guide explains the workflow that tools like GitHub Spec Kit and Kiro follow, what a usable spec contains, and where the approach fails. It also covers what most tutorials skip: how to size the effort to the change, and how to tell whether a source means a throwaway spec or a maintained one.

Quick answer

Spec-driven development (SDD) is a way of building software with AI coding agents in which a written specification of what the software must do is agreed and reviewed first, then broken into tasks the agent implements. The spec, not the chat history, is the shared source of intent that humans review and the agent follows.

Key takeaways

A written spec moves guessing out of the code and into a document, because an AI agent fills every unstated requirement with an assumption and a document is the cheapest place to correct one.

SDD has no single definition, so check which level a source means (throwaway spec, maintained spec, or spec as the only edited file), because the results and risks differ sharply between them.

The usual loop is specify, plan, split into tasks, implement and validate, with a human review before each handoff, because the review gates are where wrong assumptions get caught early.

The full lifecycle is overkill for small changes, since a Thoughtworks reviewer watched a minor bug fix balloon into a long requirements document, so match the amount of spec to the size and risk of the change.

A spec reduces drift and ignored instructions but cannot remove them, because AI output is non-deterministic, so tests and a CI pipeline remain the real safety net.

You can start with plain markdown files in your repository, because the process matters more than the product, and Spec Kit, Kiro and OpenSpec mainly automate it.

Why do AI coding agents need a written spec?

AI coding agents need a written spec because a short prompt leaves most requirements unstated, and the model fills each gap with the most likely answer from its training data. Some of those guesses are wrong, and teams often notice late. A spec makes each decision explicit, reviewable and reusable across agent sessions.

GitHub’s announcement of Spec Kit compares a coding agent to a pair programmer who follows instructions to the letter: excellent at completing patterns, unable to read your mind. The opposite habit is vibe coding, a loose prompt-and-accept loop popularised by Andrej Karpathy. It works for prototypes and throwaway scripts, and it struggles once several people, several sessions or an existing codebase are involved, because the reasoning behind each change lives only in a chat log.

IBM’s explainer on technical debt in AI-assisted development names the symptoms that a spec is meant to prevent.

1. Context drift: a fix in one area quietly breaks another, because the agent never saw the whole system.
2. Fragmentation: new features ignore the architecture conventions already in the codebase.
3. Forgotten basics: edge cases, tests and security checks are skipped when the prompt never mentioned them.
4. Reviewer guesswork: reviewers rebuild the intent from the diff because nothing records it.
5. Long prompting loops: developers spend many rounds correcting errors a clear spec would have prevented.

Each symptom traces back to intent that was never written down, which is the gap SDD fills.

How does spec driven development work?

The workflow runs as a loop of small, reviewable stages: write the specification, plan the technical approach, split the plan into tasks, let the agent implement them one at a time, then validate the result against the spec. A human reviews the output of every stage before the next one begins.

Tools differ on the number and names of stages. Kiro’s documentation describes requirements, design and tasks. GitHub’s original Spec Kit announcement described specify, plan, tasks and implement. Microsoft’s developer blog lists seven stages by adding a constitution, a clarify step and a validate step.

These are the stages most workflows share, in the order they usually run.

1. Set ground rules. Write the project-wide principles the agent must always respect, such as testing standards or security rules. Spec Kit calls this file a constitution.
2. Specify. Describe what to build and why, focusing on users and outcomes rather than the technology stack.
3. Clarify. Have the agent list ambiguities and answer them before planning, so the plan does not rest on guesses.
4. Plan. Add the technical decisions: stack, architecture, constraints and the existing systems to integrate with.
5. Split into tasks. Break the plan into small units, each one something the agent can build and test in isolation.
6. Implement and validate. The agent works through the tasks while you review focused changes and check them against the acceptance criteria.

Separating the what (the spec) from the how (the plan) is the load-bearing idea, because it lets you change the technical approach without rewriting the requirements.

In every version the human role shifts from typing code to verifying artifacts. GitHub’s announcement says the developer must verify as well as steer, with a review at the end of each stage.

What does a good spec contain?

A good spec states what the software must do, for whom, and how you will know it works, while leaving unimportant choices to the agent. At minimum it holds the goal, the users, the required behaviour, the constraints, the edge cases, what is out of scope, and testable acceptance criteria.

These seven elements cover what an agent would otherwise invent.

1. Goal: what the user can do once the feature ships, and why it matters.
2. Users and roles: who uses the feature and who must be kept out of it.
3. Behaviour: the required actions, inputs and outputs, written as observable behaviour rather than code.
4. Constraints: existing stack decisions, security rules, performance expectations and the API contracts the feature depends on (background in how APIs work).
5. Edge cases and failure states: malformed input, timeouts, permission failures and cancelled actions.
6. Out of scope: features the agent must not add, because it will otherwise add whatever similar systems usually include.
7. Acceptance criteria: checks that a reviewer or an automated test can pass or fail.

If a requirement cannot be checked by a test or a reviewer, rewrite it until it can.

This illustrative fragment for a hypothetical invoice export feature shows how each element becomes a line the agent can act on.

FEATURE: Invoice export

GOAL: Finance users can download their account invoices as a CSV file.

USERS: Users with the Finance role. Other roles must not see the export button.

BEHAVIOUR: Choosing Export downloads a CSV of the invoices in the current filter.

EDGE CASES: An empty result downloads a file with headers only. A failed export shows an error and keeps the filter.

OUT OF SCOPE: PDF export, scheduled exports, email delivery.

ACCEPTANCE: A Finance user sees the button and a non-Finance user does not. Downloaded rows match the filtered table.

Every line removes a guess. Without the out-of-scope line an agent may add PDF export because similar tools offer it, and without the role rule it may show the button to everyone.

How much detail is enough?

Match detail to risk. Allegro’s engineering blog suggests a local throwaway script needs only a light spec, while a financial service needs every important detail spelled out. IBM adds a stopping rule: the effort of refining the spec should stay below the cost of fixing the misunderstanding in code. Pro tip: ask the agent to review the spec several times, because Allegro reports that once its feedback shrinks to trivial nitpicks the spec is usually ready.

What are the levels of specification first programming?

Birgitta Böckeler’s analysis on martinfowler.com describes three levels of specification first programming: spec-first, where a spec guides one task and may then be discarded; spec-anchored, where the spec is kept and updated as the feature evolves; and spec-as-source, where humans edit only the spec and never the code.

Definitions disagree because the term covers different practices. Wikipedia’s entry describes a formal, machine-readable specification, while Böckeler and Thoughtworks describe natural-language, behaviour-oriented documents. Some vendor guides go further and require the build to fail when code diverges from the spec. Böckeler also notes that some people already use “spec” as a synonym for a detailed prompt. She reported that Tessl, still in private beta in September 2025, was the only one of her three tools aiming at spec-as-source, so check its current status before relying on that.

The safer default is spec-first for a single feature, because it costs little upkeep and captures most of the benefit. Spec-anchored earns its upkeep when a feature will change repeatedly or must be audited, ideally with automated tests tying spec and code together in CI. Spec-as-source asks you to trust a code generation pipeline that IBM and Thoughtworks both describe as non-deterministic, so the evidence supports waiting for most production systems. A practical rule: promote a spec to spec-anchored the second time the same feature needs a change.

How does SDD differ from vibe coding, TDD, BDD and rules files?

SDD differs from vibe coding in order of work (spec before code, not prompt and react), from test-driven development (TDD) and behaviour-driven development (BDD) in what comes first (intent and architecture rather than tests or scenarios), and from rules files such as AGENTS.md in lifespan (a spec covers one feature, a rules file covers every session).

The comparison uses three criteria: what each practice puts first, how long its main artifact lives, and where it is strong or weak. The rules-file row follows Böckeler’s distinction between project-wide context and feature specs.

Approach	Comes first	Lives for	Strong at	Weak at
Vibe coding	A loose prompt	One chat session	Prototypes, throwaway tools	Tracking intent across sessions
TDD	A failing unit test	The test suite	Unit-level correctness	Confirming the right thing is built
BDD	Behaviour scenarios	The scenario suite	Shared language with non-engineers	Architecture constraints
SDD	A reviewed spec and plan	One feature or longer	Reviewable intent for humans and agents	Overhead on small changes
Rules file	Project conventions	Every session	Teaching an agent your standards	Describing one feature

These practices combine rather than compete: acceptance criteria in a spec become TDD or BDD test cases, and a rules file carries the standards every spec inherits. Use vibe coding for disposable work and the combination for anything other people will maintain.

Which tools run an AI coding workflow around specs?

Four names come up most often: GitHub Spec Kit, Kiro, OpenSpec and Tessl, and you can also run the process with plain markdown files. Spec Kit and OpenSpec add the process to the coding agent you already use, Kiro builds it into its own environment, and Tessl explored specs as the maintained source.

The table summarises Spec Kit’s README, Kiro’s specs documentation (updated 2 October 2026), OpenSpec’s README and Böckeler’s analysis for Tessl; all were checked on 14 October 2026.

Tool	Main artifacts	How you work	Check first
Spec Kit	Spec, plan, tasks, constitution	Skills inside your agent	MIT licence; Python 3.11 or newer
Kiro	requirements.md, design.md, tasks.md	Kiro IDE, CLI and web	Its pricing page
OpenSpec	Proposal, specs, design, tasks	Slash commands in your agent	MIT licence; Node.js 20.19.0 or higher
Tessl	Spec files mapped to code files	CLI that doubles as an MCP server	Beta status in September 2025
Plain markdown	Product spec, technical spec, plan	Prompt your agent to follow it	Discipline is manual

The lower-risk order is plain markdown first, then Spec Kit or OpenSpec if the manual process works but feels repetitive, and Kiro if you want the whole workflow inside one environment.

What does it cost?

Cost depends on these factors rather than on a licence fee.

1. Your time: writing the spec and reading every generated artifact before the next stage.
2. Agent usage: each stage consumes model usage under your agent vendor’s pricing, which changes often, so check its pricing page and the currency it quotes, because local taxes vary by region.
3. Tool terms: Spec Kit and OpenSpec are open source under the MIT licence according to their repositories, while Kiro has its own subscription and billing documentation.
4. Upkeep: someone must update specs when code changes, or they drift.
5. Lock-in: opinionated file formats are harder to move between tools than plain markdown.
6. Data exposure: specs describe business logic, so check what each agent vendor does with repository content, a risk covered in shadow AI risks at work.

The cheapest way to learn your real cost is to run one feature through the process and note where the time went.

How do you run a first spec cycle with Spec Kit?

Install the Specify CLI, initialise a project, open your coding agent in that folder, and run the Spec Kit skills one at a time, reviewing each result before moving on. The CLI only sets up the project; the specify, plan and implement steps run inside your agent’s chat.

According to Spec Kit’s official README as read on 14 October 2026, you need Python 3.11 or newer, the uv package manager and a supported AI coding agent on Linux, macOS or Windows. These terminal commands install the CLI and create a project; replace copilot with the integration key for your own agent.

uv tool install specify-cli

specify init my-project –integration copilot

Then open your agent in the new folder and work through these steps.

1. Run /speckit-constitution once with your project rules. Expected result: a constitution that later steps are checked against.
2. Run /speckit-specify with the what and why, not the stack. Expected result: a feature spec.
3. Run /speckit-clarify and answer its questions. Expected result: your answers folded into the spec.
4. Run /speckit-plan with your stack and constraints. Expected result: design artifacts, including a plan.
5. Run /speckit-tasks. Expected result: a dependency-ordered task list.
6. Run /speckit-analyze. Expected result: a read-only report of conflicts, gaps and ambiguities across spec, plan and tasks; fix them at the source and rerun.
7. Run /speckit-implement. Expected result: the agent works through the tasks in order.
8. Run /speckit-converge. Expected result: new tasks appended if gaps remain; repeat implement and converge until it reports Converged.

For the invoice example, the first three arguments could look like this.

/speckit-constitution Require tests for every feature and never log personal data.

/speckit-specify Add CSV export of filtered invoices for the Finance role. PDF export is out of scope.

/speckit-plan Reuse the existing backend and authentication. Add one export endpoint.

Two failure points are worth knowing in advance.

1. Typing skills into the terminal: the README says these are agent skills, not terminal commands, so if your shell returns an error instead of a spec, move the command into the agent chat.
2. Wrong invocation syntax: the README says other agents may use different syntax, and tutorials written earlier show /specify or /speckit.specify, so if the agent does not recognise a skill, check the command invocation section of the Spec Kit integrations reference.

Spec Kit’s quickstart offers a shorter path for small features and a full path with extra quality gates for production work, so choose by risk.

When is spec driven development worth the effort?

It is worth the effort when a wrong interpretation costs more than writing the spec: multi-session work, several contributors, changes to an existing codebase, or audit requirements. For a small fix or a disposable prototype, a direct prompt is faster and just as safe.

Weigh these factors before writing a spec.

1. Cost of a wrong guess: the more expensive the rework, the more a spec saves.
2. Size of the change: Böckeler reported that Kiro turned one small bug fix into four user stories with sixteen acceptance criteria.
3. People and sessions: a shared spec keeps several contributors and agent sessions aligned.
4. Existing code: GitHub says writing a spec forces clarity on how a new feature touches the current system.
5. Compliance or audit: a versioned spec makes decisions traceable.
6. Clarity of the problem: exploratory work needs experiments first, and a spec written too early gets rewritten.
7. Review capacity: someone must read the generated markdown, and Böckeler said she would rather review code.
8. System risk: a financial service warrants more detail than a local script.

If most of these point the same way, the decision is easy; if they conflict, start with a short spec and grow it.

Right-sizing is what Microsoft’s developer blog recommends, noting that not every change needs the full lifecycle. It describes a brownfield team that captured a repeated onboarding pattern in parameterised specs and reports cutting onboarding for new asset types from two to three weeks to a few days; the figure is self-reported.

Where does SDD break down?

SDD breaks down when the agent ignores or misreads the spec, when specs go stale, and when reviewing generated markdown costs more than reviewing code. Specs reduce these problems but cannot remove them, because AI output is non-deterministic.

These failure modes come from hands-on trials and practitioner reports.

1. Ignored or over-applied instructions: Böckeler saw agents skip parts of the instructions and also follow a constitution rule too eagerly.
2. Duplicate code: in her Spec Kit trial the agent treated notes about existing classes as a new spec and generated them again.
3. Spec drift: once code changes and nobody updates the spec, it misleads agents and reviewers.
4. Review overload: she found the many generated markdown files repetitive and verbose.
5. Blurred boundaries: Böckeler and Thoughtworks both say the line between functional and technical detail is hard to hold.
6. Non-determinism: Thoughtworks says deterministic checks, such as a CI/CD pipeline, are still needed to protect quality.

A spec does not make an AI agent obedient; it makes the agent’s misunderstanding visible before it becomes code.

The Thoughtworks Technology Radar entry placed the technique in its Assess ring in November 2025, advising teams to explore it while noting that the workflows were elaborate and opinionated and that some tools generate spec files that are hard to review.

Is it just waterfall again?

Not by design, but it can drift that way. Thoughtworks’ Liu Shangqi argues the difference is feedback speed: waterfall suffered long gaps between requirements and working software, while an agent can regenerate code from a changed spec in minutes. The risk he names is over-formalised specs that slow change, and Allegro’s engineers say the spec should be built iteratively, never in one shot.

Four mistakes that make it worse

Putting the technology stack into the first spec, which blurs the what and the how.

1. Running the full lifecycle for a one-line change.
2. Changing code without updating the spec.
3. Approving generated specs without reading them.

Avoiding these four removes most of the avoidable overhead.

Where to start

Treat the spec as the cheapest place to find out your request was ambiguous. Before adopting any tool, pick one upcoming feature that touches existing code and write a short spec with the goal, required behaviour, out-of-scope items and acceptance criteria. Whoever adopts spec driven development should have a second person read that spec before the agent does. Then judge your new AI coding workflow by one question: did the agent make fewer wrong guesses than in your last prompt-only attempt?

Frequently asked questions

1. Who should write the spec?

Ideally a product person and an engineer together, with the agent drafting. Allegro’s engineers advise against a single author because product, engineering and design each see different gaps, and Microsoft’s developer blog describes product managers defining scenarios while architects shape the plan. Whoever approves the spec stays accountable for what ships.

2. How long should a spec be?

As short as the risk allows. A short spec with goal, behaviour, out-of-scope items and acceptance criteria suits a typical feature, and IBM warns that a spec more detailed than needed stops helping. Allegro suggests one spec per feature for medium and large or existing projects, because smaller files fit the context window and stay maintainable.

3. Can I use it on an existing codebase?

Yes. GitHub names feature work in existing systems as where the approach pays off most, because the spec forces clarity about how the feature touches current code. Böckeler found two of the three tools she tried harder to introduce into an existing codebase, so start with one feature rather than the whole repository.

4. Can I do it without Spec Kit or Kiro?

Yes. Allegro’s engineers suggest a raw session first: tell the agent which documents to maintain, such as a product spec, a technical spec and an execution plan, and which stages to follow. Tools automate that structure; they do not create the discipline of reviewing each stage before moving on.

5. Does a spec replace tests?

No. Acceptance criteria in the spec should become tests, and the tests remain the check that code matches the spec. Thoughtworks’ Liu Shangqi stresses that spec drift and hallucination are hard to avoid, so deterministic pipelines still protect quality. Treat the spec as the source of test cases, not a substitute for running them.