Spec Driven Development: What It Fixes (and Breaks)

AI coding agents are great, but they have a knack for drifting. Left alone, they reinterpret vague prompts, quietly expand scope, and ship code that technically works but nobody actually asked for. Spec driven development is the attempt to fix that by making the specification, not the prompt, the source of truth the agent has to work from. It works. Here's the catch: a lot of teams adopting it are just rebuilding waterfall with a chatbot bolted on. This post breaks down which parts of the seven phase workflow earn their keep and which parts are pure ceremony.

What spec driven development actually changes

Spec driven development shifts the source of truth from the prompt to the specification. The spec, not the agent's interpretation of your Slack message, becomes the authoritative document the agent has to work from.

In practice that means a seven phase pipeline: constitution, specify, clarify, plan, tasks, implement, analyze. Each phase has a human review gate between it and the next one, and that gate is the whole mechanism. It's what stops an agent from confidently running off with a bad interpretation for three hours before anyone notices.

Here's roughly what each phase is doing:

• Constitution: the standing rules for the project (conventions, constraints, things that are always true).
• Specify: the actual requirement, written in enough detail that two people would build the same thing from it.
• Clarify: turning anything vague into a testable, unambiguous acceptance criterion. This is where EARS notation earns its keep. You want to write something an agent literally cannot misread. I built the agent system prompt builder partly because watching agents misread plain English requirements over and over got old fast.
• Plan: breaking the specify plus clarify output into an actual sequence of work.
• Tasks: the individual units the agent (or you) will execute.
• Implement: the agent writes the code.
• Analyze: someone checks the output against the spec before it ships, not after. This is the phase most teams skip or rubber stamp, and it's exactly where good testing strategy actually pays for itself, because analyze is worthless if nobody is verifying against real behavior instead of eyeballing a diff.

A vague requirement like "users shouldn't be able to log in too often" becomes something like this once you clarify it into an EARS style acceptance criterion:

Given a user has attempted to log in 5 times within 1 minute
When the user attempts to log in again
Then the system shall block the login attempt and return a rate limit error

That's the whole trick. An agent can't argue with that sentence the way it can argue with "add some rate limiting."

Diagram: A horizontal flowchart showing the seven-phase Spec-Driven Development pipeline: constitution → specify → clarify → plan → tasks → implement → analyze, with a checkmark review gate between each phase.

The tooling landscape: Spec Kit vs Kiro vs nothing at all

GitHub Spec Kit is open source and MIT licensed, a CLI first toolkit that treats specifications as the actual executable source of truth for an agent. It's a good fit if your team wants to own the workflow and is already comfortable stitching CLI tools into whatever setup you're running.

AWS Kiro takes the opposite approach: it's a full agentic IDE built around spec driven development from the ground up, not a CLI you bolt on. Kiro reached international general availability on May 7, 2026, shipping with team plans, a CLI, and property based spec testing. It had already pulled in over 250,000 developers during its preview and more than 100,000 waitlist signups in roughly 90 days before that GA date, which tells you the demand for this workflow was real before the tooling caught up. Kiro is the better fit if you want the discipline enforced by the IDE itself rather than assembled from parts you have to maintain.

And then there's option three: no dedicated tooling at all, just a well written AGENTS.md or equivalent context file plus manual review discipline. This genuinely works for smaller projects. It just doesn't scale the enforcement Kiro or Spec Kit give you for free once more than two or three people are touching the same agent workflows.

Where this actually breaks down

Here's the part most writeups skip: Thoughtworks places spec driven development in the Assess ring of its Technology Radar, not Adopt. That's a "proceed with caution," not an endorsement.

The real criticism behind that placement is concrete: this practice can double documentation overhead on a project when every phase gets treated as mandatory ceremony instead of a tool you reach for when the task actually warrants it.

Here's the tell. If your team is writing exhaustive specs for a two hour task, running every phase gate on a one line CSS fix, and treating the human review step as a rubber stamp instead of an actual check, you're not doing spec driven development anymore. You're doing waterfall with an AI coding agent attached, and you've made your process slower without making it safer.

The phases are supposed to scale down for small tasks and scale up for genuinely risky or ambiguous ones. Teams that apply identical ceremony to everything are the ones who end up hating this workflow within a month, and honestly, they're right to hate it. That's a process problem, not a spec driven development problem.

How to run this without turning it into paperwork

Scale the phases to the actual risk of the task. A trivial change gets a one line spec and goes straight to implement. A genuinely ambiguous or high risk change gets the full