Spec-Driven Development (SDD) is the practice of treating a software specification as the central artifact of the development cycle, not as a disposable document that turns into a PowerPoint and dies. In 2026, with AI agents writing more and more code, SDD has become the sanest way to ensure that what is generated matches what was asked for, with traceability and automated validation.
This guide explains what SDD is, why it resurfaced in the AI era, how it differs from BDD and TDD, and how to adopt it without falling into bureaucracy.
What changed for SDD to become a central topic
For decades, "spec" was a synonym for a Word document forgotten in SharePoint. The code was the source of truth. Comments and tests documented intent when they were lucky. SDD flips this: the spec is the source of truth, described in a format readable by human and machine (structured Markdown, YAML, JSON Schema, OpenAPI, Gherkin). The code is generated, validated, and maintained from it.
The trigger was the arrival of coding agents (Claude Code, Cursor, Copilot Workspace, Aider, in-house tools built with the Claude Agent SDK). These agents work much better when they receive a clear spec, with acceptance criteria, business rules, and examples, instead of vague requests like "implement this endpoint". The practical consequence: teams that write good specs harvest better code, faster, and with less rework.
Anatomy of a good spec
A useful spec has five sections. 1. Context and objective: what problem it solves, for whom, why now. 2. Expected behavior: a description of the main flow and the edge cases. 3. Contracts: the input schema, the output schema, the error format. 4. Acceptance criteria: a list of verifiable assertions ("given X, when Y, then Z"). 5. Non-goals: what is explicitly out of scope, so it does not become an endless project.
A bad spec is generic, without acceptance criteria, without a schema, and fits any interpretation. A good spec is specific, with a rigorous schema, concrete examples, and clarity about what it should not do.
SDD vs TDD vs BDD
The three disciplines share the same gene: writing the intent before the code. The differences matter. TDD (Test-Driven Development): you write the test before the implementation. Focus on granular verification. It suffers when the test is fragile or when the real intent does not fit into "this return equals that one". BDD (Behavior-Driven Development): you write scenarios in structured natural language (Gherkin). Focus on behavior that is readable by product. It suffers when the scenarios turn into a tangle of step definitions. SDD: you write the complete spec, including contracts, criteria, and examples, before any code. Focus on being a canonical source reusable by humans and AI agents.
In practice, SDD contains BDD (the scenarios become part of the acceptance criteria) and TDD is born naturally from it (each criterion becomes at least one test).
SDD with AI agents
The most visible gain of SDD appears when you ask an agent to implement a feature. With a rich spec, the agent generates code that passes the acceptance criteria on the first try in most cases. Without a spec, the agent fills gaps with assumptions, and you discover the wrong assumptions later.
A mature flow has three steps. First, a human writes or refines the spec with the agent's help (the agent asks questions, proposes forgotten scenarios, suggests edge cases). Second, the agent implements the feature from the spec, with tests derived from the criteria. Third, a human reviews the spec, code, and tests side by side, with comparable diffs.
Popular tools and formats in 2026
The ecosystem has grown. OpenAPI / AsyncAPI: the de facto standard for REST and event-driven APIs. JSON Schema: for validating payloads and configuration. Gherkin (Cucumber): for behavioral scenarios. Structured Markdown with frontmatter: for feature specs readable by agents. GitHub's Spec Kit and similar initiatives: to standardize the format of a spec consumed by copilots. Pydantic / Zod / TypeBox: to generate runtime validators from declarative schemas.
SDD anti-patterns
The four most common pitfalls. 1. A gigantic, outdated spec: a spec without an owner and without a review cycle becomes folklore. Treat the spec as code: it has a PR, it has review, it has versioning. 2. A generic spec without verifiable acceptance criteria. If you cannot write a test from it, it is not a spec. 3. A product-only spec, without technical contracts. Use the spec to align product, engineering, and QA, not just one of the parties. 4. A spec after the code: retroactive documentation does not have the same value. SDD works because the spec comes first.
When SDD is not worth it
SDD is not free. For a disposable script, a one-off migration, or an exploratory spike, writing a spec is overhead that does not pay off. SDD shines in code that will last, be maintained by more than one person, be extended with agents, and that has non-negotiable quality criteria (public APIs, critical modules, integrations with external systems).
SDD at Steply
At Steply, SDD is standard practice in every squad that builds product with AI. Every feature starts with a short spec, written together with the client, containing the objective, contracts, criteria, and non-goals. That spec becomes the agent's briefing, becomes the basis of the tests, becomes the changelog, and becomes the review material. The compound effect is faster delivery with less rework, less arguing about "that is not what I asked for", and code more aligned with what the business needs.