Spec-Driven Development With AI Coding Agents: A Practical Guide

Tools like Claude Code, GitHub Copilot, Cursor and Windsurf now produce, restructure and test code much faster than any person could. Speed without precision, though, tends to become a liability. Many teams using these tools work in a loop of prompting, receiving output, patching errors and prompting again, and the loop gets worse as the codebase grows. The cause usually isn't the model. It's that nobody has a disciplined way of telling the agent what is wanted.

Spec-driven development (SDD) is one answer. It treats a structured specification as the main product of the delivery process: the document from which code is derived, checked and governed.

The conceptual foundation

How vibe coding fails

"Vibe coding" means describing the desired result conversationally and steering the output with informal follow-up prompts. It works well for isolated tasks, quick prototypes and single-session experiments. It fails badly at scale, and the reason is worth understanding.

Context decay

Every session happens inside a context window, the limited amount of information the agent can reason over at one time. During vibe coding, the project's state exists only inside the chat history. As the conversation lengthens, early architectural decisions, security constraints and library choices drop out of the window. The agent then substitutes plausible alternatives, often without saying so. That is context decay.

Its typical symptom is implementation drift: a slow separation between what the agent believes it's building and what the business originally asked for. The code passes its tests, works on its own and looks right, yet breaks structural or business rules set earlier. In enterprise systems this is the sort of defect that's hardest to diagnose and costliest to fix.

The core idea

SDD rests on one architectural principle: the specification is the primary artifact, and the implementation is derived from it. That's more than a workflow tweak. It turns the traditional model upside down, where code comes first and documentation trails behind.

In this approach the specification is machine-readable, version-controlled, living and executable. It acts as a contract between human intent and agent execution, and the agent works within the contract's limits rather than guessing. A precise contract yields predictable output, while an ambiguous one yields variance. In short, you can't control what an agent builds until you've defined exactly what you want built.

Six elements of a machine-readable spec

A specification meant for an agent has to get past the ambiguity of natural language. The six elements usually listed as necessary to stop an agent from making unwanted assumptions are:

1. Outcomes, the results the work should achieve.
2. Scope, including what is explicitly left out.
3. Constraints, such as required technologies, security rules and performance limits.
4. Decisions already made, so they aren't reopened.
5. Tasks, the work broken into steps.
6. Verification criteria, the checks that show a task is done.

The SDD workflow

Four phases with human gates

The workflow has four sequential phases, and each includes a point where a person must intervene. These human checkpoints aren't bureaucracy. They stop errors from compounding downstream, and skipping one to "move faster" tends to have the opposite effect.

Phase 1, specify. The developer states the intent at a high level, and either the agent or the developer alone fleshes that out into a structured functional specification: user journeys, business outcomes, acceptance criteria and explicit scope boundaries. The person's job here is architectural review, reading the result for hallucinations, omissions and misreadings before any planning starts. Hold off on phase 2 until phase 1 is free of ambiguity: a vague specification rarely leads to a vague implementation, but to one that is sure of itself and wrong.

Phase 2, plan. Once the specification is approved, the agent drafts a technical plan that covers architecture decisions, data models, API contracts and technology choices. The plan encodes organizational constraints such as "persist data in PostgreSQL" or "every API endpoint requires JWT authentication." Human review at this point catches architectural mistakes before they're written into thousands of generated lines.

Phase 3, task breakdown. The approved plan is cut into small tasks that can each be tested independently. Granularity is probably the most underrated variable in SDD. A task should be implementable and verifiable in one agent run, and if it forces the agent to juggle more than about three separate concerns, it's too big. A well-split list also works as a scaffold for test-driven development, since every task has a clear success condition before work begins and the project gets frequent validation points.

Phase 4, implement and verify. The agent writes code task by task, with focused output that can be audited and traced to a specific requirement. This phase is paired with a verifier pattern, where one agent generates code and a second agent or an automated test suite checks it against the acceptance criteria.

Updating the spec in both directions

One of the most important practices, and one often broken, is bidirectional updating. Suppose that during phase 4 the agent makes a decision the specification doesn't cover, such as picking a library for performance reasons or handling an edge case in an unobvious way. That decision should be written back into the specification right away.

