Spec-Driven Development with AI Agents

Spec-driven development (SDD) emerged in 2025 as the direct answer to the signature failure of "vibe coding": agents that produce plausible code drifting steadily away from intent, hallucinating APIs, and decaying as the project scales. By 2026 every major coding-agent vendor ships an SDD flavor — GitHub Spec Kit, AWS Kiro, Claude Code planning modes, Cursor, OpenSpec, BMAD, Tessl. The shared core: write down what to build, get it reviewed, and only then let the agent build it — with the written artifact, not the chat scrollback, as the source of truth.

Why Specs Beat Prompts

A conversational prompt is consumed once and gone; a spec is a durable artifact that survives context compaction, session restarts, agent handoffs, and your own memory. Three concrete effects:

  1. Review moves upstream. Reviewing a one-page plan takes minutes and catches design errors before they become a 2,000-line diff. Reviewing the diff alone means design errors are found after the expensive part.
  2. Intent survives long horizons. Multi-hour agent runs compact their context; an on-disk spec is re-readable at full fidelity any time the agent (or a fresh agent) needs to re-anchor.
  3. Acceptance becomes checkable. A spec with explicit acceptance criteria converts "is it done?" from vibes into verification — the bridge to VerificationLoopsForAgenticCoding.

The Canonical Artifact Chain

The converged shape across tools is a three-stage chain, each stage a reviewable file:

  1. Requirements — what and why, as testable statements. Kiro popularized EARS syntax (Easy Approach to Requirements Syntax): WHEN <trigger> THE SYSTEM SHALL <response> — a format both humans and agents parse unambiguously.
  2. Design — how: architecture decisions, data flows, interfaces, trade-offs considered and rejected. This is where a reviewer catches the wrong approach cheaply.
  3. Tasks — an ordered, checkable implementation plan with per-task acceptance criteria, sized so each task is independently verifiable.

Kiro materializes exactly these as requirements.md, design.md, and tasks.md. GitHub Spec Kit (open source, ~111k stars by mid-2026, portable across Claude Code / Copilot / Gemini / Cursor) drives the same chain through /specify, /plan, and /tasks commands with constitution-style project principles layered on top. BMAD adds role-based agent personas (analyst, PM, architect) to generate the artifacts; OpenSpec targets lightweight, vendor-neutral change proposals.

Lightweight SDD Without a Framework

The method is bigger than any tool, and a plain-markdown version captures most of the value:

  1. Brainstorm before specifying. A short back-and-forth where the agent asks clarifying questions and proposes alternatives surfaces the decisions a spec must record. Skipping straight to the spec bakes in the first idea, not the best one.
  2. Write the spec to a file (docs/specs/2026-08-08-feature-name.md), not into chat: intent, non-goals, design, ordered tasks, acceptance criteria.
  3. Human gate. Read it. Edit it. This is the highest-leverage five minutes in the entire workflow.
  4. Execute against the file, one task at a time, each gated by its acceptance criteria — ideally by a fresh agent session that reads the spec cold, which proves the spec actually contains the plan (if a cold reader can't execute it, the plan was living in the chat, not the spec).
  5. Update the spec on divergence. Reality wins; the spec records that it did and why.

When SDD Pays — and When It's Ceremony

SDD earns its overhead when the work is multi-session, multi-file, delegated, or contested — anything where design errors are expensive and intent must survive a handoff. It is pure ceremony for a two-line fix, a rename, or an experiment you'll throw away within the hour; mature practice (see AgenticCodingMaturityModel) includes a crisp skip-the-ceremony rule for trivial tasks. A useful threshold: if you couldn't hand the task to a competent new hire in one paragraph, it needs a spec.

Anti-Patterns

See Also