Skip to content

Knowledge base

Spec-driven development

How specifications create stable intent and verifiable work for coding agents.

Written by

Updated:

Agentic Engineering 5

How specifications create stable intent and verifiable work for coding agents.

Spec-driven development

When agents write the syntax, the human’s primary artifact moves from code to intent. You start with an intent, harden it with the agent in plan mode, and let a precise specification fall out of that conversation; the specification, not the source code, becomes the durable asset that holds across every execution loop. A specification carries two things: schemas that pin the shape of the data (OpenAPI, GraphQL, Prisma, JSON Schema) and business rules that carry the behavior. LLMs are far better at satisfying a rigid YAML or JSON schema than a natural-language paragraph, because the structure fixes field names, types, and status codes and leaves almost nothing to interpret.

The workflow that keeps this safe is the Plan-Build-Verify cycle: harden the spec with the agent in plan mode, authorize the agent to build against the approved plan, then verify the output with automated contract or schema tests rather than by eye. The load-bearing caveat is that schemas bound shape and types, not behavior: an OpenAPI schema can say /register returns a 201, but not that a duplicate email must fail before the database write. Behavior lives in acceptance criteria, ADRs, and above all tests, so passing the contract tests proves the shape and never the logic. This is also why natural language fails at scale: English is ambiguous, prompts degrade across model versions, and you cannot write an automated test against an English paragraph, where a typed schema constrains an agent consistently as the model underneath shifts.

Spec-driven development (SDD) is the emerging default for non-trivial agentic work, replacing prompt-and-pray iteration. The creator of the term “vibe coding” declared that era ending a year later in favor of “agentic engineering”: orchestrating agents against detailed specifications with human oversight. The practical workflow starts with a project constitution (mission, tech stack, roadmap), then loops through plan, implement, and validate per feature, with deliberate replanning phases in between; the discipline that makes it robust is routing fixes through the spec rather than patching code in chat, so the specification stays the shared source of intent across sessions and agents (Towards Data Science - From Vibe Coding to Spec-Driven Development (opens in a new tab)).

The discipline often starts one step earlier, with requirements rather than a plan. A single-purpose Requirements Analyst agent, itself generated from one sentence of instruction, interviews you through discovery phases and emits a REQUIREMENTS.md that defines the what and the why but never the how, then hands off to a Solution Architect, a Developer, and a Reviewer, each in its own context; naming the unstated assumptions up front is the step that saves weeks of later correction, because two weeks of coding still cannot buy back five minutes of thinking (Requirements Analyst Agent (opens in a new tab), 2026). Writing the spec down also aligns humans with each other, not only the agent, which is part of why specifications are political (Four Patterns of AI-Native Development (opens in a new tab), 2025).

This is the same move McKinsey describes at the organizational level, the unit of work shifting from story-driven to spec-driven, with product managers iterating on specs with agents instead of writing long PRDs (McKinsey – The AI Software Development Operating Model (opens in a new tab), 2026).

A vendor playbook pushes the same artifact chain past the spec and around the whole lifecycle. Its premise is that once code stops being the bottleneck the constraint moves to the stages on either side of build, plan, review and deploy, which still run at human speed, and the controls there become intractable rather than merely slow, since reviewing every line by hand made sense when a person wrote it. The answer it proposes is that every stage ends by committing an artifact the next stage reads: an intent.md written by the originator in their own terms and corrected by the product owner before it is committed, a spec.md that collapses requirements and design into one working session against skills carrying the organization’s standards, a plan.md produced in plan mode, then the diff with its tests and the PR with its review findings. The chain of commits is itself the audit trail, who asked for what, what the agent produced, and who approved it, so compliance needs no separate record; and the same commits are the triggers, an accepted intent.md starting the design pass, an approved spec.md starting plan mode, and a production anomaly writing the next intent.md (Anthropic – The AI-Native SDLC Playbook (opens in a new tab), August 2026, vendor). Read it as vendor self-description of its own Applied AI practice: the transferable part is one committed artifact per stage and the handoff riding on the commit, not the specific filenames.

The traditional SDLC as a line against the AI-native SDLC as a loop

The shape of the change: a line where one slow loop back is a new release cycle, against a loop running in hours with humans above it instigating, directing and governing. Figure from Anthropic – The AI-Native SDLC Playbook (opens in a new tab), August 2026, reproduced with attribution.

The playbook’s more useful artifact is its adoption order, which it draws as a dependency graph rather than a sequence, because the order to adopt the plays in is not the order the stages run in. Five plays have nothing pointing into them and can be started today in any order: capturing intent, CLAUDE.md, giving the agent a feedback loop, hooks, and plan mode. Everything else waits on those. Skills sit downstream of CLAUDE.md; subagents downstream of CLAUDE.md and the feedback loop; evals downstream of CLAUDE.md, the feedback loop and hooks. Only then do the process plays become reachable: requirements-and-design needs captured intent plus skills, PR review needs evals, CI/CD needs PR review plus plan mode, and closing the loop autonomously sits five layers deep, reachable only once CI/CD and captured intent are both in place (Anthropic – The AI-Native SDLC Playbook (opens in a new tab), August 2026, vendor; the graph carries this, the prose does not). The ordering is worth more than the stage taxonomy above it, because it says plainly that the autonomous maintenance loop everyone wants to demo is the last thing a team earns, not the first thing it installs.

