/agent

wiki / raw / github-spec-driven-development-ai-2025

Spec-driven development with AI: Get started with a new open source toolkit

updated 2026-08-27

Original source: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ SHA256: efac995e17bb4e0cc6e7811f4c5d89f9f98e9e4bb34308bcbee17149208fb759

Spec-driven development with AI: Get started with a new open source toolkit

Author: Den Delimarsky (Principal Product Manager, GitHub)
Published: 2025-09-02
Source: The GitHub Blog

Executive Summary & Core Thesis

As coding agents have grown more capable, a common failure mode has emerged: developers describe a goal in natural language (“vibe-coding”), receive plausible-looking code back, and discover it fails to compile, misses architectural constraints, or introduces subtle logic bugs.

The failure is not the model’s raw coding ability, but the software development methodology. Treating agents like search engines fails because agents are literal-minded pair programmers that excel at pattern recognition but require unambiguous instructions.

GitHub introduces Spec-Driven Development (SDD) and the open-source Spec Kit toolkit (specify init, /specify, /plan, /tasks, /implement). SDD transitions software engineering from “code is the source of truth” to “intent and specifications are executable sources of truth.”

The 4-Phase Spec-Driven Process with Validation Gates

Phase 1: Specify (UX, user journeys, outcomes — "what" & "why")
                 ↓ [Human Validation Gate]
Phase 2: Plan (Architecture, tech stack, constraints, enterprise rules)
                 ↓ [Human Validation Gate]
Phase 3: Tasks (Decomposed into isolated, testable small units — "TDD for AI")
                 ↓ [Human Validation Gate]
Phase 4: Implement (Focused, reviewable diffs executed per task)
  1. Specify (/specify): Developer provides high-level intent; agent generates a detailed functional specification focusing on user experience, problem definition, and success criteria (technology-agnostic).
  2. Plan (/plan): Developer inputs technical stack, architectural patterns, compliance rules, design system tokens, and legacy constraints. Agent generates a comprehensive technical execution plan.
  3. Tasks (/tasks): Agent decomposes specification and plan into small, isolated, independently testable tasks (analogous to TDD for coding agents).
  4. Implement (/implement): Agent executes tasks sequentially or in parallel; human reviews small, focused diffs against task contracts rather than unconstrained 1,000-line code dumps.

High-Efficacy Application Domains

  1. Greenfield (0-to-1): Prevents generic pattern hallucination by establishing strict architectural constraints upfront.
  2. Feature Work in Existing Systems (N-to-N+1): Forces clarity on integration boundaries and prevents architectural erosion in complex codebases.
  3. Legacy Modernization: Extracts business logic into living specs to allow complete architecture rebuilding without carrying forward inherited technical debt.

Named Frameworks & Patterns (Verbatim)

  • “Spec-driven development (SDD)”: Development methodology where executable specifications act as the central governing artifact for agentic generation and verification.
  • “Spec Kit”: Open-source toolkit implementing phased /specify, /plan, /tasks, /implement workflows for coding agents.
  • “Intent is the source of truth”: The paradigm shift from static code repositories to executable specifications driving automated code synthesis.
  • “TDD for AI agents”: Task decomposition pattern where specifications and plans are split into small, reviewable, unit-testable increments before code generation.

Decision Rules

  • When directing AI coding agents on non-trivial systems, do author executable specifications and technical plans before writing code, because vague prompts force models to guess unstated architectural and business constraints.
  • When progressing through agentic development phases, do enforce validation gates at each phase (Specify, Plan, Tasks, Implement) before proceeding to the next, because errors in requirements compound exponentially when propagated directly into code generation.
  • When reviewing agent-generated code, do review focused, isolated task changes against explicit task contracts rather than reviewing 1,000-line monolithic diff dumps, because human verification bandwidth degrades on large multi-file diffs.
  • When building in existing enterprise codebases, do encode security policies, compliance rules, and design system constraints explicitly into the technical plan phase, because agents cannot infer unwritten organizational standards.

Anti-Patterns & Failure Modes (with Mechanisms)

1. Vibe-Coding / Vague Prompting

  • Mechanism: Issuing broad prompts (e.g. “add photo sharing to my app”) directly to coding agents.
  • Observable Symptom: The agent hallucinates unstated requirements, introduces conflicting libraries, breaks existing interfaces, and produces code that fails integration testing.

2. Monolithic Diff Dumps

  • Mechanism: Permitting agents to implement entire features across multiple layers in a single generation turn without task decomposition.
  • Observable Symptom: Reviewer fatigue, inability to verify edge cases, and high escape rate for subtle regression bugs.

What the Source Does NOT Claim

  • Does NOT claim that spec-driven development eliminates the necessity of human developer review; human steering and verification gates are mandatory at every phase.
  • Does NOT claim that writing natural language specifications alone produces bug-free code without automated testing and phased validation.