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 seven phases, gates and all. Don't run the same checklist for both.
Keep the constitution file short and opinionated. It should be the rules you actually enforce day to day, not an aspirational wishlist nobody reads past the first week.
Never skip the human review gates. Everything else in this workflow is process around that one mechanism, and it's the actual safety net. This is also where wiring your agent workflow correctly matters more than people expect: if the gate is a Slack notification nobody reads until the next morning, you've built the workflow but skipped the safety mechanism it exists to provide.
Write acceptance criteria in EARS style specifically at the clarify and plan phases. That's where it earns the most, because it forces ambiguity to surface before the agent starts generating code instead of after you're already reviewing a pull request you don't fully understand.
Where this leaves you
Spec driven development is a real fix for a real problem: agents drifting on vague prompts and shipping scope nobody asked for. It's not a fad, and it's not going away. But it's also not a substitute for judgment about when process is worth the cost. The teams getting the most out of this treat the seven phases as a dial they turn up or down based on risk, not a checklist they run unconditionally on every ticket.
If you're setting this up for a team and want a second pair of eyes on the constitution file or the gate design before it calcifies into ceremony, that's exactly the kind of work I take on.
Drop a comment if your team's setup looks different, curious what variations people are actually running in production.
Top comments (0)