tuaregs[AI]

Spec-Driven Development: Code With AI Without Losing Control

Write the spec, let AI build it. The workflow that keeps you in charge when AI writes most of the code.

Table of Contents

If you have ever watched an AI agent confidently build the wrong thing for twenty minutes, this is for you.

Spec-driven development (SDD) is the simple shift that fixes it: agree on what you are building before the AI starts building it.

1. What spec-driven development is

Spec-driven development means the specification is the source of truth, not the code. You write a clear description of what you want, the AI turns it into a plan, and only then does it write code. When something is wrong, you fix the spec, not just the output.

It flips the usual order. Instead of "prompt, get code, patch the code, repeat," you do "spec, plan, build, verify." The durable artifact you keep and refine is the spec, because the code is now cheap to regenerate.

2. Why it matters now

When you wrote every line yourself, a vague plan was fine; your understanding lived in your head and your hands. Now an AI agent can generate a thousand lines in a minute. If your intent is vague, you get a thousand lines of confidently wrong code, fast.

The bottleneck has moved. It is no longer typing speed, it is clarity of intent. SDD is just taking that seriously: the clearer your spec, the better the AI's output, and the easier it is to review. You review the spec (small, in your language) instead of reviewing a huge diff (large, in the machine's).

3. The loop

SDD is a short, repeatable loop:

  1. Specify. Write what you want in plain language: the goal, the behavior, the constraints, what "done" looks like. Not how to code it.
  2. Plan. Have the AI propose an approach and break it into steps. Read the plan. This is the cheapest place to catch a wrong turn.
  3. Build. Let the AI implement against the approved plan, ideally in small, reviewable chunks.
  4. Verify. Check it against the spec, run the tests, try the edge cases. If it is wrong, update the spec or the plan and loop, do not just hand-patch the code.

The trick is to spend your attention at steps 1 and 2. A clear spec and an approved plan make steps 3 and 4 almost boring, which is exactly what you want.

4. What a good spec contains

A spec is not a novel. A good one is short and concrete:

  • The goal. What are we building and why, in a sentence or two.
  • Behavior. What it should do, including the important edge cases.
  • Constraints. Stack, patterns to follow, things not to touch, performance or security limits.
  • Done criteria. How you will know it works. Tests that should pass, or a checklist.
  • Out of scope. What this explicitly does not cover, so the agent does not wander.

If you cannot write the done criteria, you do not understand the task yet. That is a feature: the spec surfaces the confusion before the AI bakes it into code.

5. SDD vs vibe coding

Vibe coding (see the vibe coding guide) is fast, loose, and great for exploring: you chat, the AI builds, you steer by feel. It is perfect for prototypes and learning.

SDD is what you reach for when it has to be right: anything other people depend on, anything you will maintain, anything where a confident wrong answer is expensive. The two are a spectrum, not enemies. A common rhythm is to vibe-code a prototype to understand the problem, then write the spec and rebuild it properly.

Rule of thumb: the higher the stakes and the longer the lifespan, the more spec you want up front.

6. The tools

You do not need anything fancy to start; a markdown file works. But tooling is forming around this workflow:

  • GitHub Spec Kit (github.com/github/spec-kit): an open toolkit and CLI for spec-driven development with AI agents.
  • Kiro (kiro.dev): an AI IDE built around specs, plans, and hooks.
  • Claude Code plan mode (Claude Docs): drafts and confirms a plan before it touches your code, which is the planning half of the loop built in.

The tool matters less than the habit. Even a SPEC.md you paste into any assistant gets you most of the benefit.

7. How to start

Pick a small, real task and run the loop once:

  1. Write a half-page spec: goal, behavior, constraints, done criteria.
  2. Ask your AI to produce a plan from it, and read the plan before approving.
  3. Let it build in small steps, reviewing against the spec.
  4. When something is off, edit the spec or the plan, not just the code.

Do that three times and it becomes second nature. You will write less code by hand, review less of the machine's, and ship things that actually match what you meant.

Ready to practice? Try it in the playground or pick a coding path.