Ziv Kfir

Posted on Jan 7

Back to the V-Model: SDD in the AI Era - Classic V-Model discipline for AI-first SDD

#ai #architecture #softwareengineering

Spec-Driven Development (SDD): Complete Overview

Navigation: Overview (you are here) | Greenfield Workflow | Brownfield Workflow

What Is Spec-Driven Development?
What Problem Does This Solve?
When Should You Use SDD?
Tool Landscape
Related Methodologies
References
Appendix A: IMPD and Semantic CI/CD
Appendix B: Further Reading

What Is Spec-Driven Development?

Spec-Driven Development (SDD) is a software engineering methodology where you write a formal, detailed specification document before implementing features or systems, and use that spec as the single source of truth throughout development.

Core Principles

Spec First: Write requirements, edge cases, and acceptance criteria before coding
Single Source of Truth: The spec is the authoritative reference for what to build
Test-Driven: Derive tests directly from the spec
Iterative Refinement: Update the spec as you discover gaps during implementation
Living Documentation: The spec evolves but always reflects current state

How It Works

Ad-hoc AI Prompting (Vibe Coding):
Idea → Prompt AI → Code → "Oh, I forgot about X" → Re-prompt → Drift → More patches

AI-Assisted SDD:
Idea → Spec (formal doc) → Review → Approve → Tests (from spec) → Code (to pass tests) → Ship
           ↑                                                                              ↓
           └──────────────────── Update spec if gaps found ──────────────────────────────┘

The key difference: The spec prevents "forgetting" requirements mid-project because everything is written down and reviewed upfront. This applies SDD principles (long established in Waterfall/V-Model) to modern AI-assisted development.

What Problem Does This Solve?

Problem 1: Context Window Degradation (AI Hallucination)

Without SDD:

You: "Build a user authentication system"
AI: [generates code]
You: "Add password reset"
AI: [generates more code, but forgets some auth logic]
You: "Add 2FA"
AI: [now the code is inconsistent, previous features broken]

Root cause: AI context window has limits. As conversation grows, early requirements fade from context. AI "hallucinates" solutions that contradict earlier decisions.

With SDD:

You: "Generate a spec for user authentication with password reset and 2FA"
AI: [generates formal spec.md with all requirements]
You: Review, approve, lock the spec
AI: "Implement Task 1 from spec.md"
AI: [generates code referencing spec.md]
You: "Implement Task 2 from spec.md"
AI: [generates code referencing spec.md - no hallucination, spec is always loaded]

Solution: The spec is a persistent artifact that's always referenced. AI doesn't need to "remember" from chat history—it reads the spec.

Problem 2: Scope Creep and Drift

Without SDD:

Start building Feature A
Midway, realize you need Feature B
Implement B, but now A doesn't work
Fix A, but introduce bug in C
No clear "done" state

With SDD:

Spec defines exactly what's in scope
If new requirements emerge, update the spec first, then implement
Clear acceptance criteria = clear "done"

Problem 3: Lost Knowledge

Without SDD:

Developer implements feature
6 months later: "Why did we do it this way?"
Original context lost in Slack/email/memory

With SDD:

Spec documents:
- Why decisions were made (trade-offs section)
- What edge cases exist
- How the system should behave
Future developers read the spec and understand immediately

Problem 4: Testing Is an Afterthought

Without SDD:

Write code
"I'll add tests later" (never happens)
Ship with 30% test coverage

With SDD:

Spec defines acceptance criteria
Tests are derived from spec before coding
Code is written to pass tests
Result: 100% coverage of spec requirements

When Should You Use SDD?

✅ Use SDD When:

Building complex features or systems (> 500 lines of code, multiple days of work)
Working with AI assistants (prevents hallucination and drift)
Multiple people involved (spec = shared understanding)
Long-term maintenance expected (spec = documentation for future)
High cost of bugs (production-critical, security-sensitive, regulated)

⚠️ Optional for SDD:

Small bug fixes (< 100 lines, < 2 hours) - lightweight process is fine
Prototypes or experiments - speed matters more than rigor
Trivial changes (typos, config tweaks) - good commit message is enough

Decision Tree

Is your change:
  ├─ New big project (greenfield, 500+ lines, multiple days)? → Full SDD (6-phase workflow)
  ├─ New medium feature (100-500 lines, 2-8 hours)? → Change Proposal (1-2 page spec)
  ├─ Bug fix or small feature (< 100 lines, < 2 hours)? → Lightweight (good commit message)
  └─ Prototype or experiment? → Skip SDD, iterate fast

