Spec-Driven Development

Master the complete Spec-Driven Development workflow with 11 comprehensive modules covering constitution, specification, planning, implementation, and documentation

What is Spec-Driven Development? Instead of coding first and writing docs later, in spec-driven development, you start with a (you guessed it) spec. This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code. The result is less guesswork, fewer surprises, and higher-quality code.

In 2025, this matters because:

  • AI IDEs and agent SDKs can turn ambiguous prompts into a lot of code quickly. Without a spec, you just get elegant garbage faster.
  • Agent platforms (e.g., OpenAI Agents SDK) make multi-tool, multi-agent orchestration cheap—but the cost of weak specifications is amplified at scale.
  • The broader ecosystem (e.g., GitHub's recent "spec-driven" tooling push) is converging on spec-first workflows for AI software.

Why it beats "vibe coding"?

  • Captures decisions in a reviewable artifact instead of buried chat threads.
  • Speeds onboarding and cross-team collaboration.
  • Reduces rework and drift because tests/examples anchor behavior.

Tools & patterns in SDD ecosystem

  • Spec-Kit Plus (Panaversity open-source toolkit)
  • Spec-Kit (GitHub's open-source toolkit) — templates and helpers for running an SDD loop with your AI tool of choice.
  • Broader coverage in recent articles summarizing SDD's rise and best practices.

How Spec-Kit Plus Works?

1. Core Features

  • /constitution commands → PHR created
  • /specify commands → PHR created
  • /plan commands → PHR created + ADR suggestion
  • /tasks commands → PHR created
  • /implement commands → PHR created
  • Debugging, refactoring, explanations → PHRs created

and following key innovations:

2. Automatic Prompt History Records

Every significant AI interaction is captured as a structured artifact—no. You work normally, and get complete documentation of your AI-assisted development journey.

What gets captured automatically:

You see: Brief confirmation like 📝 PHR-0003 recorded

3. Explicit Architecture Decision Records

After planning completes, you get a suggestion to review for architectural decisions. You explicitly run /adr when ready to capture significant technical choices.

Flow:

/plan completes
    ↓
📋 "Review for architectural decisions? Run /adr"
    ↓
(You run /adr when ready)
    ↓
ADRs created in docs/adr/ (if decisions are significant)

Why explicit? Architectural decisions require careful judgment, team discussion, and review of existing patterns. You control when this happens.

The Complete SDD Workflow

Core Modules (For Every Feature)

  1. Module 01 – Setup Environment

    • Install Spec-Kit Plus: pip install specifyplus
    • Initialize project: sp init my-app --ai gemini
    • Get automatic PHR + explicit ADR capabilities

  2. Module 02 – Define Constitution

    • Set project principles and quality standards
    • Creates: memory/constitution.md
    • PHR automatically created 📝

  3. Module 03 – Write Specification

    • Capture business requirements and acceptance criteria
    • Creates: docs/prompts/NNNN-feature-name.spec.prompt.md
    • PHR automatically created 📝

  4. Module 04 – Create Plan

    • Design technical architecture and implementation approach
    • Creates: specs/NNN-feature/plan.md
    • PHR automatically created 📝
    • ADR suggestion appears 📋

  5. Module 05 – Review Architectural Decisions

    • (You explicitly run /adr when ready)
    • Captures significant technical choices with context
    • Creates: docs/adr/NNNN-decision-title.md

  6. Module 06 – Generate Task List

    • Break down implementation into verifiable tasks
    • Creates: specs/NNN-feature/tasks.md
    • PHR automatically created 📝

  7. Module 07 – Implement with TDD

    • Red-Green-Refactor cycles with AI assistance
    • Test-first development with AI code generation
    • PHR automatically created 📝

Best Practices & Projects

  1. Module 08 – Chatbot Project

    • End-to-end example: Build a chatbot with OpenAI Agents SDK
    • Apply full SDD workflow to real project

  2. Module 09 – Operationalize Best Practices

    • Implement nine articles of developer-AI collaboration
    • Scale SDD across teams and projects

  3. Module 10 – Prompt History Records

    • Understanding automatic PHR creation
    • When PHRs are captured and how to use them

  4. Module 11 – Analyze & Clarify

    • Cross-check specifications, plans, and tasks
    • Identify gaps and resolve inconsistencies

Next Steps

Start with Module 01 – Setup Environment to install Spec-Kit Plus and begin your spec-driven development journey.