--- title: "Spec-driven development with AI: Get started with a new open source toolkit" section: "raw" type: "source" created: "2026-08-27" updated: "2026-08-27" canonical: "https://pyweb.dev/wiki/raw/articles/github-spec-driven-development-ai-2025" --- # 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](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) --- ## 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. --- ## Agent Navigation ### Machine endpoints - Knowledge graph: https://pyweb.dev/api/graph.json - Graph analysis: https://pyweb.dev/api/graph-analysis.json - Context index: https://pyweb.dev/llms.txt