Spec-Driven Development: Where Intent Becomes the Source of Truth

Continuing from last week's post on PRP Framework, this week I'll deep-dive into the third planning framework transforming AI-assisted development: Spec-Driven Development (SDD). ThoughtWorks calls it "one of the most important practices to emerge in 2025"—and the industry is taking notice. This is part of my weekly AI series where I take you progressively through AI fundamentals, and SDD represents the most radical evolution in how we think about code itself. ## So What Is Spec-Driven Development? You may wonder, what exactly is SDD, or how is it different from the other planning approaches we've covered? That is because SDD asks a fundamental question: should code even be the source of truth anymore? As the ThoughtWorks Technology Radar describes it: "Spec-driven development is a development paradigm that uses well-crafted software requirement specifications as prompts, aided by AI coding agents, to generate executable code." In a nutshell, SDD inverts traditional development—specifications become executable, directly generating working implementations rather than just guiding them. ## The Philosophy Shift: From Code to Intent Here's the paradigm shift that makes SDD revolutionary: **Traditional Development:** - Specifications are scaffolding - Code is the source of truth - Specs get outdated and discarded - Maintaining software = maintaining code **Spec-Driven Development:** - Specifications become primary artifacts - Intent is the source of truth - Code is a "byproduct" of specifications - Maintaining software = evolving specifications As one practitioner describes it: "We're moving from 'code is the source of truth' to 'intent is the source of truth.'" This is a profound shift. For decades, developers have treated specifications as necessary paperwork—something you write to get approval, then largely ignore as you code. SDD treats specifications as the thing you maintain, with code regenerated as needed. ## The Key Principle: Think First Here's perhaps the most important insight from SDD: **"This step is important: you're not asking the AI agent to start coding yet. You're asking it to think first."** This sounds simple, but it's the opposite of vibe coding. In vibe coding, you describe what you want and AI immediately generates code. In SDD, you describe what you want and AI first generates a specification—a thinking step before implementation. Why does this matter? Because the specification becomes reviewable, testable, and maintainable. You can verify AI understood your intent before it writes a single line of code. ## The Ambitious Goal: 95%+ Accuracy SDD aims for something specific: **95% or higher accuracy implementing specs on the first try, with code that's error-free and unit tested.** This isn't marketing—it's a measurable target. SDD provides the structure that makes first-pass accuracy achievable: - Clear specifications reduce ambiguity - Given/When/Then scenarios define expected behavior - Validation commands verify implementation - Iterative refinement catches edge cases For comparison, Google has reported achieving over 75% of AI-generated character changes successfully landing in their monorepo. SDD targets even higher accuracy through specification precision. ## What Makes a Good Specification SDD inherits principles from Behavior-Driven Development (BDD) while adapting them for AI: ### 1. Domain-Oriented Language Use business language, not technical implementation details. **Bad**: "Create POST endpoint at /api/users that validates email regex and hashes password with bcrypt" **Good**: "Allow users to register with email and password, validating email format and securing credentials" The AI determines implementation; you define intent. ### 2. Given/When/Then Structure Structure scenarios clearly: ``` Given: User has all notification channels enabled When: Order status changes to 'shipped' Then: Email, SMS, and in-app notifications sent within 60 seconds ``` This format is unambiguous—AI knows exactly what behavior to implement. ### 3. Completeness with Conciseness Include everything necessary, nothing more: - Input/output mappings - Preconditions and postconditions - Constraints and edge cases - Interface types ### 4. Clarity and Determinism Reduce hallucinations through precision: - Avoid vague terms ("handle errors appropriately") - Specify exact behaviors ("return 400 status with error message") - Include semi-structured elements alongside natural language ## The Three Maturity Levels of SDD SDD exists on a spectrum. Where you fall depends on how radical a shift you're willing to make: ### Level 1: Spec-First **Definition**: Write a well-thought-out spec first, then use it in AI-assisted development. **What it means**: You still write and maintain code, but specs guide implementation. **Who uses this**: Teams transitioning from vibe coding, wanting more structure without full commitment. ### Level 2: Spec-Anchored **Definition**: Keep the spec even after the task is complete for evolution and maintenance. **What it means**: Specs become living documents. When you need to modify features, you update specs first, then regenerate code. **Who uses this**: Teams building maintainable AI-assisted systems. ### Level 3: Spec-as-Source **Definition**: The spec is the main source file. Only the spec is edited by humans—humans never touch the code directly. **What it means**: Code becomes truly disposable. You maintain intent; AI maintains implementation. **Who uses this**: Early adopters pushing the boundaries. This is controversial—some argue this "discards code as source of truth" entirely. ## The Tools: GitHub Spec-Kit, Amazon Kiro, and More SDD has exploded in tooling during 2025: ### GitHub Spec-Kit GitHub's open-source toolkit has attracted **50,000+ stars** in just months—a clear signal of industry interest. **The Workflow (Four Phases):** 1. **Specify**: Create high-level description focusing on user journeys 2. **Plan**: Generate technical architecture and constraints 3. **Tasks**: Break specs into small, testable chunks 4. **Implement**: AI agents execute tasks sequentially or in parallel **Installation:** ```bash uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> ``` **Key Commands:** - `/specify` – Generate detailed specifications - `/plan` – Create implementation plans - `/tasks` – Break work into actionable items **Philosophy:** "Spec Kit makes your specification the center of your engineering process. Instead of writing a spec and setting it aside, the spec drives the implementation." ### Amazon Kiro Amazon launched Kiro—a full VS Code fork built entirely around SDD. This isn't a plugin; it's a new IDE. **Three-Phase Workflow:** 1. **Requirements**: Capture user stories with acceptance criteria in EARS notation 2. **Design**: Document technical architecture and sequence diagrams 3. **Tasks**: Generate detailed implementation plans **Generated Files:** - `requirements.md` – User stories and acceptance criteria - `design.md` – Technical architecture - `tasks.md` – Implementation checklist **Agent Hooks (Unique Feature):** Kiro includes event-driven automations: - Save a React component → hooks update test files - Modify API endpoints → hooks refresh README - Ready to commit → security hooks scan for credentials **Availability**: Preview on Mac, Windows, Linux; $20/month pricing ### Other SDD Tools - **Cursor Plan Mode**: Separate planning and execution phases - **Claude Code Plan Mode**: Read-only exploration before implementation - **Context7**: MCP server for context management - **Tessl Framework**: Most radical—treats specs as the only maintained artifact (private beta) ## SDD vs. BMAD vs. PRP How does SDD compare to the frameworks we've covered? | Aspect | BMAD | PRP | SDD | |--------|------|-----|-----| | **Philosophy** | AI as collaborators | Minimum viable context | Intent as source of truth | | **Primary Artifact** | Documentation | PRP (context packet) | Specification | | **Code Status** | Important | Production-ready | Potentially disposable | | **Structure** | 21 agents, 4 phases | 5-phase workflow | Given/When/Then scenarios | | **Best For** | Enterprise systems | Feature development | Behavior-driven features | | **Tool Support** | VS Code, Cursor, Claude | Claude Code primarily | GitHub, Amazon, all major | **Use BMAD when**: Building enterprise systems with multiple teams **Use PRP when**: Adding features to existing codebase with known patterns **Use SDD when**: Defining behavior-driven features with clear acceptance criteria ## The Connection to BDD and TDD SDD isn't entirely new—it builds on proven methodologies: ### From TDD (Test-Driven Development) TDD: Write tests first, then code to make tests pass. SDD: Write specs first, AI generates code to match specs. The principle is the same—define expected behavior before implementation. ### From BDD (Behavior-Driven Development) BDD refined TDD with human-readable "Given-When-Then" language to align developers and stakeholders. SDD inherits this format but adds a new participant: AI agents. As the ThoughtWorks article notes: "Both TDD and BDD turned expectations into verifiable outcomes—but they still assumed humans were the only participants." ## The Cautions: What Can Go Wrong SDD isn't without challenges: ### Spec Drift and Hallucination "Spec drift and hallucination are inherently difficult to avoid." Even with clear specifications, AI can: - Misinterpret domain language - Generate code that appears correct but behaves differently - Add assumptions not in the specification ### Context Window Limitations "Even with all these files and templates and prompts and workflows and checklists, the agent frequently ultimately does not follow all the instructions. Yes, the context windows are now larger... but just because the windows are larger, doesn't mean AI will properly pick up on everything that's in there." ### Not Actually Waterfall Some critics worry SDD is "reinvented waterfall." ThoughtWorks addresses this: "SDD differs from traditional waterfall by maintaining short feedback cycles through AI-assisted code generation rather than extended planning phases followed by lengthy implementation periods." The key difference: specs can be iterated quickly because code regeneration is fast. ## Why This Matters for You Understanding SDD is the difference between following AI trends and shaping them. **For developers**: SDD changes your role from "code writer" to "intent definer." The skill becomes specifying behavior precisely, not implementing it manually. **For PMs**: SDD gives you direct leverage. Your specifications become executable. You're not hoping developers interpret requirements correctly—AI implements your exact intent. **For architects**: SDD enables "architecture as specification." System constraints live in specs, automatically enforced during generation. As the industry analysis notes: "25% of Y Combinator's Winter 2025 cohort have codebases that are 95% AI-generated." SDD is how that becomes manageable, not chaotic. ## Connecting to Our AI Fundamentals This is exactly why I've been taking you through AI fundamentals in this series: | Previous Topic | Connection to SDD | |----------------|-------------------| | **Embeddings** | Enable semantic understanding of specifications | | **Vector Databases** | Store and retrieve spec patterns | | **Context Engineering** | SDD IS context engineering at the spec level | | **BMAD** | SDD can use BMAD's documentation-as-source-of-truth principle | | **PRP** | SDD's validation commands mirror PRP's approach | ## Getting Started with SDD ### Option 1: GitHub Spec-Kit ```bash # Initialize new project uvx --from git+https://github.com/github/spec-kit.git specify init my-project # Or in existing project specify init . --ai claude ``` Then use `/specify`, `/plan`, `/tasks` commands with your AI coding assistant. ### Option 2: Amazon Kiro Download Kiro from kiro.dev and use its built-in Requirements → Design → Tasks workflow. ### Option 3: Manual SDD Even without tooling, you can practice SDD: 1. Write Given/When/Then scenarios before coding 2. Have AI review specs for completeness 3. Generate implementation from specs 4. Validate against original scenarios 5. Maintain specs as you evolve features ## What's Next Excited to delve deeper? In next week's post, I will explain Context Engineering—the discipline that makes all these planning frameworks even more powerful. Anthropic says "intelligence is not the bottleneck, context is," and understanding context engineering will take your vibe-planning to the next level. We'll explore the four core strategies (Write, Select, Compress, Isolate) and why Shopify now requires AI proficiency in performance reviews. Stay tuned!! ## Key Takeaways - **SDD** = Using specifications as prompts for AI to generate executable code - **ThoughtWorks**: "One of the most important practices to emerge in 2025" - **The shift**: "Intent is the source of truth," not code - **The goal**: 95%+ accuracy implementing specs on the first try - **Given/When/Then**: Inherit BDD's structure for AI implementation - **Three levels**: Spec-First → Spec-Anchored → Spec-as-Source - **GitHub Spec-Kit**: 50k+ stars, four-phase workflow - **Amazon Kiro**: Full IDE built around SDD ($20/month) - **Key principle**: "You're asking AI to think first, not code first" ## Additional Documents to Read on This - [Spec-Driven Development - ThoughtWorks](https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices) - The definitive 2025 analysis - [GitHub Spec-Kit](https://github.com/github/spec-kit) - Open-source toolkit (50k+ stars) - [GitHub Blog: SDD with AI](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) - Official introduction - [Amazon Kiro](https://kiro.dev/) - SDD-native IDE - [Martin Fowler: SDD Tools Analysis](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) - Kiro, Spec-Kit, Tessl comparison - [Red Hat: How SDD Improves AI Quality](https://developers.redhat.com/articles/2025/10/22/how-spec-driven-development-improves-ai-coding-quality) - Enterprise perspective --- *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: Context Engineering.*