Tool Landscape

Disclaimer: My main experience with Spec-Driven Development (SDD) comes from designing and running manual SDD processes on real projects. My familiarity with off-the-shelf SDD/AI tools and platforms is more limited, partly because many of them did not exist when these projects were executed.

There are multiple ways to implement SDD, from manual (templates + meta-prompts) to fully automated tools.

Note: The tool landscape for SDD is rapidly evolving. Some tools listed below are emerging or conceptual. Always verify current availability and features before adoption.

Comparison Table

Tool	Type	Best For	Pros	Cons
Manual SDD	Templates + Meta-Prompts	Anyone, any AI tool	No setup, full control, works with Claude/ChatGPT/Cursor	Requires discipline
GitHub Spec Kit	Official GitHub Methodology	Teams standardizing on SDD	Platform-agnostic, slash commands (`/speckit.specify`, `/speckit.plan`)	More setup required
Claude SDD Toolkit	Prompts + Workflows	Claude/Cursor users	Turnkey for Claude ecosystem	Claude-specific
Kiro (AWS)	IDE-Native SDD Tool	All-in-one experience	Fully automated, living docs, IDE integration	Proprietary, newer tool
TaskGuard	CI/CD Enforcement	Critical systems	Enforces "spec before code" in pipeline	Setup overhead

1. Manual SDD (Templates + Meta-Prompts)

What it is: Use structured templates (checklist-based) with AI to generate specs, then implement following the spec.

How it works: Create templates for different change types. Use meta-prompts to guide AI in generating specs that follow your template structure. Review, refine, approve the spec, then implement test-first.

Best for: Individuals, small teams, or anyone wanting tool-independence and full control over the spec process.

2. GitHub Spec Kit

What it is: GitHub's official SDD toolkit with slash commands for spec-driven development workflows.

How it works:

Use /speckit.specify command to generate formal specifications
Use /speckit.plan to create implementation plans with research
Use /speckit.tasks to break plans into ordered, dependency-aware tasks
Use /speckit.implement to execute the implementation plan
Specs and plans are versioned in your repo

Pros:

✅ Official GitHub methodology
✅ Platform-agnostic (works with any IDE)
✅ Integrates with GitHub workflows

Cons:

❌ Requires initial setup
❌ Best suited for larger projects

Best for: Teams already using GitHub Copilot.

Reference: GitHub Spec Kit

3. Claude SDD Toolkit

What it is: Pre-built prompts and workflows specifically for Claude Code (Cursor, Claude Projects), created by Tyler Burleigh.

Relationship to GitHub Spec Kit:

GitHub Spec Kit = Platform-agnostic SDD methodology (the standard)
Claude SDD Toolkit = Tyler Burleigh's implementation specifically optimized for Claude/Cursor ecosystem

How it works:

Load SDD prompts into Claude Project
Use structured commands to generate specs, plans, tests
Claude references spec throughout implementation

Pros:

✅ Turnkey for Claude ecosystem
✅ Pre-built prompts (minimal setup)
✅ Optimized for Claude's context window

Cons:

