Malhar Ujawane

Blog

Explainer·(updated October 31, 2026)

What is spec-driven development? Specs for AI coding agents

Spec-driven development: write a spec before an AI agent writes code, then treat it as the source of truth. How Spec Kit and Kiro do it, and where it breaks.

What is spec-driven development? Specs for AI coding agents

Spec-driven development (SDD) is a way of working with AI coding agents where you write a specification of what to build, and why, before the agent writes any code, then use that spec as the source of truth for planning, tasks, implementation and review. The agent generates most of the artifacts; your job is to steer and verify them at each checkpoint. It’s the deliberate opposite of vibe coding, where intent lives only in a chat history.

Where did spec-driven development come from?

Writing requirements before code is as old as software engineering. What’s new is who reads the spec. In 2025, two tools put the idea at the center of agentic coding.

Kiro is an AI IDE built on Code OSS that turns one prompt into three documents: requirements (user stories with acceptance criteria in EARS notation), a design document generated from the codebase and the approved requirements, and a sequenced task list linked back to the requirements. Kiro’s launch post frames it as getting vibe-coded prototypes into production.

GitHub open-sourced Spec Kit on September 2, 2025. It’s a CLI (specify) that sets up a project for an agent such as GitHub Copilot, Claude Code or Gemini CLI, then drives four phases through slash commands: specify, plan, tasks, implement. GitHub’s post puts the motivation in one line I agree with: we treat coding agents like search engines “when we should be treating them more like literal-minded pair programmers.”

How does spec-driven development work?

Using Spec Kit’s phases as the reference:

  1. Specify. You describe what you’re building and why: users, journeys, what success looks like. No stack, no architecture. The agent expands it into a detailed spec.
  2. Plan. Now the technical side: stack, architecture, constraints, compliance rules, performance targets. The agent writes a technical plan that respects them.
  3. Tasks. The agent breaks spec and plan into small tasks, each something you can implement and test on its own. GitHub compares this to test-driven development for the agent.
  4. Implement. The agent works through the tasks, and you review focused changes instead of a thousand-line dump.

The checkpoint between each phase is the point. GitHub’s post says “your role isn’t just to steer. It’s to verify.” Spec Kit also adds a “constitution”, a set of project-wide principles the workflow checks every change against, which plays the same role as an AGENTS.md file or Kiro’s “steering” documents.

Why do specs help an AI agent?

Because a vague prompt makes the model guess. GitHub’s example is “add photo sharing to my app”, which leaves the model to invent thousands of unstated requirements; some guesses will be wrong, and you find out late. A spec moves those decisions to the front, where they’re cheap to change.

This is really context engineering with a paper trail. The spec, plan and task list are the context the agent needs for each step, written down once instead of retyped into every prompt. They also give a second agent, or a second human, something to check the work against. From a delivery-lead seat, that’s the part I’d sell to a team: the spec is the artifact a product owner can read and sign off, which code never was.

What are the levels of spec-driven development?

Birgitta Böckeler’s review of Kiro, Spec Kit and Tessl on martinfowler.com is the clearest analysis I’ve read. She found the term already overloaded and split it into three levels:

  • Spec-first. Write a careful spec, use it for the task at hand, then it’s done. Every SDD tool she looked at does at least this.
  • Spec-anchored. Keep the spec after the task and edit it as the feature evolves, so it stays true.
  • Spec-as-source. The spec is the only thing humans edit; code is generated from it and marked do-not-edit. Tessl was exploring this, with a one-to-one mapping between spec files and code files.

Most of what people call SDD today is spec-first. The bigger claims, that “intent is the source of truth” in GitHub’s phrase, need spec-anchored or spec-as-source, and that’s where the hard questions start.

What does an executable spec look like?

The most useful property a spec can have is that a machine can check it. Here’s a tiny example: a Markdown spec with requirement IDs and example tables, and a script that turns each example into a check against the code an agent wrote.

# spec_check.py: turn the examples in a Markdown spec into checks, traced to requirement IDs.
# Python 3 standard library only.
import re

SPEC = """
## R1 Slugs are lowercase ASCII words joined by hyphens
| input              | expected          |
| Hello World        | hello-world       |
| Café au lait       | cafe-au-lait      |

## R2 Runs of punctuation and spaces collapse to one hyphen
| input              | expected          |
| a  --  b!!         | a-b               |

## R3 Empty or symbol-only input returns "untitled"
| input              | expected          |
| !!!                | untitled          |
"""

