{"slug": "spec-driven-development-what-it-fixes-and-breaks", "title": "Spec Driven Development: What It Fixes (and Breaks)", "summary": "Spec driven development, a workflow that makes the specification the source of truth for AI coding agents, is gaining traction but risks becoming waterfall with a chatbot, according to a developer's analysis. The practice, which uses a seven-phase pipeline with human review gates, is placed in the Assess ring of Thoughtworks' Technology Radar, signaling caution due to potential documentation overhead. Tools like GitHub Spec Kit and AWS Kiro are emerging to support this approach.", "body_md": "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.\n\nSpec 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.\n\nHere's roughly what each phase is doing:\n\nA 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:\n\n```\nGiven a user has attempted to log in 5 times within 1 minute\nWhen the user attempts to log in again\nThen the system shall block the login attempt and return a rate limit error\n```\n\nThat's the whole trick. An agent can't argue with that sentence the way it can argue with \"add some rate limiting.\"\n\nDiagram: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.\n\n[GitHub Spec Kit](https://github.com/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.\n\nAWS 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.\n\nAnd 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.\n\nHere'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.\n\nHere'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.\n\nThe 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.\n\nScale 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.\n\nKeep 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.\n\nNever 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](https://mudassirkhan.me/blog/ai-agent-workflow-automation) 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.\n\nWrite 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.\n\nSpec 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.\n\nIf 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](https://mudassirkhan.me/services/agentic-ai-consulting).\n\n*Drop a comment if your team's setup looks different, curious what variations people are actually running in production.*", "url": "https://wpnews.pro/news/spec-driven-development-what-it-fixes-and-breaks", "canonical_source": "https://dev.to/mudassirworks/spec-driven-development-what-it-fixes-and-breaks-1co3", "published_at": "2026-08-10 20:40:38+00:00", "updated_at": "2026-08-10 20:47:01.430046+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-products", "ai-ethics"], "entities": ["GitHub Spec Kit", "AWS Kiro", "Thoughtworks", "Technology Radar"], "alternates": {"html": "https://wpnews.pro/news/spec-driven-development-what-it-fixes-and-breaks", "markdown": "https://wpnews.pro/news/spec-driven-development-what-it-fixes-and-breaks.md", "text": "https://wpnews.pro/news/spec-driven-development-what-it-fixes-and-breaks.txt", "jsonld": "https://wpnews.pro/news/spec-driven-development-what-it-fixes-and-breaks.jsonld"}}