❌ Claude-specific (doesn't work with ChatGPT, etc.)
❌ Less flexible than manual approach

Best for: Heavy Claude/Cursor users who want a ready-made workflow.

Reference: Claude SDD Toolkit

4. Kiro (AWS)

What it is: An agentic IDE from AWS that implements spec-first development workflows.

How it works:

Generates specs from natural language
Automatically creates architecture diagrams (C4 model)
Breaks specs into tasks with dependencies
Enforces test-first implementation
Keeps specs in sync with code (living documentation)

Pros:

✅ Integrated spec-first workflow
✅ IDE-native experience
✅ Living documentation (specs auto-update)
✅ Built-in approval gates

Cons:

❌ AWS ecosystem (may have vendor considerations)
❌ Newer product (ecosystem still developing)
⚠️ Verify current availability before adoption

Best for: Teams wanting all-in-one automation.

Reference: Kiro (verify current availability)

5. TaskGuard

What it is: Custom CI/CD pipeline rules that enforce spec-first workflows.

How it works:

Add TaskGuard to your CI/CD pipeline
Requires spec.md to exist before code can be committed
Enforces tests exist before implementation
Blocks merge if tests don't pass

Pros:

✅ Enforces discipline (can't skip specs)
✅ Works with any SDD approach (manual, SpecKit, Kiro)
✅ Integrates with existing CI/CD
✅ Fully customizable

Cons:

❌ Setup overhead
❌ Can slow down rapid prototyping

Best for: Production-critical or security-sensitive systems where rigor is mandatory.

Which Tool Should You Use?

Start with Manual SDD if:

You're new to SDD (learn fundamentals first)
You want tool-independence
You're an individual or small team

Use GitHub Spec Kit if:

You want a structured, well-documented workflow
You're using Claude Code or similar AI agents
You need slash-command convenience (/speckit.specify, /speckit.plan, etc.)

Use Claude SDD Toolkit if:

You're heavy Claude/Cursor user
You want turnkey prompts
You don't need multi-tool support

Adopt Kiro if:

You want full automation
You have budget for tooling
Your team is ready for IDE-native SDD

Add TaskGuard if:

You need enforcement (critical systems)
You want CI/CD integration
You're already using another SDD approach

Related Methodologies

SDD builds on and complements other established practices:

Test-Driven Development (TDD)

TDD: Write tests before code (red → green → refactor)

SDD + TDD: Spec defines what to test, TDD defines how to test

Together: Spec → Derive tests → Implement code to pass tests

Design Docs (Google-style)

Google Design Docs: Write design before coding, include trade-offs and alternatives.

SDD difference:

SDD is more formal (structured templates)
SDD includes test cases and acceptance criteria
SDD is "living" (updated during implementation)

Similarity: Both emphasize thinking before coding and documenting decisions.

IMPD (Interactive Model-driven Progressive Development)

IMPD: Use AI to iteratively refine requirements through Q&A before spec generation. See Appendix A for details.

Semantic CI/CD

Semantic CI/CD: CI/CD pipeline understands intent (not just syntax), verifies behavior matches spec. See Appendix A for details.

References

IEEE 29148:2018 - Systems and Software Engineering: Requirements Engineering Standard
Google Engineering Practices: Design Docs - https://google.github.io/eng-practices/
C4 Model (Architecture Diagrams) - Simon Brown, https://c4model.com/
GitHub Spec Kit - https://github.com/github/spec-kit
Claude SDD Toolkit - https://github.com/tylerburleigh/claude-sdd-toolkit
Kiro (AWS) - https://kiro.dev

Summary

Spec-Driven Development is a methodology where you:

Write a formal spec before coding
Use the spec as single source of truth
Derive tests from the spec
Implement code to pass tests
Update spec when gaps are found

Why it works:

Prevents AI hallucination (spec is persistent artifact)
Prevents scope creep (clear boundaries)
Creates organizational memory (docs for future)
Enables test-first development (clear acceptance criteria)

When to use:

Complex features or new systems
Working with AI assistants
Production-critical code
Long-term maintenance expected

Tools: Choose based on your needs - from Manual (full control) to Kiro (full automation).

Next steps:

Choose your workflow: Greenfield (new projects) or Brownfield (existing code)
See SDD-Workflow-Greenfield.md for new big projects
See SDD-Workflow-Brownfield.md for existing codebases

Appendix A: IMPD and Semantic CI/CD

This appendix covers two complementary methodologies that enhance SDD, both developed by Ziv Kfir.

IMPD (Interactive Model-driven Progressive Development)

What it is: A requirement elicitation technique that uses iterative Q&A with AI to gather complete requirements before generating formal specs.

How IMPD complements SDD:

IMPD: Requirement elicitation (discovering what to build)
SDD: Structured execution (how to build it with spec as single source of truth)
Together: IMPD → complete requirements → SDD → formal spec → implementation

When to use IMPD:

New projects where requirements are unclear
Early discovery phases before formal spec writing
Complex domains where edge cases need exploration
Stakeholder engagement when they don't know exactly what they need

IMPD Process:

You provide rough idea
AI asks clarifying questions (3-5 at a time)
You answer
AI asks follow-up questions based on answers
Iterate until complete understanding
AI summarizes complete requirements
Feed into SDD: Use requirements summary to generate formal spec

Example:

You: "I want to build a task management system"
AI: [asks about users, auth, task structure, real-time, concurrency, data models]
You: [answers each round]
AI: [asks follow-ups about edge cases, permissions, notifications]
You: [provides details]
AI: [summarizes complete functional + non-functional requirements]
→ Requirements become input to SDD Phase 2 (Specification Generation)

IMPD in SDD Workflows:

Greenfield (new projects): IMPD is Phase 1, see SDD-Workflow-Greenfield.md
Brownfield (existing code): IMPD used for large changes (500+ lines)

Learn more: See Ziv Kfir's article "Beyond Prompt Engineering: Envision a Framework for Interactive AI-Assisted Development" on dev.to

Semantic CI/CD

What it is: AI-powered CI/CD that understands intent (not just syntax), enabling automated failure analysis and fixes that align with specification intent.

How Semantic CI/CD complements SDD:

SDD: Defines intent in spec (what the system should do)
Tests: Verify intent (acceptance criteria)
Semantic CI/CD: When tests fail, AI analyzes failure in context of spec intent and suggests/implements fixes

Traditional CI/CD:

Test fails → Developer manually debugs → Fix → Re-run

Semantic CI/CD:

Test fails → AI reads spec + test + code → AI understands intent mismatch → 
AI suggests fix aligned with spec → Developer reviews → Approve → Auto-fix

Key Difference: AI doesn't just fix syntax errors—it understands why the code should behave a certain way (from the spec) and fixes logic to match intent.

Example:

Spec says: "API should return 404 if user not found"
Test fails: API returns 500 instead of 404
Traditional CI/CD: "Test failed. Status code mismatch."
Semantic CI/CD: 
  - Reads spec (knows intent: 404 for not found)
  - Reads code (sees exception not handled)
  - Suggests: "Add try-catch for UserNotFoundException, return 404"
  - Fix aligns with spec intent

Benefits:

Faster debugging: AI diagnoses root cause by understanding intent
Spec alignment: Fixes conform to specification (not just passing tests)
Knowledge preservation: AI learns patterns from spec → code → test relationships

The Complete Loop:

1. SDD: Write spec (intent)
2. TDD: Write tests (verify intent)
3. Implement: Code to pass tests
4. Semantic CI/CD: When tests fail, AI fixes using spec intent
5. Update spec if new requirements discovered

Learn more: See Ziv Kfir's article "CI/CD Semantic Automation: AI-Powered Failure Analysis" on dev.to

Evolution Timeline

2022-2023: Vibe Coding

"AI, build me a login system" → AI generates code
No structure, no specs, high hallucination

2024: Context-Aware Development

Load codebase into context window
AI understands existing code
Still no formal specs

2025: Spec-Driven Development (SDD)

Write spec first
Spec = single source of truth
Tests derived from spec
Prevents hallucination and drift

2025+: IMPD + SDD + Semantic CI/CD (Current State)

IMPD: Interactive requirement elicitation
SDD: Formal spec + test-first implementation
Semantic CI/CD: AI-powered debugging aligned with spec intent
Result: Complete workflow from idea → requirements → spec → code → tests → automated fixes

Appendix B: Further Reading

Official Documentation

GitHub Spec Kit: https://github.com/github/spec-kit
Claude SDD Toolkit: https://github.com/tylerburleigh/claude-sdd-toolkit
Kiro (AWS): https://kiro.dev
C4 Model (Architecture): https://c4model.com/

Related Concepts (by Ziv Kfir)

"Beyond Prompt Engineering: Envision a Framework for Interactive AI-Assisted Development" - dev.to
- In-depth IMPD methodology
- Real-world examples of requirement elicitation with AI
- Integration with SDD workflows
"CI/CD Semantic Automation: AI-Powered Failure Analysis" - dev.to
- Semantic CI/CD explained
- How AI understands spec intent for debugging
- Closing the loop: Spec → Code → Tests → AI Diagnosis → Fix

Community Resources

IEEE 29148:2018: Systems and Software Engineering: Requirements Engineering Standard
Google Engineering Practices: Design Docs - https://google.github.io/eng-practices/

Navigation: Overview (you are here) | Greenfield Workflow | Brownfield Workflow

Disclaimer: The views, opinions, methodologies, and recommendations expressed in this document are solely those of the author(s) and contributors. They do not represent, reflect, or are endorsed by any past, present, or future employer, organization, or affiliated entity. This documentation is provided for educational and informational purposes based on practical experience and publicly available resources. Users should evaluate and adapt these practices to their own specific contexts, requirements, and organizational standards.