Dependency graph of the playbook's plays, five entry points at the top and closing the loop five layers deep

The adoption order as a dependency graph: the five plays across the top need nothing before them, and every arrow is a prerequisite. Figure from Anthropic – The AI-Native SDLC Playbook (opens in a new tab), August 2026, reproduced with attribution.

The economics of the approach are inverted from traditional coding: planning is the expensive, high-leverage step and execution is cheap. One documented build spent 30 minutes writing a spec and 10 minutes executing it to get 80% of a working 3D application, with every later iteration faster because the spec defined the target; the spec became a living document, with separate iteration and security specs spun off as the project evolved (Ona - Spec-driven design: why planning is the new coding (opens in a new tab)). At fleet scale the same logic hardens into a warning: ambiguous requirements do not just slow you down, they multiply across dozens of parallel autonomous runs, so a spec that survives that environment requires genuine understanding of architecture, integration boundaries, edge cases, and invariants. The spec is product thinking made explicit, which is why strong engineers get more leverage from these tools, not less (The Factory Model (opens in a new tab)).

The tooling has converged on this shape. GitHub’s own Spec Kit runs a four-phase loop, specify then plan then tasks then implement, validating each phase before the next and reframing the shift as moving from code as the source of truth to intent as the source of truth; GitHub reports it works best in greenfield, feature work on existing systems, and legacy modernization (GitHub – Spec-driven development with Spec Kit (opens in a new tab), 2025). Builder Methods’ Agent OS adds the standards layer, discovering coding conventions from an existing codebase and injecting them into spec shaping so generated code matches house rules (Builder Methods – Agent OS (opens in a new tab), vendor); its v3 rebuild strips the framework to only what native plan mode does not do, indexes standards in a manifest so the agent loads only the relevant ones on demand, and interviews the author to capture the reasoning behind conventions that scanning the code cannot reveal (Agent OS v3 (opens in a new tab), 2026).

BMAD Method packages the same discipline as scale-adaptive workflows with 12+ agent personas, adjusting planning depth from a bug fix to an enterprise system (bmad-code-org - BMAD Method (opens in a new tab)). The most radical form pushes the spec into the language itself: Intent is a contract-based language designed for AI to generate and humans to verify, making pre- and post-conditions structural so you audit declarations rather than implementations (Intent (opens in a new tab)). Specifications are increasingly written for agents as much as humans and served as machine-queryable artifacts (an MCP endpoint, an llms.txt, a text/markdown view of any URL) so an agent can audit against them directly rather than parse prose (The Website Specification (opens in a new tab), 2026).

AWS Labs packages the lifecycle version of the same discipline as steering rules for coding agents, one harness-neutral core that installs into seven harnesses, among them Claude Code, Kiro, Codex CLI, Cursor, opencode and GitHub Copilot. Its README lists five phases with 33 stages, from initialization through ideation, inception and construction to operation, plus 14 agents: 11 domain experts, two reviewers and a composer that adapts the workflow. Eleven workflow profiles cover work from a bug fix or proof of concept to enterprise delivery. The request selects the workflow, the agent asks for the decisions it is missing, and it stops at human approval gates before moving on. A 123-event audit trail, persistent state and learned rules keep requirements, decisions, code, tests and operations connected, which answers the problem the project states for itself: ad-hoc AI coding loses context as a project grows (awslabs - aidlc-workflows (opens in a new tab), MIT-0, vendor self-description as of version 2.11.1, October 2026).

The sharpest demonstration of spec-as-executable-target is a verification-first port: take an existing library’s spec and test suite as the fixed goal, point the agent at it, and implement until every test passes. Reco rebuilt JSONata in Go this way, reporting 13,000 lines and 1,778 passing tests in roughly seven hours for $400 in tokens, then validated it in shadow mode against the reference implementation before promoting it to production (self-reported, Reco – We Rewrote JSONata with AI (opens in a new tab), 2026). The test suite is the specification, and whether every test is green against the reference is a check the agent cannot argue with, which is why the author expects surgical AI refactors to become routine.

The same verification-first logic ports whole codebases across languages: extract the existing tests and source into citation-linked specifications with per-file subagents, then run an autonomous loop that implements against those specs until a strictly-compiled target passes, using the citations to pull up the original implementation on demand (Porting software has been trivial for a while (opens in a new tab), 2026).

Two artifacts carry the behavior a schema cannot. Architecture decision records must be machine-enforceable, not just prose: record the why, then back it with a lint or import rule so a violation links the agent straight back to the document to fix it. And executable specifications, BDD scenarios in Cucumber-style Given/When/Then, close the gap spec-driven development otherwise leaves open, how you validate that the product actually matches the spec, since one thing harder than reading AI code is reading AI tests (Capturing Decisions for Humans and AI Alike (opens in a new tab), 2026). The stronger move is to prevent whole error classes structurally rather than catch instances: forbid the BDD suite from importing any database-touching module so a class of mistakes cannot recur, and let the harness itself, git hooks plus CI running the same checks, be the reinforcement loop that stops an agent skipping them (Capturing Decisions for Humans and AI Alike (opens in a new tab), 2026).