def slugify(text):              # what the agent wrote from the spec, first attempt
    import unicodedata
    text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode()
    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")

req = None
for line in SPEC.splitlines():
    if m := re.match(r"## (R\d+) (.*)", line):
        req = m.group(1)
    elif line.startswith("|") and "input" not in line:
        given, want = [c.strip() for c in line.strip("|").split("|")]
        got = slugify(given)
        mark = "ok  " if got == want else "FAIL"
        print(f"{mark} {req}  {given!r:<16} -> {got!r:<16} want {want!r}")

Output (Python 3.13.11):

ok   R1  'Hello World'    -> 'hello-world'    want 'hello-world'
ok   R1  'Café au lait'   -> 'cafe-au-lait'   want 'cafe-au-lait'
ok   R2  'a  --  b!!'     -> 'a-b'            want 'a-b'
FAIL R3  '!!!'            -> ''               want 'untitled'

The implementation handles the happy path and misses the edge case in R3, which is the kind of gap a model fills with a plausible guess when nobody wrote the rule down. The failure points to a requirement ID, so the fix, or the argument about whether R3 is right, happens at the spec level. Kiro’s acceptance criteria and Spec Kit’s task checklists aim at the same thing; examples in a table are the cheapest version.

Where does spec-driven development break?

Böckeler’s review lists the problems I’d expect, and I’ll keep her framing because it comes from actually using the tools.

One workflow for every problem size. She asked Kiro to fix a small bug and got four user stories with sixteen acceptance criteria. Spec Kit felt like overkill for a three-to-five-point feature. A real team needs a light path for small changes and a heavy one for big features.

Reviewing Markdown instead of code. Spec Kit generated many files, repetitive with each other and with existing code. Her line: “I’d rather review code than all these markdown files.” If the spec is too long to review, it stops being a checkpoint.

A false sense of control. Even with templates and checklists, she saw the agent ignore instructions, for example regenerating classes that already existed, and also follow some instructions too eagerly. Larger context windows don’t guarantee the model attends to everything in them.

The model-driven development echo. She compares spec-as-source to model-driven development, which never took off for business software, and worries SDD could end up with “inflexibility and non-determinism.” Regenerating code from the same spec doesn’t give you the same code.

I’d add one from my side: specs rot. A spec-anchored workflow needs someone who owns keeping the spec true, the same way a schema registry needs an owner. Without that, the spec becomes another stale wiki page, which is the problem GitHub says it’s solving.

What I would do

  • Spec-first for anything that will outlive the week. Write the what and why, plus acceptance examples, before handing work to an agent. Half a page beats a template nobody reads.
  • Make acceptance criteria executable. Examples tables, Given/When/Then cases, or plain unit tests the agent must make pass. A check that runs is worth more than a paragraph that’s read once.
  • Scale the ceremony to the change. Bug fixes get a one-line intent and a failing test. New features get the full specify, plan and tasks pass.
  • Keep project rules in one file. A constitution, steering docs or AGENTS.md: pick one, keep it short, and review it like code.
  • Review the plan harder than the spec. The plan is where the agent picks libraries, data models and boundaries, the decisions that are expensive to undo.
  • Pair it with a sandbox and evals. A spec tells the coding agent what to do; tests and agent evals tell you whether it did.

FAQ

What is spec-driven development in simple terms?

You write down what the software should do and how you’ll know it works, then let an AI agent plan and build from that document, checking its output against it at each step.

Is spec-driven development the same as TDD or BDD?

Related, not the same. TDD starts from a failing test and BDD from behavior scenarios; SDD starts from a natural-language spec that an agent turns into a plan, tasks and code. Good specs often contain BDD-style acceptance criteria, and good task lists end in tests.

What tools support spec-driven development?

GitHub’s open-source Spec Kit works with agents like GitHub Copilot, Claude Code and Gemini CLI. The Kiro IDE has specs built in (requirements, design, tasks). Tessl has explored specs as the main maintained artifact. You can also do it with plain Markdown files and any coding agent.

Does spec-driven development replace code review?

No. It moves some review earlier, to the spec and plan, but the agent can still ignore or misread the spec. You still review and test the code.

Sources

Get new posts in your inbox

© 2026 Malhar Ujawane. Built with Astro.