If it isn't, "specification debt" builds up: documented intent and actual behavior drift apart. That divergence turns a living specification into an outdated file nobody trusts and eventually nobody reads, and it becomes useless exactly when it's needed most, during later AI-assisted changes. The rule is simple: when the implementation departs from the spec, update the spec now, not next sprint. Spec debt grows faster than technical debt, since it poisons what every later generation run starts from.

Persistence artifacts and the project constitution

Why agents need a constitution

A coding agent has no memory between sessions. Each new session starts with only what you put into its context. With no persistence mechanism, every session is a blank slate, with no awareness of your security standards, naming conventions, banned libraries or architectural decisions.

The "project constitution" is a set of persistent artifacts that solves this. These are structured files committed to the repository next to the source, giving the agent the institutional knowledge to work like an informed team member and not an outsider.

The core artifacts

AGENTS.md or CLAUDE.md, the operating manual. This is the most important one: a README for the agent, read at the start of each session to learn how this particular project works. It should be written for machine parsing before human readability. An effective file covers three kinds of information:

• Operational details the agent can't infer: exact build commands with flags, how tests are run, linter configuration and environment variable names.
• Naming and structural conventions: what each directory is for, how files are named and how modules are organized.
• A severity hierarchy for agent actions, using a consistent signal system. Always do things like linting, running affected tests and following naming conventions. Ask first before changing database schemas, adding dependencies or altering API contracts. Never commit secrets, edit .env files or change authentication logic without review.

SPEC.md, the living specification. This is the authoritative description of what the system should do. It isn't a historical record. It reflects current intended behavior, including every decision made during implementation. If the code diverges from SPEC.md, the file is updated, and when requirements change, SPEC.md is edited first and the implementation follows.

PLAN.md, the architecture record. It holds architectural decisions, technology choices and system-wide constraints. It answers "why was it built this way?", supplying the reasoning that stops later agents and later engineers from undoing carefully made choices.

Tool-specific configuration files. Each tool has its own convention for rule files. Cursor's .mdc format deserves a mention because it combines Markdown with YAML front matter to attach rules to file glob patterns. Backend rules, such as authentication requirements and database access patterns, can then apply only when the agent works on backend files, keeping irrelevant context out of its working memory during frontend work.

Multi-agent orchestration

Why one agent isn't enough

A single agent in charge of a whole enterprise codebase hits a hard limit: the context window. A large system with 100,000+ files, several services, intricate data flows and a full test suite can't fit into one agent's context. The agent has to choose what to include, and those choices create blind spots.

The idea behind multi-agent orchestration is to copy how a strong human team operates, with defined roles, tidy handoffs and one specification everyone treats as the truth.

Three roles

Coordinator. This agent plays project manager and architect. It holds the global picture, meaning the full specification, the task list and the architectural constraints. It breaks the specification into sub-specifications, hands them to implementors, watches for conflicts between parallel workstreams and makes sure finishing one task doesn't undermine the architecture as a whole.

Implementor. Implementors are specialists. Each gets a sub-specification covering one task or a small cluster of related ones, and works in an isolated Git worktree so it can't collide at file level with other implementors running in parallel. It knows nothing about work outside its assignment and isn't responsible for it. That isolation isn't a limitation. It's what makes the output deterministic, testable and reviewable.

Verifier. The verifier has the opposite goal. Where the implementor tries to finish the task, the verifier tries to find where the result fails the specification. The adversarial arrangement is borrowed from formal verification and security research, and it's among the strongest quality mechanisms SDD offers. The verifier tests output against acceptance criteria and looks for functional gaps, security policy violations, breaches of performance constraints and drift from the spec. On finding a discrepancy it doesn't patch the code. It reports back to the coordinator with a structured description tracing the failure to a particular requirement.

For production systems this adversarial verifier shouldn't be optional. An agent that writes and checks its own code will nearly always judge its work acceptable, and the verifier's value comes from being independent of the implementor and opposed to it.

Parallel execution with worktrees

One of the most valuable abilities of multi-agent SDD is parallelism: several implementors on different features or services at once, each in its own worktree. For large projects with few dependencies between tasks, delivery time can shrink dramatically.

