Spec-Driven Development With AI Agents: A Practical Guide

TL;DR: Write the Spec Before You Prompt

AI coding agents produce clean, working code in seconds and still ship the wrong thing. The bottleneck is not typing speed anymore. It is intent. Spec-driven development fixes that by making you describe behavior, constraints, and acceptance criteria first, then letting the agent implement against a document both of you can read.

Verdict: if a feature touches more than two files or will span more than one session, write the spec first. If it is a five-line bug fix, skip the ceremony and just fix it. Everything else lives on a spectrum, and this guide shows you where the line sits.

Below you get the full workflow: what spec-driven development actually means, how GitHub Spec Kit runs the loop, how Kiro takes a lighter path, and the practical rules that separate a useful spec from a wasted afternoon.

What Spec-Driven Development Actually Means

The idea sounds new but the shape is old. For decades, teams wrote requirements documents, then threw them away once the real coding started. The documents went stale because keeping them updated cost more than the value they returned.

Also Read:

How to Write Rules Files for AI Coding Agents

Spec-driven development flips the economics. Because an AI agent can generate an implementation from structured text, the spec stops being overhead and becomes the primary artifact. Change the spec, regenerate the affected parts, and the documentation never drifts from reality because the spec drives the code directly.

Martin Fowler’s colleagues at Thoughtworks studied the tools pushing this approach and found three distinct maturity levels:

Nearly every tool you can use right now operates at the first level. That matters for expectations: you still read diffs, you still run tests, you still own the architecture. The spec just gives the agent something better than a half-formed prompt to aim at.

Where Pure Vibe Coding Breaks Down

Vibing your way through a weekend prototype works. Vibing your way through a billing system does not, and the failure modes repeat across almost every team that tries:

• Intent drift. Each follow-up prompt nudges the implementation slightly away from what you originally pictured. Twenty prompts later, the feature technically matches none of them.
• Session amnesia. The agent forgets yesterday’s decisions unless you re-explain them. Context windows fill up, summaries lose nuance, and the same architectural debate happens twice.
• Review overload. When generation is cheap, reviewing becomes the bottleneck. A thousand-line pull request generated in four minutes still takes an hour to review properly.
• Hidden acceptance criteria. The tests that matter live in your head. Until they exist as written criteria, the agent cannot target them and neither can your test suite.

If you have already inherited a codebase built this way, the repair path runs through a systematic audit. We covered that in our guide to auditing vibe coded Python codebases, and the broader advice in our vibe coding workflow guide for solo developers pairs well with everything below. Prevention through specs beats post-hoc archaeology every time.

GitHub Spec Kit Runs the Loop

Spec Kit is GitHub’s open source toolkit for this workflow, released under the MIT license. It crossed 130,000 stars within its first year and hit version 1.0.0 in August 2026, exactly one year after the first commit. It works with a long list of coding agents including Copilot, Claude Code, and Cursor, which means your existing setup probably already qualifies.

Also Read:

How to Audit Vibe Coded Python Codebases

Installation goes through uv, Astral’s Python package manager. You need Python 3.11 or newer plus Git, then a single tool install command pulls the Specify CLI from the spec-kit repository on GitHub. From there, one init command scaffolds your project and connects it to whichever agent you use.

The core workflow is six slash commands executed in order:

Two details separate Spec Kit from a plain prompt template. First, every phase produces files on disk inside your repo, so the reasoning survives between sessions and teammates can review the spec itself rather than reverse-engineering intent from diffs. Second, the last step closes the loop: convergence checks whether the implementation still matches the written spec, and you repeat the build step until it reports converged. Optional extensions add a structured assess, fix, test flow for bugs and an intake to decision pipeline for evaluating raw ideas before you commit to building them.

Also Read:

Vibe Coding Workflow Guide for Solo Developers: Ship Apps Faster

Kiro Takes a Lighter Path

If managing files and slash commands sounds heavy, Kiro is the friendlier entry point. Amazon built it as a VS Code based IDE with the spec workflow baked into the interface. Instead of running commands, you walk through three generated documents: Requirements, written as user stories with acceptance criteria in Given, When, Then form; Design, covering the technical approach; and Tasks, which trace back to requirement numbers and can be executed one by one with per-task review.

Kiro also carries project-wide context through what it calls steering files, typically product.md, structure.md, and tech.md, which act like a lightweight version of Spec Kit’s constitution.

Here is how the three approaches compare:

None of the three is strictly better. The plain file approach fails quietly once features start interacting. Spec Kit scales furthest but asks the most of you. Kiro trades flexibility for guidance, and its own site frames the pitch as turning prompts into executable specs with validation layered on top.

Writing a Spec an Agent Can Actually Execute

The tooling matters less than what you put in the spec. Four rules carry most of the weight:

• Describe behavior, not implementation. Say the export button produces a CSV under ten megabytes within five seconds. Do not prescribe which library parses the rows. Stack decisions belong in the plan phase, and our FastAPI versus Litestar comparison shows why locking those choices deliberately beats letting a prompt decide by accident.
• Give every requirement acceptance criteria. Given, When, Then format forces you to define done before code exists. Vague requirements produce vague code, and the agent will happily exploit the wiggle room.
• List non-goals explicitly. Write down what this feature must not do. Agents expand scope when given silence, and unrequested features are just future review load.
• Promote repeated rules into the constitution. Anything you explain twice belongs in the project rules file. Security requirements especially, since our rundown of AI agent security risks shows how easily injected instructions slip past an agent working from memory alone.

I treat the constitution file the way I treat a style guide: short, opinionated, and updated the moment I correct the same mistake twice. GitHub’s own guidance for Spec Kit says your role is not just to steer but to verify, reflecting on and refining the output at each phase. Skip those checkpoints and you have rebuilt vibe coding with extra steps.

When You Should Skip the Full Ceremony

Honesty requires the counterargument. Thoughtworks’ write-up warns that elaborate, file-heavy spec workflows can amplify the very problems they claim to solve, piling review work onto developers who already had too much of it. Ceremony has a tax, and small tasks should not pay it.

My rule of thumb fits in a table:

I think the honest answer for most working developers lands in the middle: adopt specs gradually, starting with the features where miscommunication already costs you time. You do not owe every commit a requirements document.

Final Thoughts and Your Next Move

Spec-driven development is not a promise that AI writes perfect software. It is a way to make the imperfect software traceable, reviewable, and anchored to something sturdier than a prompt history. The spec becomes the contract, the agent becomes the contractor, and convergence checking keeps both sides honest.

Pick one real feature this week and run it through the loop end to end: constitution once, then specify, plan, tasks, implement, converge. Keep the resulting files in the repo even after the merge, because next month you will want them. Start with GitHub’s Spec Kit repository if you live in the terminal, or try Kiro if you prefer the spec workflow wrapped in an editor.

I would rather spend ten minutes writing a spec than thirty minutes reverse-engineering what an agent thought I meant. Once you feel that trade pay off on a single feature, the rest of the workflow adopts itself.