Not everyone reads more upfront specification as the answer. Specifying the entire solution before the agent writes a line is waterfall in new clothing, the same mistake the dark-factory promise repeats; the move is to spec the problem, not the solution, naming the constraints, users, existing system shape, and success criteria while leaving the implementation open for the agent to iterate on and defend (How I Use AI to Code (opens in a new tab), 2026). The label itself has blurred through overuse (semantic diffusion, in the established sense), and underneath the branding an agent is still just tools in a loop, so the useful question is not whether you “do spec-driven development” but whether your specs and tests actually constrain the agent (Advanced Context Engineering for Coding Agents (opens in a new tab), 2026).

A practitioner who tried plan-first runs reports the same failure every time. The agents hit cases the plan missed, and the human stops them, rewrites the plan and starts over. The argument against it is the cost of change. When any change costs about as much as the first build, an upfront plan is the expensive option. Iterating story by story, with an architecture review after each one or two, is the cheap one. That practitioner keeps specifications ephemeral instead of persisting them in the repository. For tools he publishes, he tells others to point their agents at his version and build their own, so the finished artifact serves as the specification (LIVE: Uncle Bob on Software Fundamentals in the Age of AI (opens in a new tab), August 2026, practitioner).

The same waterfall charge returns with numbers attached. Scott Logic rebuilt a feature of about 1,000 lines in a hobby web app with GitHub’s Spec Kit, running GitHub Copilot on Claude Sonnet 4.5, and picked a feature it had already built so the specification could be unambiguous. The four steps before implementation, constitution to tasks, produced 2,577 lines of markdown for 689 lines of code, and the whole run took 33.5 minutes of agent time and about 3.5 hours of review. The plan step alone wrote 2,067 of those lines, among them a 406-line research document justifying the UI library every other page of the app already used. The generated code still failed on first start with an obvious bug, a form variable never loaded from the datastore, which no change to the specification could express. A second, smaller increment cost another 2,262 lines of markdown and about two hours of review. Built the usual way, in small prompted increments with functional testing between them, the functionality took 8 minutes of agent time, 15 minutes of code review and 9 minutes of testing and fixes, without bugs, which the review puts at around ten times faster than the Spec Kit run (Scott Logic - Putting Spec Kit Through Its Paces: Radical Idea or Reinvented Waterfall? (opens in a new tab), November 2025).

The structural objection in that review is that markdown makes a weak law. Code is a formal language that can be tested and proved right or wrong, and a markdown specification is not, so making the spec the source of truth places trust in the less formal artifact. Much of what Spec Kit generated was duplication or invented context, such as a design rationale about users wearing gloves trackside that nobody had stated. A specification is also mostly a point-in-time tool that nobody revisits once the feature ships, while the architecture and design decisions behind the code, the why that code cannot carry, stay worth recording. And since agents make code cheap to produce and to throw away, a sequential specification pipeline gives up the faster iteration they make possible. The review names its own caveats: Spec Kit was immature, with open questions on evolving specs and folding in bug fixes, and an engineer who reviews and steers every increment may not be its target user (Scott Logic - Putting Spec Kit Through Its Paces: Radical Idea or Reinvented Waterfall? (opens in a new tab), November 2025).

The continuous delivery community’s version of a lightweight, replan-as-you-go practice puts a clock on it. Specifying one change should take under 15 minutes, and a spec that takes longer marks a change to split, since each spec covers one thin vertical slice such as a single scenario. Before any code, the agent reviews intent, scenarios, constraints and acceptance criteria as one set for vague wording, missing cases, conflicting terms and a hypothesis nobody can measure, because this is the last point where a change costs almost nothing. One useful critique asks the agent for scenarios that two different implementations would both pass, since such a scenario pins nothing down. For larger work the guide describes a discovery loop in four phases. The human frames the intent with a rough measurable hypothesis. The agent interviews in rounds of three to five pointed questions, and the human answers with raw context for the agent to structure later. The agent drafts the specification and then critiques its own draft for vague constraints and missing edge cases. The difference from turn-by-turn prompting is where the iteration happens: the spec is stable before any implementation agent starts, instead of the code being corrected afterwards (MinimumCD.org and DojoConsortium.org - Agent-Assisted Specification (opens in a new tab), as of September 2026).

One limit survives even that lightweight practice: specs are indispensable but they are not proof of correctness. In practice they are incomplete, hypothesis-based, and sometimes wrong, and the more confidently they are written the more dangerous unquestioned implementation becomes. The source of truth in a mature agentic pipeline is programmatic tests and fitness functions; the spec describes intent, tests check reality, and where the two diverge, reality wins (Dark Factory Patterns).

Resources

Lifecycle playbooks

Specification practice