Git worktrees make it possible. Each agent has a separate working directory attached to the same repository, so file conflicts are avoided while the coordinator watches progress across all workstreams from one place. After the verifier approves, the coordinator merges finished worktrees and keeps the main branch clean.

Diagrams as code

Why diagrams belong in the spec

Architecture diagrams have traditionally been drawn after the fact, as documentation of code that already exists. In SDD they come upstream, as part of the specification and plan and before any implementation.

The reason is diagnostic. Asking an agent for a valid Mermaid diagram from a specification forces it to reason explicitly about data flow, service dependencies and state transitions before it writes code. A messy or incoherent diagram at this stage is a dependable sign that the specification is ambiguous or structurally flawed, and fixing such problems in a diagram costs far less than fixing them in deployed code.

Formats

Text-based formats, especially Mermaid and D2, beat binary images for this purpose. They can be versioned and diffed, and agents can read them directly. They can also be updated as the specification evolves, which keeps structural documentation and implementation in step.

Three maturity levels

Practitioners have settled on three levels of SDD. They aren't a ladder every team must climb in order. They're different trade-off profiles for different contexts, and knowing which suits your situation comes before any rollout.

Level 1, spec-first. A thorough specification is written for one task. Once the implementation is complete and verified, the spec is treated as disposable: it may be kept for reference but isn't maintained. It suits isolated features, one-off migrations and experiments where Level 2's upkeep isn't justified. Proponents say this level captures roughly 60% of SDD's value at a fraction of the cost, which makes it a sensible starting point for newcomers. Use it for a bounded new feature with clear acceptance criteria, no cross-service dependencies and delivery measured in days.

Level 2, spec-anchored (the recommended default). The specification is an equal partner to the code across the project's life, and both are maintained. When requirements change, the spec changes first, and when the implementation diverges, the spec is updated at once to record real behavior and the reasoning. That looks like double maintenance, but in practice it lowers total cost: it prevents context decay across sessions, lets new team members (human and AI) onboard reliably, and makes later AI-assisted changes much more dependable. It's the baseline for production systems, team projects and anything expected to keep evolving.

Level 3, spec-as-source (experimental). The specification is the only primary artifact. Code is treated like compiled output, regenerated on demand and never edited by hand. It's the theoretical endpoint of SDD, with engineers maintaining specifications and AI maintaining implementations. It has an unsolved problem, determinism. Identical specs may yield syntactically different, though functionally equivalent, code from run to run, which makes diffs, debugging and review very hard. Treat it as experimental. It might suit greenfield projects with highly complete specifications, strong AI governance and tolerance for immature tooling, but it isn't recommended for critical production systems as of 2026.

Playbooks by role

Engineers and architects

The engineer's main skill shifts to context engineering. Writing correct syntax is something agents do at machine speed, so the engineer's value lies in defining precise architectural context, curating what the agent can see and checking that its output matches the system's structural intent. That covers writing good AGENTS.md and SPEC.md files, setting library governance rules (an explicit list of allowed and prohibited dependencies), stating security and compliance requirements in machine-readable form, and structuring tasks so concerns stay separate.

A starting routine for engineers:

1. Ahead of any AI-assisted feature, create or refresh SPEC.md so that it holds the six elements described earlier.
2. Review AGENTS.md and confirm that the build commands, test patterns, naming rules and severity hierarchy still reflect reality.
3. Ask the agent for a Mermaid architecture diagram before implementing, and review it for coherence.
4. Break work into atomic tasks, and split any task that needs more than one focused generation cycle.
5. After each task, check it against the spec's acceptance criteria before calling it done.
6. Whenever the code and SPEC.md disagree, fix SPEC.md on the spot.

A constraints block is a handy template to include in any spec. It lists the tech stack (every required technology), banned libraries (spelled out), security requirements (how users authenticate, which encryption is expected, how data may be handled), performance limits (target latency and throughput), testing requirements (coverage threshold and required test types) and architectural patterns (those required and those to avoid).

Technical product managers

From PRDs to behavioral briefs. A classic product requirements document assumes human engineers who will read it, argue about it and implement it using their own judgment. In SDD, a TPM's output has to be a behavioral brief: a machine-readable account of how the product should respond to specific user needs, with the precision agent execution demands.

