Spec-Driven Development: Write Specs, Not Code
Spec-driven development is a paradigm shift: instead of writing code, developers write detailed specifications that AI coding agents implement directly. GitHub has been a major proponent of this approach, seeing specs as the natural interface between human intent and AI execution. The developer's job becomes defining what to build with precision, while AI handles the how.
What Is Spec-Driven Development?
Spec-driven development is a paradigm shift: instead of writing code, developers write detailed specifications. AI coding agents then implement those specs directly.
GitHub has been a major proponent of this approach, seeing specs as the natural interface between human intent and AI execution. The developer's job becomes defining what to build with precision, while AI handles the how.
This isn't about dumbing down development - it's about raising the abstraction level. Good specs require deep technical knowledge. But instead of expressing that knowledge as code, you express it as unambiguous requirements that any capable agent can implement.
The Shift
Traditional: Write code → Test → Debug → Iterate
Spec-driven: Write spec → AI generates code → Review → Refine spec → Regenerate
Anatomy of a Good Spec
Overview
High-level description of what this feature/component does
Requirements
Detailed functional and non-functional requirements
Interfaces
Input/output definitions, API contracts, data shapes
Examples
Concrete input/output examples for key scenarios
Edge Cases
How to handle errors, edge conditions, invalid inputs
Acceptance Criteria
Testable conditions that define 'done'
Example Spec Structure
# Feature: User Authentication
## Overview
Implement email/password authentication with JWT tokens.
## Requirements
- Email validation with confirmation link
- Password requirements: 8+ chars, 1 number, 1 special
- JWT tokens with 24h expiry, refresh tokens with 7d expiry
- Rate limiting: 5 attempts per minute per IP
## Interfaces
POST /auth/register { email, password } → { user, token }
POST /auth/login { email, password } → { user, token, refresh }
POST /auth/refresh { refreshToken } → { token }
## Examples
Input: { email: "user@example.com", password: "Secure1!" }
Output: { user: { id, email }, token: "eyJ..." }
## Edge Cases
- Duplicate email: Return 409 with "Email already registered"
- Invalid password: Return 400 with specific requirement failures
- Expired token: Return 401, client should use refresh endpoint
## Acceptance Criteria
- [ ] User can register with valid email/password
- [ ] User receives confirmation email
- [ ] User can login after confirmation
- [ ] Tokens expire correctly
- [ ] Rate limiting blocks after 5 failed attempts
Why Spec-Driven?
Predictable Output
Detailed specs produce more consistent AI-generated code
Reviewable Intent
Specs can be reviewed before any code is written
Reusable Patterns
Spec templates accelerate future similar work
Documentation Built-In
Specs serve as living documentation of intent
Easier Iteration
Change the spec, regenerate the code, compare results
Human-AI Handoff
Clear specs enable smooth handoffs between human and AI work
Frequently Asked Questions
What is spec-driven development?
Spec-driven development is writing detailed specifications that AI coding agents can execute directly. Instead of writing code, you write precise specs describing what you want - the AI turns specs into working implementations.
How is this different from normal prompting?
Regular prompts are conversational. Specs are structured, detailed documents that define inputs, outputs, behavior, edge cases, and acceptance criteria. They're closer to technical requirements than chat messages.
Why is GitHub pushing spec-driven development?
GitHub sees specs as the future interface between humans and AI agents. Their vision: developers focus on what to build (specs), while agents focus on how to build it (code). It's a fundamental shift in the development process.
What makes a good spec for AI agents?
Clear success criteria, explicit constraints, defined interfaces, example inputs/outputs, and edge case handling. The spec should be unambiguous enough that a human developer could implement from it too.
What spec formats work best?
Structured markdown is popular - sections for overview, requirements, interfaces, examples, and acceptance tests. Some teams use YAML or JSON for machine-readable specs. The key is consistency and completeness.
Can AI help write specs?
Yes, AI can help draft specs from rough descriptions, identify missing requirements, suggest edge cases, and validate specs against existing code. Spec writing becomes a human-AI collaboration.
How do specs connect to context engineering?
Specs are a form of context. They provide the detailed information AI needs to produce correct code. Good specs reduce the context engineering burden by front-loading clarity and precision.
Can you help implement spec-driven workflows?
Yes. I help teams adopt spec-driven development - from spec templates to agent configuration to workflow integration. The goal is faster, more predictable AI-assisted development.
Ready for Spec-Driven Development?
I help teams adopt spec-driven workflows - from creating spec templates to configuring agents to integrating specs into your development process.