Development methodology where the specification is written before the code, serving as a contract between teams and as the source of truth for implementation.
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.
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 most established use. Write the OpenAPI specification first, generate server stubs and clients, then implement the logic.
Concrete benefits:
When using an AI agent to generate code, the specification acts as a structured prompt:
This significantly reduces hallucinations and incorrect code because the agent has a clear contract to work against.
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.
| Format | Primary use |
|---|---|
| OpenAPI | REST APIs |
| JSON Schema | Data validation |
| Protocol Buffers | gRPC APIs, serialization |
| AsyncAPI | Event-based APIs |
| JSON-RPC | Protocols like MCP |
In these cases, an iterative approach where the specification emerges from the code may be more practical.
Open protocol created by Anthropic that standardizes how AI applications connect with external tools, data, and services through a universal interface.
Field of computer science dedicated to creating systems capable of performing tasks that normally require human intelligence, from reasoning and perception to language generation.
Key takeaways from Dr. Werner Vogels' final keynote at AWS re:Invent 2025, where he presents the Renaissance Developer framework and argues why AI will not replace developers who evolve.
Demonstration of dual-interface architecture where the same business logic serves both a traditional web application and an MCP server for AI tools.
Typed superset of JavaScript adding optional static types, improving developer productivity, error detection, and code maintainability.
Practice of treating documentation with the same tools and processes as code: versioned in Git, reviewed in PRs, and automatically generated when possible.
Practices and tools for documenting APIs clearly, interactively, and maintainably, from OpenAPI specifications to documentation portals.
Principles and practices for designing clear, consistent, and evolvable programming interfaces that facilitate integration between systems.
Tools using LLMs to help developers write, understand, debug, and refactor code, from autocomplete to agents that implement complete features.