The difference is more than style. A PRD can say "improve the checkout experience." A behavioral brief has to state what the current checkout flow does, which user pain points it causes, which behavioral changes count as improvement, how success is measured, which edge cases must be handled and what the system must never do.

The prototype loop. SDD lets a TPM shorten the usual design-to-engineering handoff. Instead of waiting for a designer's mockups and then for an engineer to build them, the TPM can generate interactive prototypes straight from a behavioral brief and judge working behavior rather than static screens. If the prototype misses the vision, the spec is updated and the agent regenerates the implementation, so the feedback loop runs on the specification and not on code. That removes several translation points (PRD, then design handoff, then engineering handoff) where intent usually leaks away.

CTOs and engineering leaders

Governance. A CTO's priority in an agent-first organization is a governance framework that lets AI speed up delivery without compromising quality, security or compliance. SDD supplies the control layer, but only with organizational discipline. Three mechanisms matter at scale:

• Version control for specs. SPEC.md, PLAN.md and AGENTS.md live in the same repository as the code and go through the same review and approval.
• Audit trails. Each AI-generated change should trace back to a particular specification requirement, which isn't optional in regulated industries.
• Human gates at each phase transition. Nothing moves autonomously from specify to plan to implement without approval at every step.

CTOs should also evaluate AI coding tools against this framework, asking how well each supports persistent rule files, review gates, traceability and multi-agent workflows.

Measuring return. Organizations adopting SDD often report that development feels slower for the first two to four weeks, because engineers spend time on specifications instead of diving into code. The observation is correct but the interpretation misleads. Specification work isn't new overhead. It's work that used to be done informally, inconsistently and after implementation, when it cost most. The metrics that show the real return sit downstream:

• time from requirement to production-ready code, meaning verified, reviewed and deployed and not merely written,
• rework percentage, the share of finished features that must be redone because requirements were misunderstood,
• context recovery time, how long a developer or agent needs to become productive on code untouched for 30 days, and
• defect escape rate, the share of defects caught in specification review compared with after deployment.

Teams with mature SDD practice reportedly see rework fall by 40-60% and context recovery shrink sharply, since the specification supplies the context that would otherwise take hours of code archaeology. Those figures come from practitioner reports and not controlled studies, so measure your own baseline.

Intent drift

What it is

Intent drift is the slow gap that opens up between the business's original requirements and the behavior of the code in production. It isn't new to AI-assisted work and is one of software engineering's oldest problems, but coding agents add a dangerous accelerant. They optimize for plausibility and passing tests, not for business alignment. Ask one to build payment processing and it will write code that passes every test and covers every specified case. If the specification is incomplete or stale, the agent fills the gaps with statistically likely defaults from its training data. Those are fine for generic systems and potentially disastrous for your particular business rules. The worst drift is the kind noticed only when it costs a customer, a compliance audit or a production incident, because agents are very good at producing code that looks correct while being subtly off.

Defenses

• A living specification. The first defense is a spec updated in real time as decisions are made. Every departure from SPEC.md, no matter how small or well justified, is recorded immediately, so the file always describes current behavior and not original intent.
• Adversarial verification. The verifier pattern doubles as drift detection. Checking output against the spec at each task catches drift at the smallest possible grain, before it compounds over several implementation cycles.
• Specification coverage tracking. More advanced setups track the fraction of requirements that have automated, verifiable tests. A requirement without a test can drift unnoticed, and working toward full coverage is test-driven development applied at the requirements level.

A minimal AGENTS.md

A production-ready AGENTS.md can be short. At minimum it should include a one-paragraph description of the project, the exact commands to build, test and lint, the conventions for naming and directory layout, the always, ask-first and never lists, pointers to SPEC.md and PLAN.md, and the library governance rules. Adapt each part to your stack and your organization's requirements.

Where this leaves you

Spec-driven development isn't a passing fashion or a small improvement to existing habits. It changes what engineering work consists of. With coding agents the bottleneck in delivery is no longer how fast syntax gets produced. It's how precisely intent is defined. The specification is the product, the code is what implements it, and in agentic software construction the specification is the engineer's most important deliverable.