Spec-driven development helps keep AI coding agents focused on what you asked for. Without a maintained spec, requirements can become scattered across chat history, making them harder to review, update, and hand off.
Writing requirements into a spec first gives you a document to check the finished code against. The tradeoff is size. A spec with more detail than the change needs can cost more review time than it saves.
Copy link to headingWhat is spec-driven development for AI coding agents?
Spec-driven development (SDD) is a workflow where you write a structured, behavior-oriented spec before an AI coding agent writes code. The spec describes intended behavior in natural language and is the shared source of truth for you and the agent. Birgitta Böckeler's SDD taxonomy describes three levels that differ by how the spec is used over time. A spec-first spec guides one task, a spec-anchored spec stays for later maintenance, and in spec-as-source the human edits only the spec.
All three levels start spec-first, and the later levels are optional. The maintenance model is often left open. A spec kept past its task needs an owner and an update rule, or it can drift from the code it describes. SDD is part of agentic coding, the broader discipline of directing coding agents.
Copy link to headingHow is spec-driven development different from vibe coding?
The biggest difference is how intent is captured and reviewed. Vibe coding can leave intent scattered across chat history as the developer accepts changes without closely reviewing the code. SDD leaves a spec you can review before and after the agent runs. Plan mode and instruction files provide other ways to structure the work. Plan mode has the agent propose an approach for your approval before it edits anything, while an instruction file contains standing rules for the repository.
The four approaches differ most in which artifact survives the session and how long it lasts:
The three structured approaches work together. An instruction file sets rules for every change, a spec defines what one change must do, and plan mode works out how to build it.
Copy link to headingWhy does spec-driven development matter for agents?
Spec-driven development gives agents and reviewers a written record of the requirements. An agent can only follow context it can read, and you can only review context you can read. Although tools can resume previous conversations, requirements scattered across chat history can be harder to find and maintain. A written spec addresses that in four ways:
Single place to revise: Edit a changed requirement once in the spec. Its version history shows what changed when a failure needs tracing.
Clean handoffs: A second agent, reviewer, or teammate can pick up the work from the spec without replaying the original conversation.
Up-front risk rating: A detailed feature spec can record a change's risk before an agent starts work, helping determine how much human review it needs.
Shared definition of done: Reviewers, tests, and verification tools check the change against the same acceptance criteria.
A spec makes intent available for review, but it can't make the agent follow it. Checks that must pass every time belong in scripts enforced by the development workflow.
Copy link to headingCore components of a spec-driven workflow
The workflow below has four components. Each answers a different question about the agent's work.
Copy link to headingThe spec file
The spec file records what to build and why as requirements and acceptance criteria rather than implementation decisions. Dedicated spec tools can generate a requirements file, along with separate design or plan files and a task list. Requirements may use user stories with acceptance criteria, sometimes in Easy Approach to Requirements Syntax (EARS). Kiro's feature specs use this structured notation to make requirements testable. In a requirements-first workflow, technology choices follow during planning, while existing technical constraints belong in the spec.
When shipping a web app change, review this file before implementation begins. Generated specs can grow long and repetitive, increasing review time. Write each acceptance criterion so you can verify it through application behavior, automated tests, logs, or other appropriate measurements. For a deployment-status filter, for example, specify which results appear when "Failed" is selected, what clearing the filter restores, and what users see when nothing matches.
Copy link to headingThe plan and task breakdown
The plan and task breakdown connect the spec to code by turning requirements into technical decisions and then into ordered implementation steps. Tools such as GitHub Spec Kit first establish a project constitution, a file of project-wide principles. Each feature then goes through specification, planning, task breakdown, implementation, and convergence checks. The task breakdown produces a dependency-ordered list that guides implementation.
Spec tools can pause for your approval between requirements, design, and tasks, or generate all three in one pass, as Kiro Quick Spec does. Approval gates let you catch a mistaken design before implementation begins. Use them when a mistaken approach would be expensive, and generate the documents together when the direction is already clear.
Copy link to headingThe agent instruction file
An agent instruction file contains standing repository guidance. AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation and is plain Markdown with no required fields. In a monorepo, each package can have its own file. When instructions conflict, the nearest applicable file takes precedence, and explicit user instructions override repository guidance.
In Vercel's January 2026 Next.js agent evaluations, a compressed 8-kilobyte (KB) documentation index in AGENTS.md achieved a 100% pass rate on the evaluation suite. With on-demand skills, which are reusable instruction packages, the agent never invoked the available skill in 56% of cases. Even with explicit instructions to use it, skills peaked at a 79% pass rate. The persistent index pointed agents to documentation they could read as needed and outperformed the skill for general framework knowledge in those evaluations. Put guidance every task needs in the instruction file. Skills can contain specific workflows a developer triggers on purpose, such as a version upgrade.
Copy link to headingThe verification loop
The verification loop checks implementation against the spec after the agent finishes. In GitHub Spec Kit, the convergence check compares the codebase against the spec, plan, and tasks, then appends tasks to address remaining gaps. Implementation and verification repeat until the check reports nothing missing. The change then proceeds to review.
Automated tests catch drift once the spec's acceptance criteria are encoded as tests. Property-based testing checks a rule against generated inputs. This raises confidence without proving correctness, since a loose property can pass even if the behavior remains wrong. A suite written from an incorrect spec can also pass against incorrect behavior, so review the spec as closely as the code.
Copy link to heading4 best practices to implement spec-driven development with coding agents
Four practices help keep spec-driven development practical for daily use. Each addresses a problem that a written spec can't solve on its own.
Copy link to headingScale the spec to the size of the change
A full spec for a one-line fix can cost review time and agent context without providing useful additional direction. A repository instruction study found that adding instruction files increased cost and steps, with marginal, statistically insignificant effects on task success. The study covered instruction files, not feature specs, and found no clear relationship between file length and cost or success. It therefore does not establish the overhead of longer feature specs.
When one sentence captures a well-understood, low-risk change, prompt directly without a separate planning step. Concise context also worked in Vercel's framework evaluations. Compressing the Next.js documentation index from about 40 KB to 8 KB preserved the 100% pass rate on that suite.
Copy link to headingTurn repeated corrections into written rules
Typing the same review comment to an agent twice can indicate that the rule is missing from its written guidance. If you run agents daily, start with the comments you repeat in pull requests, design reviews, and Slack threads.
Add a rule to the file once the agent repeats a mistake, and phrase it as an observable behavior you can check. A rule to run npm test before committing gives the agent a concrete action. A rule to "test your changes" leaves the command and expected checks unspecified.
Copy link to headingTest the instruction file as well as the code
An instruction file can sound authoritative and change nothing about the output. Compare repeated runs of the same task with and without the file to help determine whether it changes behavior. Vercel evaluates its product-design skill with and without the skill loaded for this reason.
Test loading and following separately. An agent that never loads the guidance and one that loads it but breaks a rule need different fixes. A loading check confirms the guidance was available to the agent. A following check scores its output against each rule, helping identify what failed.
Copy link to headingKeep a human at the merge gate
When agent-written pull requests (PRs) outpace your review capacity, keep merge authority with a human. Vercel's AI SDK factory uses agents to reproduce bugs, implement features, and open PRs, while people review and merge every change. Factory agents authored 25 to 35% of the PRs merged each week, and the factory closed 70 to 80% of the issues that were closed.
Rillet's agent workflow writes specs, makes changes, and opens PRs for an engineer to review and merge, tripling their shipping rate in three months.
Copy link to headingHow Vercel supports spec-driven development for agent-assisted teams
Vercel supports version-matched framework context before your coding agent writes code. Afterward, it provides a running application, a code reviewer that uses your conventions, and platform data for comparing the result with the spec.
Copy link to headingNext.js keeps agent instructions version-matched
Outdated framework knowledge can lead a coding agent to rely on its training rather than on your installed Next.js version. Next.js 16.2 and later bundle version-matched documentation. From 16.3, when next dev detects a coding agent, it also writes a managed AGENTS.md block pointing to those docs. Next.js 16.1 and earlier use the legacy agents-md codemod instead. Next.js rewrites only the content between the managed markers and preserves your conventions outside them. To opt out, set agentRules in next.config.ts:
import type { NextConfig } from 'next'const nextConfig: NextConfig = { agentRules: false }export default nextConfigWith the flag set to false, next dev stops managing the block. From Next.js 16.4, the next next dev run also removes an existing block and keeps the rest of the file.
In a monorepo, check where the app lives, because the installed next package may not be visible from the repository root. When enabled, the block points agents to documentation that matches the installed Next.js version, reducing reliance on outdated training knowledge.
Copy link to headingPreview deployments give spec review a running application
A diff shows what the agent changed, but it doesn't establish whether the page behaves as the spec requires. Acceptance criteria describing user-facing behavior are easier to assess in a running app. With Vercel's Git integration enabled, pushing to a non-production branch creates a preview deployment for the change, subject to your project's deployment settings. Each deployment created through Git or Vercel CLI gets a unique deployment URL identifying that immutable deployment.
Check each relevant acceptance criterion against the preview. The branch URL tracks the latest deployment on that branch, making it useful for reviewers checking the newest deployed change. Record the unique deployment URL in review notes so the evidence still points to the version you checked after the agent pushes again.
Copy link to headingVercel Agent Code Review reads your agent's conventions file
When your coding agent and your reviewer follow different rules, review comments can contradict the code the agent was told to write. Vercel Agent Code Review, in Public Beta on Pro and Enterprise plans, detects supported conventions files after you enable reviews for your repositories. It prioritizes AGENTS.md over other supported rules files in the same directory. One edit can therefore affect both what the agent writes and the conventions the reviewer checks against.
Changes to conventions also change review policy. Vercel's product-design review loop treats them that way. It requires evidence and human approval before guidance or checks change and recommends a decision log of what changed and why.
Copy link to headingAI Gateway shows what each agent in the workflow costs
A spec-driven workflow can run several agents, with one drafting the spec, another implementing it, and a third reviewing the result. Without a shared layer, these agents may need separate provider credentials, billing arrangements, and outage handling. AI Gateway's coding-agent setup connects supported coding agents via a single CLI command and provides shared model access with automatic provider fallbacks. Some integrations require additional manual configuration.
Give each agent its own AI Gateway API key to track model spending and set a separate budget for each step. These API key budgets are soft caps. Once a limit is reached, subsequent requests are rejected, but the request that crosses the limit can complete. BYOK provider spending is excluded from metering. Budgets help control model costs, while the spec defines what counts as done.
Copy link to headingAgent resources give coding tools production context
An agent checking its own work without access to deployments or logs may have to infer production behavior. In its final report, an unsupported inference can sound like a verified result. Vercel's agent resources provide documentation for how features should behave and packaged skills for repeatable workflows such as a review checklist. Connecting the Vercel MCP server provides authenticated access to project information, deployment details, and logs. The agent can inspect these while checking a finished change before it reaches your review.
Skills support progressive loading. The agent reads a skill's full instructions when the task calls for them, while standing conventions remain in repository instructions.
Copy link to headingWrite the spec your agent needs and ship it on Vercel
Drift caught at merge time can be expensive to fix, especially when the diff is large and the intent is hard to reconstruct. A spec sized to the change, an instruction file you've tested, and a human merge gate provide shared criteria for checking implementation. Vercel supports the context and review parts of that workflow:
Preview deployments: Connected repositories can give each pull request a running app to check acceptance criteria against, with a unique URL per deployment.
Vercel Agent code review: Once enabled, pull request review detects supported repository conventions files without separate guideline configuration.
AI Gateway for coding agents: Supported coding agents connect through one CLI command, and separate API keys let you track model spending and apply soft budgets.
Managed Next.js instructions: Next.js 16.3 and later point detected coding agents to bundled docs that match your installed version.
Agent resources: Coding tools can read Vercel docs, reuse packaged skills, and inspect deployments and logs through authenticated connections.
Start a project to put your next agent change behind a preview URL, or browse templates for a starting point.
Copy link to headingFrequently asked questions about spec-driven development
Copy link to headingDoes spec-driven development actually work?
Early research is promising, though the evidence is narrow. The SpecFirst study reported relative gains in average test pass rates of 6.9% to 21.3% across four models on 200 program-reconstruction tasks, compared with direct synthesis. The benchmark reconstructed programs from documentation and an executable reference, so it doesn't establish whether the same gains hold for feature development in existing codebases.
Copy link to headingWhat should a spec for an AI coding agent include?
State the behavior the change must produce as acceptance criteria you can verify through the running app, automated tests, logs, or other appropriate measurements. Include constraints the agent must respect and what's out of scope so it doesn't fill gaps with guesses. Implementation choices generally belong in the plan, existing technical constraints belong in the spec, and repository-wide conventions belong in the instruction file.
Copy link to headingWhich tools support spec-driven development?
Two kinds of tools support it. Dedicated frameworks such as GitHub Spec Kit and Kiro provide structured workflows for specifications, planning, and implementation. Spec Kit includes convergence checks, while Kiro offers requirements-first, design-first, and Quick Spec workflows. Plan modes built into coding agents and AI code editors offer a lighter planning step that can accommodate changes too small for a full spec.
Copy link to headingIs spec-driven development just BDD or waterfall again?
No, though it borrows from behavior-driven development (BDD), as described by Dan North in his 2006 article "Introducing BDD". Both express requirements as expected behavior before code. SDD can be iterative when requirements, implementation, and verification evolve together. It becomes more waterfall-like when teams lock requirements before implementation and defer feedback.