Spec-driven development: the specification first, then the code
Writing the specification before the AI generates code and using it as the source of truth. Its phases in Spec Kit, what it contains and when not to use it.
What problem does it try to solve?
Vibe coding, where you describe an idea loosely and accept the result, has a drift problem. In each session the AI can make new decisions: rename something, invent an architecture or forget a rule from the previous session. Without a document that fixes them, nobody knows what was decided or why.
The specification works as a contract. If the rule “a client only sees their own appointments” is written down, every later change can be checked against it. Fernando Ruiz frames it this way in his blog post: the specification is the contract that a chat interface cannot give you on its own (Spec-Driven Development, on the blog).
The term still has no settled definition. Birgitta Böckeler, of Thoughtworks, sums it up on martinfowler.com as writing a specification before writing code with AI, and she distinguishes three levels of commitment:
- Spec-first: the specification is written first and used for the task at hand.
- Spec-anchored: it is kept after the task is done, to evolve and maintain the feature.
- Spec-as-source: the specification is the main file and people only edit that, never the code.
According to her analysis, all the tools she looked at are spec-first; not all of them aim for the other two levels.
What are the phases?
GitHub published Spec Kit, an open-source toolkit under the MIT license, and presented it on its blog on September 2, 2025. Its flow has four phases. According to GitHub, with AI the specification becomes the source of truth and determines what gets built (GitHub Blog, Spec Kit).
| Phase | What it produces | What a person reviews |
|---|---|---|
| Specify | A document with users, problems, journeys and success criteria | That it describes the what and the why, without technology |
| Plan | A technical plan with stack, architecture and constraints | That it follows the team’s standards |
| Tasks | A list of small items that can be tested | That they can be cut or reordered before coding |
| Implement | The code, task by task | Each change, instead of a huge code dump |
Spec Kit adds a “constitution”: general project principles, such as code quality or testing, that apply to every change. Böckeler warns that the AI interprets the files and checklists it generates, so there is no guarantee it follows them.
Other tools follow a similar logic. Kiro, for example, works with three Markdown documents per feature: requirements.md (user stories and acceptance criteria), design.md (technical architecture) and tasks.md (tasks with tracking) (Kiro, specs documentation).
What should the specification contain?
According to GitHub, the specification covers the user side: who will use the product, what problem it solves, how they interact with it and which outcomes matter. It is not about technical stacks or the app’s design: technical decisions go in the plan. For a designer this is an advantage, since they already think in states, flows and rules. A useful specification answers five questions:
- Who uses the product?
- What problem does it solve, and by when?
- What are the main journeys, step by step?
- Which rules must never be broken?
- How do we know it works?
The fifth is the one most often skipped. A criterion such as “the user gets confirmation in under two seconds” can be tested; “it should be fast” cannot. To turn this into a product document, see how to write a PRD an agent can understand.
How is it used in practice?
A guide from Augment Code describes the Spec Kit flow with concrete commands and files. There are human checkpoints between stages: the person edits the specification before the plan is generated, adjusts architecture and contracts in the plan, cuts or reorders the tasks and reviews each task’s change. There is an optional consistency analysis, which runs after the tasks, to look for gaps between specification, plan and tasks (Augment Code, Spec Kit guide). Augment sells a competing platform, so read its comparisons with caution.
The same guide points out limits. In an existing project you need to write the constitution before the first specification; otherwise you get generic templates that ignore the real architecture. And a task file with hundreds of entries becomes hard to edit. Its suggestion is to cut features until the task file fits in a single implementation pass.
When is it NOT worth it?
The method has a cost. Böckeler says that using the full flow on a small bug felt like using a sledgehammer to crack a nut. She also says she would rather review code than so many Markdown files, which often repeated each other and the existing code. She saw the agent fail to follow all the instructions and saw results vary when she generated code several times from the same specification. And she is skeptical of a lot of up-front design.
The practical conclusion is proportional: an afternoon script or a demo for a meeting does not need four documents. The more people, the longer the lifespan and the more changes you expect, the more sense it makes to specify. If you are unsure, compare with when not to vibe code and vibe coding vs. AI-assisted engineering.
Example
Illustrative example: a design team builds a vacation request form. The one-page specification says who approves, what happens if the manager does not reply within five days and which states a request can have (draft, sent, approved, rejected). When planning, the AI proposes a database; the team reviews it and changes the storage because they already have one. Tasks are split into “create request”, “approve” and “notify”. When the manager asks for a rule change, the specification is updated first and the plan is regenerated, without rewriting all the code.
How do you apply it tomorrow?
- Take one feature you plan to ask for this week and write its specification on one page, using the five questions above.
- Review the plan the AI proposes before splitting it into tasks. Cut what is not needed and note which decisions you changed and why.
- Run one task at a time and check the result against the specification’s success criterion, not against your impression. If the change is large, use a branch and a pull request.
- When a rule changes, edit the specification first and then regenerate the plan. If the specification and the code disagree, the document is out of date and needs fixing.
With a small project you can check whether the method saves you time or only adds steps. For reviewing each result, see iterating with prompts without losing control.
Common mistakes
- Writing the specification with technical details instead of behavior.
- Approving the plan without reading it, just to get to the code.
- Vague success criteria such as “it should be intuitive”.
- Not updating the specification when a rule changes, so the document becomes fiction.
- Using the method for an afternoon script.
- Letting the AI write the specification without a product person reviewing it.
- Assuming the agent did everything that was written without checking.
Sources
- GitHub Blog, “Spec-driven development with AI: Get started with a new open source toolkit”
- Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, martinfowler.com
- Kiro, specs documentation
- Augment Code, “GitHub Spec Kit: A Practical Guide to the SDD Workflow”
- Fernando Ruiz, “Spec-Driven Development: The End of Amateur Vibe Coding” (fernandoux.com blog)