Spec-Driven Development: A Plain-Words Guide for AI Builders
By Tuan Hoang, Founder of Flowmaps
Published · 6 min read
Spec-driven development means you write down what to build before the AI writes any code: what the feature does, how you'll know it works, and in which order the work happens. The AI then builds from that spec instead of from a loose chat. It's the opposite of "just prompt and see", and it's the main reason some people finish AI-built apps while others get stuck at 80%.
I make Flowmaps, one of the tools in this space, so I'll be clear about where it fits. Facts about the other tools come from the Spec Kit docs and Kiro's spec docs, checked November 2026.
Why it matters more with AI
A human developer who gets a vague task asks questions. An AI coding tool usually doesn't: it fills every gap with a guess and keeps going. One guess is fine. Fifty guesses across a growing project is how you end up with a login that doesn't match the payments, or a database that gets rebuilt three times.
A spec removes most of the guesses up front. It also fixes the other big problem: AI tools forget. Each new chat starts with no memory of what you agreed last week. When the plan lives in a spec instead of in old chats, every session can start from the same page.
Spec-driven development vs vibe coding
| Vibe coding | Spec-driven development | |
|---|---|---|
| Where the plan lives | In your head and the chat | In a written spec next to the project |
| How you start | "Build me an app that…" | Write what to build and what "done" means |
| Size of each step | Whatever comes to mind | One feature or task at a time |
| When the AI guesses | All the time | Only where the spec is silent |
| Good for | Quick experiments and prototypes | Apps you want to finish and keep working on |
They're not enemies. Many people vibe code a quick prototype to see if an idea feels right, then switch to a spec for the real build. If you're new to the first one, read how to vibe code.
The four steps
1. Specify: what and why
Describe the feature from the user's side, without any technical choices: who does what, and why. Add the rules that matter and the things it should not do.
2. Plan: how
Decide the technical side: which data is saved, which screens change, what it connects to. If you don't code, you can let the AI propose this part and check that it matches the spec.
3. Break it into tasks
Turn the plan into small, ordered steps. Each one should be small enough to build and check in one go. Put first what the others depend on.
4. Build and check, one task at a time
The AI builds one task, you check it against the spec, and only then move on. When something is wrong, you fix the spec or the task, not just the code, so the next session doesn't repeat the mistake.
An example spec
Here's a short spec for one feature of a dog-walking app. This is all most features need:
Feature: Owners book a walk
Who and why: A dog owner books a walk with a walker, so the walker knows when to come.
What happens: The owner picks a walker, a date and a time slot from the walker's free slots, and confirms. The walker gets an email. The booking shows on both their dashboards.
Rules: Slots in the past can't be booked. Two owners can't book the same slot. Owners can cancel up to 24 hours before.
Not now: Repeat bookings, payments (separate feature).
Done when: I can book a slot as an owner, see it as the walker, and a second owner can't book the same slot.
The "Not now" and "Done when" lines do most of the work. They stop the AI from building extras you didn't ask for, and they tell both of you when to stop.
Tools for spec-driven development
| Tool | How it works | Best for |
|---|---|---|
| GitHub Spec Kit | Free, open-source commands inside your AI coding agent: set principles, write the spec, make a technical plan, break it into tasks, implement | Developers in the terminal with Claude Code, Copilot, Cursor or Codex |
| Kiro | A code editor by AWS that turns a prompt into requirements, a design and a task list, then builds the tasks and shows their progress | Developers happy to switch editors |
| Flowmaps | A visual map of features in build order, with a spec and build prompt per feature; Claude Code builds from it and moves the card when it's done | Beginners and anyone who builds with Lovable, Cursor or Claude Code |
| A markdown file | One file with every feature, its rules and its "done when" | Anyone; it's free and works with every tool |
For a full comparison with prices, see the best AI app planning tools. Spec Kit and Kiro are excellent if you're comfortable with code. If you're not, a tool that works in the browser is the easier start.
How to start today, with any tool
- Write your app idea in one sentence.
- List the features. Our MVP feature list guide shows how to keep it short.
- Write a short spec for the first feature, like the example above.
- Give that one spec to your AI builder. In Claude Code or Cursor, save it as a file in the project so every session can read it.
- Check the result against "Done when". Then write the next spec.
Want a starting point? Our free PRD template covers the whole app, and how to use Claude Code shows how to build from a spec step by step.
Frequently asked questions
What is spec-driven development in simple terms?
You write down what to build and how you'll know it works before the AI writes code. The AI then builds from that written spec, one small piece at a time, instead of guessing from a chat.
Is spec-driven development the same as writing a PRD?
Close, but not the same. A PRD (product requirements document) describes the whole product once. Spec-driven development goes further: each feature gets its own spec, a plan and tasks, and the spec stays up to date while you build. Read do you need a PRD for Lovable or Bolt for the difference in practice.
Does spec-driven development work for non-coders?
Yes, and it may help non-coders the most. The spec is written in plain words: who does what, the rules, and when it's done. You don't have to read the code to check whether the result matches the spec.
What is GitHub Spec Kit?
GitHub Spec Kit is a free, open-source toolkit from GitHub. It adds commands to AI coding agents like Claude Code, Copilot, Cursor and Codex to write a spec, a technical plan and a task list, and then implement it. It runs in the terminal.
What is the difference between Spec Kit and Kiro?
Spec Kit adds spec-driven commands to the AI coding tool you already use. Kiro is its own code editor, made by AWS, with specs built in: it writes requirements, a design and tasks, and then builds them inside Kiro.
Doesn't writing a spec slow you down?
It takes minutes per feature, and it saves the hours you'd spend undoing wrong guesses. Most AI-built projects don't stall because the AI is slow; they stall because nobody wrote down what "done" means.