Fig.1
The Documentation Graveyard
Every mid-senior developer has lived this story. You join a new team, crack open the API docs, and discover they describe an endpoint that was refactored six sprints ago. The response schema references fields that no longer exist. The authentication section still describes a bearer token flow that was replaced with OAuth2 last quarter. Nobody updated the wiki because nobody owns the wiki.
This is the predictable outcome of code-first development, the dominant paradigm where documentation is an afterthought, delegated to whoever drew the short straw during sprint planning. It’s not a people problem. It’s a systems problem. And spec-driven development is the systems answer.
But something important happened to spec-driven development between 2024 and today. The term split into two related but distinct movements, and then those movements started converging. If you learned SDD as “OpenAPI-first API design,” you know half the story. The other half is the reason GitHub’s Spec Kit has crossed 90,000 stars, AWS built an entire IDE around specs, and Google shipped Antigravity with spec-driven workflows built into its agent orchestration model.
This post covers both lineages and explains why I think the convergence is the biggest shift in engineering practice since CI/CD.
SDD, Lineage One: The Contract Tradition
Spec-driven development in its original sense is a methodology where a machine-readable, human-understandable specification is written before a single line of application logic. The specification, not the code, not the tests, not a Confluence page, is the single source of truth for how your system behaves at its boundaries.
For REST APIs, that specification is typically an OpenAPI document. For event-driven systems, it’s AsyncAPI. For gRPC services, it’s Protocol Buffers. For GraphQL, it’s the schema definition language itself. The format matters less than the principle: the spec is not a byproduct of development. It is the starting point.
If you’ve worked in strongly typed languages, this will feel intuitive. A spec is an interface contract that operates at the network boundary. It defines the shape of requests, the structure of responses, the taxonomy of errors, and the authentication requirements, all before implementation begins.
The Core Philosophy: Spec as Code
In traditional development, documentation drifts from reality the moment a developer pushes a hotfix at 2 AM. SDD eliminates drift by construction. The specification isn’t a separate artifact that needs to be “kept in sync” with the codebase. It drives the codebase. It sits in the same repository, goes through the same pull request reviews, and gates the same CI/CD pipelines as your application code.
Your openapi.yaml has the same status as your Dockerfile or your terraform/*.tf files. It’s infrastructure. It’s executable. It’s versioned. Changing it has consequences that are automatically enforced.
┌─────────────────────┐
│ Design the Spec │ ← Devs, PMs, Architects collaborate here
│ (openapi.yaml) │
└────────┬────────────┘
│
├──────────────────┬──────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Mock Servers │ │ Code Gen │ │ Contract Tests │
│ Prism, WireMock│ │ Stubs & SDKs │ │ CI/CD Gates │
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
▼ ▼ ▼
Frontend & Backend Validated
Mobile Dev Boilerplate DeploymentsThe Contract Workflow: Four Phases
Phase 1: Design & Collaborate. Before a single controller is scaffolded, the team designs the spec. This isn’t a formality. It’s where the hard decisions happen. Developers, product managers, and architects negotiate over endpoint naming, resource modeling, pagination strategies, error taxonomies, and versioning schemes. Because OpenAPI is both machine-readable and human-readable, these conversations happen around a concrete artifact rather than abstract whiteboard diagrams. A product manager can look at a POST /orders request body and say, “We also need a priority field here.” A security engineer can flag that GET /users/{id} is missing an authorization scope. These are the conversations you want to have before anyone writes implementation code.
Phase 2: Parallel Development via Mocking. Once the spec is merged, tools like Prism, WireMock, or Mockoon automatically spin up mock servers that return realistic responses based on your spec’s schemas and examples. Frontend and mobile engineers no longer sit idle while backend engineers build the real services. They start consuming realistic mock data from day one. This also shifts the discovery of integration issues left. If the frontend team realizes the response structure is awkward, that feedback surfaces during the spec review cycle, not three weeks later during integration testing when the cost of change is an order of magnitude higher.
Phase 3: Code & SDK Generation. Tools like OpenAPI Generator, openapi-ts, or Buf automatically produce server stubs, type-safe client SDKs, and shared data models. A critical nuance: code generation doesn’t mean you surrender control. The generated stubs are a starting skeleton, a frame on which you hang your business logic. The generated code handles the shape; you implement the substance.
Phase 4: Continuous Contract Testing. This is the enforcement mechanism. During CI/CD, tools like Schemathesis, Pact, or runtime validators (express-openapi-validator, connexion) compare every actual API response against the declared spec. If a developer renames a database column that subtly changes a response field from createdAt to created_at, the contract test catches it. That’s a failed build instead of a production incident discovered by a frustrated consumer three days later.
This is where SDD moves past documentation and becomes automated governance.
SDD, Lineage Two: The Agentic Tradition
Now for the newer story, the one that made spec-driven development a top-trending engineering topic through 2025 and 2026.
As AI coding agents grew capable of executing multi-file, multi-step tasks on their own, a failure mode showed up that the industry now calls the limits of “vibe coding.” You prompt the agent conversationally, accept what it produces, and watch the codebase drift from intent as the agent hallucinates APIs, forgets earlier decisions, and shapes the architecture around conversational pivots rather than deliberate design. It works for prototypes. It falls apart at scale.
The industry’s answer was the same answer the API world found a decade earlier: write the spec first, and make the spec the artifact the agent executes against, verifies against, and reports against. The spec becomes the prompt, but a versioned, reviewed, structured prompt that survives context window resets and staff turnover alike.
A useful taxonomy has emerged (formalized in early 2026 academic work) describing three rigor levels:
- Spec-first: A well thought out spec is written before the AI-assisted task begins, then used to drive implementation.
- Spec-anchored: The spec is kept after the task completes and continues to govern evolution and maintenance of that feature.
- Spec-as-source: The spec is the primary maintained artifact over time. Humans edit the spec; agents regenerate the code. Some tools now stamp generated files with
// GENERATED FROM SPEC - DO NOT EDIT.
If spec-as-source sounds familiar, it should. This is Model-Driven Development trying again, except LLMs remove the constraints that killed MDD: rigid, parseable modeling languages and hand-built code generators. Natural language specs with structured acceptance criteria sit at the abstraction level MDD never found.
The Agentic SDD Tool Landscape
Every major player has now shipped an SDD implementation, and each one takes a different approach.
Google Antigravity
Antigravity, announced in November 2025 alongside Gemini 3, is Google’s agentic development platform. It is an agent-first environment (an IDE plus a standalone Agent Manager, CLI, and SDK) where you spawn, orchestrate, and observe multiple agents working asynchronously across workspaces. Its relevance to SDD is structural. Rather than emitting raw tool-call logs, Antigravity agents generate Artifacts: task lists, implementation plans, walkthroughs, screenshots, and browser recordings that you review and comment on inline, the way you’d comment on a Google Doc. The agent incorporates feedback without stopping execution.
What makes Antigravity different for SDD is that the model decides the rigor level per task. A typo fix skips the implementation plan entirely. A request to refactor the auth system triggers a full plan artifact before any code changes. You can still impose your own fixed SDD workflow via Rules and Workflows, but the default is adaptive spec generation, where the agent chooses the right level of ceremony for the job. Combined with a persistent Knowledge base that captures project patterns across sessions, Antigravity is betting that spec management itself becomes something the agent handles, with the human as reviewer and approver. It supports Gemini 3 models natively alongside Anthropic’s Claude models, with configurable autonomy from review-every-step through fully agent-driven.
GitHub Spec Kit
Spec Kit is the open source, model-agnostic workhorse of the movement. It is a CLI that scaffolds a structured spec, plan, and tasks workflow into your existing repo and works with 30+ agents including Claude Code, Copilot, Cursor, Gemini CLI, and Windsurf. Its “constitution” concept lets teams encode non-negotiable engineering principles that every generated spec and plan must honor. Because it’s a framework rather than an IDE, it fits into whatever tooling you already run. Adoption has been fast, and it has become the default choice for teams that want SDD without vendor lock-in.
AWS Kiro
Kiro is AWS’s dedicated agentic IDE (Code OSS based, launched mid-2025, GA since late 2025) that makes SDD the mandatory front door. Every feature moves through requirements.md, design.md, and tasks.md before code generation. Its main differentiator is EARS notation (Easy Approach to Requirements Syntax), structured requirement patterns like “WHEN [condition] THE SYSTEM SHALL [behavior]” that turn fuzzy intent into testable, machine-parseable acceptance criteria. Kiro also ships agent hooks, event-driven automations that fire on file saves or commits to update tests, refresh docs, or run security scans. Newer releases even apply formal logic and SMT solvers to catch contradictory requirements before generation begins. Kiro is cloud-agnostic; no AWS account required.
Tessl
Tessl goes furthest toward spec-as-source. Its framework teaches any MCP-compatible agent to follow a spec-driven workflow, and its Spec Registry, an open catalog of 10,000+ specs describing how to correctly use external libraries, targets a different problem: agents hallucinating APIs and mixing up library versions. Think of it as npm for specifications. The two-layer idea matters. A process spec alone doesn’t help if the agent still hallucinates the APIs it’s building with.
The Rest of the Field
The ecosystem is deep and moving fast: OpenSpec (lightweight proposal-based change management with delta markers, a good fit for brownfield work), BMAD-METHOD (comprehensive multi-agent workflows), Cursor Plan Mode with AGENTS.md conventions, and Claude Code with spec-driven skills. The pattern most pragmatic teams settle on: vibe-code a spike, distill the result into a spec, then spec-drive the production version.
The Convergence: Why the Two Lineages Are One Discipline
My argument is simple: contract SDD and agentic SDD are the same idea applied at different altitudes, and teams that treat them as one discipline get compounding returns.
An OpenAPI document is a behavioral spec for a service boundary. A Spec Kit feature spec is a behavioral spec for an implementation task. Both are versioned. Both are reviewed. Both are machine-readable enforcement artifacts, not documentation. More important, the contract spec is the highest value input you can feed an agentic workflow. An agent implementing against a Kiro tasks.md that references a merged openapi.yaml has both the what (feature intent, acceptance criteria) and the shape (exact request/response contracts, error taxonomies) pinned down. Contract tests then verify the agent’s output the same way they verify a human’s.
In the agentic era, your contract specs stop being just governance and become agent context. LLMs natively understand OpenAPI, JSON Schema, and Protobuf. Large context windows mean the entire spec surface of a service, or a platform, fits in a single agent session. The better your spec discipline was in 2023, the more leverage your agents have in 2026.
Why Spec-Driven Development Went Mainstream Now
1. Microservices proliferation. In a monolith, your API contract is a function signature enforced by the compiler. In a distributed system with 40 services, there is no compiler, just HTTP and hope. SDD provides compile-time guarantees at the network boundary.
2. The agentic acceleration. This is no longer a trend. Every major AI coding platform has shipped an SDD flavor because unstructured prompting doesn’t survive contact with production systems. Early adopter reports cite much higher first-pass success rates from agents working against structured specs versus conversational prompts, and AWS has documented multi-day features shipping in a fraction of the human time when authored spec-first. The spec is the prompt; the better the spec, the better the output.
3. Platform & API economy maturity. Companies treat APIs as products. Stripe, Twilio, and Plaid didn’t build developer empires on stale documentation. Accurate, interactive API references are table stakes, and SDD is the only methodology that makes this sustainable.
4. Shift-left security. When the spec defines the exact schema of every request and response, spec-aware middleware blocks malformed inputs, unexpected fields, and oversized payloads before they touch business logic. In the agentic era this cuts both ways. Specs also constrain what agents are allowed to build and change, which matters when your workforce types faster than you can review.
5. The trust gap. Survey data shows the paradox clearly: developer adoption of AI tools keeps climbing while trust in their output has fallen. Specs close that gap. They give you an artifact to verify agent output against, instead of reading every generated line.
SDD vs. TDD: Complements, Not Competitors
A common misconception is that SDD replaces Test-Driven Development. It doesn’t. They operate at different altitudes.
| SDD (Spec-Driven) | TDD (Test-Driven) | |
|---|---|---|
| Core question | “Am I building the right thing?” | “Am I building the thing right?” |
| Scope | Integration boundaries, contracts, feature intent | Internal logic & behavior |
| Artifact | openapi.yaml, .proto, spec.md, requirements.md | Unit & integration test files |
| Failure signal | “The output doesn’t match the contract/intent” | “The function returned the wrong result” |
| Best for | Multi-team coordination, API products, agent direction | Complex domain logic, algorithms |
In a mature architecture, you use SDD to define the boundaries and intent (the inputs, outputs, error codes, and acceptance criteria) and TDD to verify the computation in between. The agentic tools are starting to merge the two. Kiro’s EARS acceptance criteria and Tessl’s @test annotations generate test suites directly from specs, making the spec the parent artifact of both code and tests.
The Toolchain: What You Actually Use
| Phase | Contract SDD Tools | Agentic SDD Tools |
|---|---|---|
| Design/Author | Stoplight Studio, Swagger Editor | Spec Kit CLI, Kiro spec mode, Antigravity plan Artifacts |
| Linting/Rigor | Spectral, Redocly CLI | EARS notation, Spec Kit constitutions, Kiro requirements analysis |
| Mocking | Prism, WireMock, Mockoon | n/a (agents implement against the spec directly) |
| Generation | OpenAPI Generator, openapi-ts, Buf | Claude Code, Gemini 3 (via Antigravity), Copilot, Cursor |
| Verification | Schemathesis, Pact, Dredd | Antigravity Artifacts & browser verification, Kiro hooks, contract tests in CI |
| Runtime validation | express-openapi-validator, connexion | Spec-aware gateway policies |
| Documentation | Swagger UI, Redoc, Scalar | The spec itself, now readable by both audiences |
| Knowledge/Memory | n/a | Antigravity Knowledge base, Tessl Registry, AGENTS.md |
Adoption Patterns: Getting Started Without Boiling the Ocean
If you’re in a codebase that’s been code-first for years, full SDD adoption isn’t realistic overnight. Here’s the graduated approach, updated for the agentic era:
Level 1: Spec as Documentation (Week 1). Write an OpenAPI spec describing your existing API surface. Don’t change any code. Generate Swagger UI docs from it. This alone eliminates “where are the docs?” and creates the artifact you’ll build on. A bonus in 2026: agents are very good at reverse-engineering a first-draft spec from existing code. Tessl even ships a command for exactly this.
Level 2: Spec as Linting Gate (Weeks 2-3). Add Spectral or Redocly to CI. Enforce naming conventions, require descriptions and examples. Spec quality goes up without changing your development workflow.
Level 3: Spec as Contract (Months 1-2). Introduce contract testing, Schemathesis or similar against staging in CI. The first time a build breaks because someone changed a response field without updating the spec, the team internalizes the value.
Level 4: Spec-First for New Services (Month 2+). For any new service, mandate spec-first. The spec PR merges before the implementation PR. Mocks spin up immediately; codegen handles boilerplate.
Level 5: Spec-Driven Agents (Month 3+). This is the new frontier. Pick one tool that matches your posture. Spec Kit if you want model-agnostic portability inside your existing repos and agents. Kiro if you want an opinionated IDE with EARS-structured requirements and hooks. Antigravity if you want adaptive, agent-managed specs with multi-agent orchestration and artifact-based review. Tessl if you’re pushing toward spec-as-source or operate in a regulated environment where audit trails matter. Take one feature your team would normally build in two days, spec it, and let the agent attempt it. Measure the supervision burden and output quality against your baseline. Build your own data point rather than trusting anyone’s benchmark, including mine.
Common Objections (and Why They Don’t Hold)
“Writing a spec first slows us down.” It doesn’t. It shifts design decisions from implicit (discovered during code review or production debugging) to explicit (decided during spec review). Total time spent is less; you’re spending it earlier, when the cost of change is lower. In agentic workflows the tradeoff is even more obvious. Thirty minutes of spec writing regularly saves hours of re-prompting and rework.
“Our API changes too fast for a spec to keep up.” If your API changes that frequently, you have a design stability problem, not a spec problem. SDD forces you to confront that instability, which is a feature, not a bug.
“Generated code is terrible.” For boilerplate generators, the key insight remains: you’re generating routing, validation, and type definitions, not business logic. For agentic generation, the quality lever is the spec itself. Vague spec, vague code. Structured acceptance criteria, verifiable code.
“Isn’t this just Waterfall/MDD again?” Partly, and that’s fine. Agentic SDD borrows the rigor of a design phase but embeds it in an iterative loop measured in hours, not quarters. And unlike MDD, there’s no rigid modeling language or hand-built generator to maintain. The “generator” is a frontier model that reads natural language. The overhead that killed MDD is gone. Whether the discipline survives is a fair open question, but the failure modes it prevents are already here.
“We’re not building a public API, so we don’t need this.” Internal APIs are consumed by internal teams, and increasingly by internal agents, who are just as confused by stale documentation and breaking contract changes as external consumers. SDD’s value scales with the number of consumers and the cost of miscommunication. Agents multiply the consumer count.
The Bottom Line
Spec-driven development started as the answer to documentation drift at API boundaries. Today it is also the shared language between humans and AI agents, and the governance layer for a development model where code is increasingly a build output rather than a hand-crafted artifact.
The spec is not documentation. It’s infrastructure. It mocks your servers, generates your boilerplate, validates your deployments, directs your agents, and keeps your documentation accurate by construction. Whether it lives as an openapi.yaml gating your CI pipeline, a requirements.md written in EARS notation inside Kiro, or an implementation plan you’re annotating inside Antigravity’s Agent Manager, the principle is the same one that opened this post: the spec is not a byproduct of development. It is the starting point.
The shift from prompt-centric to intent-centric engineering is already underway. Structure, not better instructions, is what makes agents dependable.
Start with the spec. Everything else follows.
