Ways of having AI write code are rapidly diverging.
On one side is vibe coding: building things improvisationally through conversation. On the other is this article’s subject, Spec Driven Development (SDD).
In one sentence: SDD finalizes the specification in a document before asking for code.
That document becomes the single source of truth, guiding AI through planning, implementation, and verification.
This article explains how SDD works, its representative tools spec-kit and Kiro, and when to use it instead of vibe coding. Tool information is current as of August 2026.
Let’s start with the key takeaways.
- SDD first defines “what to build” in a spec document and treats code as its output.
- The flow has four stages: spec (requirements) → plan (technical design) → tasks (work breakdown) → implementation.
- GitHub’s spec-kit and AWS’s Kiro are leading tools that implement this flow.
- The general dividing line is vibe coding for prototypes and SDD for product code that must be maintained over time.
Why Specs Have Returned
The idea of writing documentation before development is not new. Waterfall-era requirements specifications did exactly that, but were pushed aside by Agile for being too heavyweight.
Then AI agents appeared and changed the situation. Human developers ask questions and fill in context even when requirements are ambiguous.
AI, by contrast, fills gaps with plausible guesses when given an ambiguous prompt. The result differs from the requirements yet looks fine—the most troublesome kind of defect.
That created the demand to “remove ambiguity before assigning work to AI,” bringing specifications back as the answer. The difference this time is that the document serves as AI’s execution standard, not merely something people read.
The Four-Stage Pipeline, from spec to tasks
The names vary slightly by tool, but the structure is the same.
| Stage | Output | What is finalized |
|---|---|---|
| Specify | spec.md | What to build and why (requirements · scenarios) |
| Plan | plan.md | How to build it (technology stack · architecture) |
| Tasks | tasks.md | What order to build it in (work-unit breakdown) |
| Implement | Code | Implement each task in order |
There are two core rules.
First, move to the next stage only after a person reviews and approves the previous output. This filters out ambiguity during documentation, before it reaches the code.
Second, if requirements change during implementation, update the spec—not the code—and rerun the stages below it. The spec must always be the latest truth.
Viewed from the opposite perspective: code is no longer the source, but the result of compiling the spec. The real source is the documentation.
Two Tools: spec-kit and Kiro
GitHub’s spec-kit is an open-source toolkit that is not tied to any particular agent.
It adds /specify, /plan, and /tasks slash commands on top of Claude Code, Copilot, Gemini CLI, and others, enforcing the pipeline above.
It also features a constitution document containing the project’s immutable principles.
AWS’s Kiro is an agentic IDE designed around SDD from the ground up. It creates three documents: requirements.md, design.md, and tasks.md.
Its strength is requirements notation. It structures requirements using EARS (Easy Approach to Requirements Syntax).
The approach expresses requirements as sentences like “The system shall ~ under ~ conditions.”
If you already use a general-purpose agent such as Claude Code, adding spec-kit has a lower adoption cost. If you want an integrated IDE experience, Kiro is the better fit.
Where SDD Differs from Vibe Coding
SDD is not always right. Creating and reviewing three documents has a real cost, so applying it to a weekend prototype or one-off script can make the process more expensive than the work itself.
The deciding factor is the code’s lifespan. If the code can be thrown away this week, iterate quickly with vibe coding.
If the code will be maintained and extended for several months or longer, removing ambiguity first with SDD lowers the total cost.
There is also one operational risk: drift, where the spec and code are left out of sync.
The moment the rule “requirement changes must start with the spec” breaks, the spec becomes a document nobody trusts. SDD then degenerates into a formality.
Summary
Ultimately, SDD claims that “the real programming language in the AI era is natural-language specifications.” It elevates intent communication from a single prompt line into a document that can be reviewed.
Before writing a prompt for your next feature, try writing one spec document first. You can decide within a day whether this methodology fits your work.