What Is Spec-Driven Development?
Spec-driven development is a way of building software in which a written specification, covering requirements, behavior and constraints, comes before the code and acts as the source of truth. With AI coding agents, the spec becomes the main input the agent builds from.
Teams write and refine the spec, turn it into a plan and tasks, let people or agents implement, then check the result against the spec. Spec-driven development trades upfront writing time for clearer intent, fewer rewrites and a review that has something concrete to check against.
Spec-driven development in 2026: is the spec a prompt or a contract?
Spec-driven development started 2026 as an answer to vibe coding: write down what you want before an agent builds it. By spring it had named levels of rigor, its own toolkits and a place on the Thoughtworks Technology Radar.
Cheap code moved the hard work, it didn’t remove it. Effort went upstream into deciding what to build and downstream into checking what got built. A spec sits at both ends, as the agent’s instructions before coding and as the reviewer’s baseline after.
Thoughtworks teams also found a failure mode in spec-driven development. Specs and project context kept growing until agents lost the thread, and the teams that got value kept specs lean and kept review in the workflow.
2026 spec-driven development highlights
- Practitioners named levels of rigor. A practitioner guide described spec-first, spec-anchored and spec-as-source, with a workflow of specify, plan, implement and validate (January 2026, arXiv).
- Thoughtworks put Spec Kit in Assess. Technology Radar Volume 34 found that a "constitution" with scope, domain context, coding standards and repository structure kept agents inside architectural boundaries (April 15, 2026, Thoughtworks).
- Specs bloated. The Thoughtworks Spec Kit blip also reported instructions growing until context rot began, and one team moved reusable guidance into skills to keep the main instructions lean (April 15, 2026, Thoughtworks).
- Review earned its place. One Thoughtworks team ran spec, plan, tasks, coding and review, and found issues earlier (April 15, 2026, Thoughtworks).
Prompt or contract in 2027?
A spec read only by the agent is a long prompt. A spec that review checks every PR against is a contract, and only a contract tells you whether the code does what was asked.
Our verdict: in 2027 the teams that get value from spec-driven development will treat the spec as the contract and measure each PR against it. Teams that stop at writing specs will have better prompts and the same missing requirements.
What spec-driven development needs next: the 2027 outlook
- Specs get shorter and sharper. Expect requirements written as checkable statements, with constraints and non-goals, in place of long narratives an agent only half follows.
- Every PR links its spec. A PR with no linked requirement can’t be checked against one, so expect the link to become part of the definition of ready.
- Requirement gaps become review findings. Missing cases should show up on the PR, next to the code, not in QA weeks later.
- Qodo has a Spec Agent (Research Preview) that reads the spec linked to a PR and reports each missing requirement next to the code as a "📎 Requirement gap" finding.
Write the spec for the agent, and check the PR against it, or the spec stays a long prompt.
How spec-driven development works
- Agree on project principles. Spec Kit calls this a constitution: scope, standards and structure that apply to every task.
- Write the spec. Capture user stories, requirements and acceptance criteria.
- Clarify open questions. Resolve gaps before anyone writes code.
- Write a technical plan. Choose the approach, data model and interfaces.
- Break the plan into tasks. Small tasks are easier for agents and reviewers.
- Implement. People or coding agents build each task.
- Validate against the spec. Check that the merged code does what the spec says.
Levels of spec-driven development
| Level | What the spec does | Who edits code | Main risk |
|---|---|---|---|
| Spec-first | Written before coding, then left alone | People and agents | The spec goes stale after release |
| Spec-anchored | Kept and updated as the code changes | People and agents | Updates get skipped under deadline |
| Spec-as-source | The spec is the main artifact; code is generated from it | Mostly agents | Hard to review generated code at volume |
Source: levels as described in the January 2026 practitioner guide (arXiv).
Spec-driven development vs TDD, BDD and vibe coding
Spec-driven development vs test-driven development
In test-driven development, tests are the spec: you write a failing test, then the code. Spec-driven development writes the intent in prose first, and tests are one way to check it.
Spec-driven development vs behavior-driven development
Behavior-driven development writes behavior as Given, When, Then scenarios. Given, When, Then scenarios can be part of a spec, and many spec templates include them.
Spec-driven development vs vibe coding
Vibe coding means prompting an agent and accepting what comes back, with no written contract. Spec-driven development adds the contract, so a reviewer can say whether the result is right.
What makes a good spec
- Testable requirements. Each requirement can be checked as met or not met.
- Explicit non-goals. The spec says what the change won’t do, so agents don’t overbuild.
- Constraints. The spec names security, performance and compatibility limits.
- Acceptance criteria. The spec lists the conditions a reviewer checks before merge.
- Links to tickets. The spec, the ticket and the PR point at each other.
- Version control. The spec is stored next to the code, or linked from the PR, so it changes with the code.
Spec-driven development tools
| Tool | Type | Where specs live |
|---|---|---|
| GitHub Spec Kit | Open-source toolkit for agent workflows | Markdown files in the repository |
| Kiro | Agentic IDE with built-in specs | Spec files in the project |
| Plain Markdown specs | Convention, no tool | docs/ or spec folders in the repository |
| Confluence or Notion pages | Documentation tools | Pages linked from tickets or PRs |
Risks of spec-driven development
Spec drift: the code changes and the spec doesn’t, so the spec stops being the source of truth.
Instruction bloat: specs and agent instructions grow until agents lose track of what matters, as Thoughtworks teams reported in 2026.
Specs nobody opens at review: the spec sits in a wiki, and the reviewer reads only the diff.
False confidence: a detailed spec can make a team trust generated code it hasn’t checked.
Qodo’s take: a spec only works if review checks it
Spec-driven workflows include a validate step, but in practice it often means tests passing. Nobody compares the merged code to the spec line by line, so missing requirements ship quietly.
You shouldn’t review code with the same tool that wrote it. The agent that read the spec is the wrong judge of whether it followed it, so the check needs an independent reviewer.
Qodo is the best AI code review platform to close the loop in spec-driven development because its Spec Agent (Research Preview) compares each pull request with its linked specification in Confluence or Notion and reports requirement gaps as review findings.
Qodo isn’t focused on test generation, even though some authors still point to it as a key strength. In our experience, Qodo is best at AI code review and code governance for checking that what agents build matches what the spec asked for.
Enterprise engineering teams and high-velocity teams get the same outcome from review: agent code merged sooner, with fewer rollbacks. Enterprise engineering teams get one set of rules enforced across many repositories and coding agents once Rule enforcement is on, and the Spec Agent (Research Preview) checks each PR against its linked spec.
High-velocity teams get the rule files they already have, such as AGENTS.md and CLAUDE.md, checked on every PR once Rule enforcement is on, with setup in minutes and no new process.
Qodo reports requirement gaps against the linked spec
The Spec Agent (Research Preview) runs when a PR with a linked specification is opened or updated, and reports a requirement gap finding where the PR doesn’t fully implement a requirement in that spec (last checked November 2026, Qodo’s docs). See Qodo’s post on how Qodo uses linked specs to catch missing requirements.
Qodo finds the spec through the PR or the ticket
Qodo reads a Confluence or Notion link in the PR description, or follows one hop through a linked Jira or Linear ticket (Research Preview, Confluence and Notion docs). Qodo’s ticketing integrations also bring ticket context from Azure DevOps, Monday.com, GitHub Issues and GitLab Issues.
Qodo works where Kiro specs are written
Qodo’s Kiro power gives the Kiro agent Qodo’s review and codebase skills, so a Kiro agent can review its changes and resolve Qodo findings before a PR is opened (last checked November 2026, Qodo’s docs). See Kiro code review.
Qodo example: the acceptance criterion the agent skipped
Context: an organization like a fintech team that writes specs in Confluence and links them from Jira tickets.
Problem: a coding agent implemented the main path of a refund flow. The spec also required an audit log entry for partial refunds, and the agent skipped it.
How Qodo helped: the Spec Agent followed the Jira ticket to the Confluence spec and posted a requirement gap finding on the PR.
Outcome: the author added the missing case before merge. The requirement gap and its resolution are visible in the PR’s findings.
Ways to verify code against a spec
| Method | What it checks | Effort | Limits | Best for |
|---|---|---|---|---|
| Reviewer reads the spec | Any requirement | High | Slow, and easy to skip under load | Small, high-risk changes |
| Acceptance tests | Requirements written as tests | Medium | Only covers what someone automated | Stable, well-defined behavior |
| BDD scenarios | Behavior in Given, When, Then form | Medium | Needs upkeep as the spec changes | Product-facing features |
| Agent self-check | The agent compares its own output with the spec | Low | Same system judges its own work | Early drafts |
| Qodo Spec Agent | Each PR against its linked spec, as requirement gap findings | Low | Research Preview | Teams with specs in Confluence, Notion or tickets |
Qodo features in this table were checked against Qodo’s documentation as of November 2, 2026.
FAQ
Spec-driven development is a way of building software in which a written specification comes before the code and acts as the source of truth. With AI agents, the spec is the main input the agent builds from.
Test-driven development uses tests as the spec and writes them first. Spec-driven development writes intent in prose first, such as requirements and acceptance criteria, and uses tests as one way to check it.
Common options include GitHub Spec Kit, Kiro’s built-in specs, plain Markdown spec files in the repository and Confluence or Notion pages linked from tickets.
Spec-driven development works well with AI coding agents, because agents follow a clear spec better than a short prompt. Thoughtworks teams reported in 2026 that specs need trimming, because growing instructions led to context rot.
Use acceptance tests for what can be automated and review the rest against the spec on every PR. Qodo’s Spec Agent (Research Preview) compares each pull request with its linked spec and reports requirement gaps as findings. See requirements compliance in code review.