Spec-Driven Development: When Specifications Become Executable

Continuing from last week's post on PRP Framework, this week I'll deep-dive into the third planning framework: Spec-Driven Development (SDD). This is part of my weekly AI series where I take you progressively through AI fundamentals, and SDD represents the most structured approach to vibe-planning—where specifications aren't just documentation, they're executable blueprints. ## What is Spec-Driven Development? You may wonder, what exactly is SDD, or how is it different from BMAD and PRP? That is because SDD represents a fundamental paradigm shift in how we think about code: **From "code is the source of truth" to "intent is the source of truth."** In traditional development: Requirements → Design → Manual Coding → Testing. In spec-driven development: Requirements → Detailed Specification → AI Generation → Validation. The specification IS the source file. AI generates code from it. When requirements change, you update the spec—not the code. As ThoughtWorks describes it: "Architecture is no longer advisory; it is executable and enforceable." ## The Three Implementation Levels SDD isn't one-size-fits-all. There are three levels of adoption: ### Level 1: Spec-First Write a well-thought-out specification before coding. Use it in your AI-assisted workflow to generate code. This is the entry point. You still own the code, but you start with structure. ### Level 2: Spec-Anchored Keep the specification after implementation. Use it for evolution, maintenance, and onboarding. Six months from now, when you need to extend a feature, the spec tells you WHY decisions were made—not just WHAT was built. ### Level 3: Spec-as-Source The specification IS the main source file over time. Humans never touch the code directly. This is the endgame vision: you describe intent, AI materializes execution. ## Why SDD Matters You may wonder, why do specifications work better than prompts? That is because specifications provide what prompts lack: 1. **A North Star** — The spec guides AI agents through larger tasks without getting lost. It's a reference point they can validate against. 2. **Reduced Hallucinations** — Clear, semi-structured input significantly improves LLM reasoning performance. Ambiguity breeds hallucination. 3. **Tamed Chaos** — SDD "tames the chaos of prompt-driven vibe coding on large code bases." Structure scales; vibes don't. 4. **Institutional Memory** — The spec persists. New team members, new AI sessions, new models—all can reference the same source of truth. ## GitHub Spec-Kit: The Open-Source Toolkit GitHub released Spec-Kit to bring spec-driven development to any coding agent. It's already attracted 50k+ GitHub stars. ### The Four-Phase Workflow **Phase 1: Specify** Describe goals and user journeys. The agent drafts a detailed spec that evolves with your feedback. **Phase 2: Plan** Declare architecture, stack, and constraints. The agent proposes a technical plan. **Phase 3: Tasks** The agent breaks work into small, reviewable units. **Phase 4: Implement** The AI implements each task against the spec. ### Getting Started ```bash # Install the CLI uv tool install specify-cli --from git+https://github.com/github/spec-kit.git # Initialize with your preferred AI specify init my_project --ai claude # or --ai copilot, --ai gemini ``` Spec-Kit works with GitHub Copilot, Claude Code, and Gemini CLI. ### The Key Insight Instead of coding first and writing docs later, you start with a spec. This becomes the contract for how your code should behave—the source of truth your tools and AI agents use to generate, test, and validate code. ## Amazon Kiro: The Spec-Driven IDE Amazon released Kiro in July 2025—a VS Code fork built specifically for spec-driven development. ### How Kiro Works You describe requirements in natural language. Kiro outputs: 1. **User Stories** — With detailed acceptance criteria in EARS notation 2. **Technical Design** — Architecture diagrams and schemas 3. **Implementation Tasks** — A sequence of trackable coding tasks ### Kiro Hooks This is Kiro's secret weapon: event-driven automations that trigger agents in the background. When you save, create, or delete files, hooks can: - Run linting and formatting - Update related documentation - Validate against the spec - Complete boilerplate tasks As one developer noted: "Spec-driven development stopped her from going in circles with vibe coding." ### Real-World Results Delta Airlines achieved 1,948% growth in Q Developer adoption within six months using spec-driven approaches. Business product owners without coding experience generated production-ready prototypes. ### Model Selection Kiro offers Claude Sonnet 4.5 for advanced reasoning or Auto mode (mix of frontier models balanced for quality, latency, and cost). Free access during public preview. ## The Waterfall Criticism You may wonder, isn't this just Waterfall 2.0? That is because critics argue SDD "revives the old idea of heavy documentation before coding—an echo of the Waterfall era." The concern is valid. SDD can bury agility under layers of Markdown if misapplied. ### My Take The difference is execution speed. In Waterfall, you wrote specs, waited months, then developers built (often incorrectly). In SDD, you write specs, AI generates immediately, you validate in minutes. The feedback loop is hours, not months. SDD isn't anti-agile—it's structured agility. You iterate on specs, not code. The spec is living documentation, not a static artifact. ## SDD vs. BMAD vs. PRP How do all three frameworks compare? | Aspect | BMAD | PRP | SDD | |--------|------|-----|-----| | **Philosophy** | Comprehensive structure | Minimum viable context | Spec is source of truth | | **Agents** | 21 specialized personas | Single context-aware agent | Spec-guided agents | | **Documentation** | Extensive (PRD, architecture) | Focused (context packet) | Specification IS the artifact | | **Best For** | Enterprise systems from scratch | Features in existing codebase | Greenfield projects, clear requirements | | **Tooling** | IDE-agnostic | Claude Code, Cursor | Kiro, Spec-Kit | | **Learning Curve** | Steep | Gentle | Medium | | **Iteration** | Human oversight each phase | Ralph Loop self-corrects | Spec evolution | **Use BMAD when**: Building enterprise systems from scratch, multiple teams, long-term maintenance critical. **Use PRP when**: Adding features to existing codebase, need production-ready on first pass, working solo or small team. **Use SDD when**: Starting greenfield projects, requirements are clear, you want AI to own implementation entirely. ## The Convergence Here's what I find fascinating: all three frameworks are solving the same problem—vibe-coding collapse—from different angles. - **BMAD** says: "Structure your thinking with specialized agents." - **PRP** says: "Give AI the minimum context it needs." - **SDD** says: "Make specifications executable." They're not mutually exclusive. You could use BMAD's analysis phase to create requirements, format them as a PRP for context, then feed that into Spec-Kit for generation. The future is probably hybrid—picking the right tool for each phase. ## Getting Started with SDD **Option 1: GitHub Spec-Kit** ```bash uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify init my_project --ai claude ``` **Option 2: Amazon Kiro** Download from [kiro.dev](https://kiro.dev/). Free during public preview. **Option 3: Manual Spec-First** Even without tools, you can adopt spec-first thinking: 1. Write detailed requirements before prompting 2. Include acceptance criteria 3. Define validation commands 4. Reference the spec in every AI session ## What's Next Stay tuned!! In next week's post, I'll put it all together with a decision framework: BMAD vs PRP vs SDD—when to use which, and how to combine them. We'll explore real-world scenarios and create a practical guide for choosing the right planning approach. ## Key Takeaways - **SDD** = Specifications become executable blueprints for AI code generation - **The shift**: From "code is source of truth" to "intent is source of truth" - **Three levels**: Spec-first → Spec-anchored → Spec-as-source - **GitHub Spec-Kit**: Four phases (Specify → Plan → Tasks → Implement), 50k+ stars - **Amazon Kiro**: VS Code fork with natural language → user stories → design → tasks - **Benefits**: North Star for agents, reduced hallucinations, tamed vibe-coding chaos - **Criticism**: Waterfall concerns, but feedback loops are hours not months - **The convergence**: BMAD, PRP, SDD all solve vibe-coding collapse differently ## Additional Documents to Read on This - [ThoughtWorks on SDD](https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices) - Industry perspective on the methodology - [GitHub Spec-Kit Repository](https://github.com/github/spec-kit) - Official open-source toolkit - [GitHub Blog: Spec-Driven Development](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) - Getting started guide - [Amazon Kiro](https://kiro.dev/) - Spec-driven IDE - [Martin Fowler: SDD Tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) - Deep dive on Kiro, Spec-Kit, and Tessl - [InfoQ: When Architecture Becomes Executable](https://www.infoq.com/articles/spec-driven-development/) - Technical analysis --- *This is part of my weekly AI series taking you progressively from fundamentals to practical applications. Previous posts covered embeddings, vector databases, neural networks, prompting techniques, vibe coding dangers, vibe-planning, BMAD Method, and PRP Framework. Next week: BMAD vs PRP vs SDD Decision Framework.*