Spec-Driven Development
Development methodology where the specification is written before the code, serving as a contract between teams and as the source of truth for implementation.
What it is
Spec-Driven Development (SDD) is a methodology where a detailed specification is written before writing code. The specification — not the code — is the project's source of truth.
It's the opposite of the "code-first" approach where you implement first and document later (if at all). In SDD, the specification functions as a contract: it defines what the system should do, how its parts communicate, and what to expect from each interface.
Why it matters now
SDD isn't new — API-first design with OpenAPI/Swagger has existed for years. But the arrival of AI agents that generate code has made this methodology more relevant than ever.
When an AI agent generates code, it needs clear, unambiguous instructions. A well-written specification is exactly that: a structured document that defines expected behavior, data types, interface contracts, and acceptance criteria.
Without a specification, the agent guesses. With a specification, the agent implements.
The SDD cycle
- Define: write the specification in a structured format (OpenAPI, JSON Schema, protobuf, or even a detailed requirements document)
- Validate: review the specification with all stakeholders before writing code
- Generate: create base code, mocks, and tests from the specification
- Implement: write business logic within the generated structure
- Verify: confirm the implementation meets the specification
Applications
APIs (the classic case)
The most established use. Write the OpenAPI specification first, generate server stubs and clients, then implement the logic.
Concrete benefits:
- Frontend and backend can work in parallel from day one
- API contracts are explicit and versioned
- Contract tests are generated automatically
AI-assisted development
When using an AI agent to generate code, the specification acts as a structured prompt:
- Defines exact data types and models
- Establishes expected behaviors with examples
- Specifies constraints and edge cases
- Provides verifiable acceptance criteria
This significantly reduces hallucinations and incorrect code because the agent has a clear contract to work against.
Protocols (MCP, A2A)
The Model Context Protocol is an example of SDD applied to AI protocols. The specification defines exactly how clients and servers should communicate, what messages are valid, and what responses to expect. Any implementation that meets the specification is interoperable.
Common specification formats
| Format | Primary use |
|---|---|
| OpenAPI | REST APIs |
| JSON Schema | Data validation |
| Protocol Buffers | gRPC APIs, serialization |
| AsyncAPI | Event-based APIs |
| JSON-RPC | Protocols like MCP |
When not to use SDD
- Quick prototypes: when exploring an idea and the specification would change every hour
- One-person projects: the overhead of maintaining a formal specification may not be justified
- Unknown domains: if the problem isn't well understood, writing a premature specification can be counterproductive
In these cases, an iterative approach where the specification emerges from the code may be more practical.
References
- What Is Specification-Driven API Development? — Nordic APIs. Clear introduction to the concept.
- Using spec-first API development for speed and sanity — Atlassian, 2024. Practical adoption case in large teams.
- OpenAPI Specification — The most widely used standard for REST API specifications.
- Model Context Protocol Specification — Example of SDD applied to an AI protocol.