Spec-Driven Development: A Practical Guide with Examples / Jun 18, 2026

12 min readBy Emmanuel Akinfulubi
Spec-Driven Development: A Practical Guide with Examples

Spec-driven development is a way of building software where you write down what a feature must do, how it will work and the order to build it before any code exists, then build and check the code against what you wrote. The written spec is usually three short documents: requirements, design and tasks. With an AI coding agent, the agent drafts all three, and your job is to check each draft and make the decisions it cannot make for you.

This guide covers why that matters more now that agents write the code, the process step by step, one worked example in Kiro and GitHub's Spec Kit, and when not to bother.

Why the spec matters more with AI coding agents

Coding agents made writing code cheap. That did not make software easier. It moved the hard part upstream: the bottleneck is no longer typing, it is deciding precisely what to build.

An agent will build whatever you describe, quickly and confidently. Where the description has a gap, it fills the gap with a plausible guess and does not mention it. A colleague reading "send them a receipt" would come and ask what should happen if the email fails. An agent decides. I wrote up a case of exactly that, a payment with no receipt and a decision nobody knew had been made, in writing requirements an AI coding agent can build from.

The spec is where those decisions get made on purpose, by you, before the code exists. A clear target is worth more than a clever prompt.

What a spec contains

Three documents, each answering one question:

  1. Requirements: what must be true. The behaviour, including what happens when something goes wrong, written so that each line can be tested.
  2. Design: how it will work. What is stored, the states a record can be in, and the order of steps.
  3. Tasks: what order to build it in. Small pieces of work, each pointing back to the requirement it satisfies and each finishing with the tests passing.

Alongside them sit project rules: the conventions the agent should follow in every task, such as the language version, how money is stored and which folders it must not touch. Kiro calls these steering. Spec Kit calls them the constitution.

Both tools use the same three documents. Only the file names differ:

DocumentKiroSpec Kit
Requirements.kiro/specs/discount-codes/requirements.mdspecs/001-discount-codes/spec.md
Design.kiro/specs/discount-codes/design.mdspecs/001-discount-codes/plan.md and data-model.md
Tasks.kiro/specs/discount-codes/tasks.mdspecs/001-discount-codes/tasks.md
Project rules.kiro/steering/.specify/memory/constitution.md

A spec does not need to be long. It needs to be precise.

The process, step by step

Every document goes through the same loop: draft, save, check, decide, approve. The agent drafts. You commit the draft as it came, so you can see later what you changed. You check it against a few questions. You give your decisions back in plain words, never "make it better". Only then do you approve it and move on to the next document.

Step 1. Requirements

Describe the feature in a sentence or two and let the agent draft the requirements. Then check every line with three questions:

  • Could someone write a passing or failing test from this line without asking me anything?
  • Does it say what happens when something goes wrong?
  • Did the agent decide something I never asked for?

The second question is where most of the value is. Retries, partial success, two requests at once and a dependency that is down are the cases a first draft almost never covers.

Step 2. Design

Hold the approved requirements next to the design and ask where each one is handled. Three checks catch most problems:

  • Does the data model store everything the requirements need?
  • Does every failure in the requirements have a state and a plan?
  • Is the order of steps safe if the process stops halfway through?

Designing a feature an AI coding agent cannot improvise goes through this on a refund feature, including the order of writes that once left an order marked as refunded with no money moved.

Step 3. Tasks

Agents usually slice work by layer: database, then service, then screen. Re-slice it so each task delivers one piece of behaviour from end to end, names the requirement it satisfies, and includes its own tests. A task should be small enough to review in one sitting and leave the build passing when it lands. Sizing tasks an AI coding agent can finish covers how to judge that.

Step 4. Build

Let the agent take one task at a time, with the tests running after each one. Read each diff against the task and its requirement, not against your memory of a conversation. If the agent makes a choice that is not in the spec, that is not a bug to patch quietly. It is a missing decision, and it goes back into the requirements or the design.

Step 5. Review

At the end, check the feature against the acceptance criteria rather than a gut feeling: every requirement has a test, every test passes, and every failure has been tried at least once. If reality disagrees with the spec, fix the spec first and go again. The spec stays the shared source of truth for you, your teammates and any agent that touches the feature later.

A worked example: discount codes in a small shop

Here is the whole loop on one feature. The shop is an illustration, a small online store that takes payment in naira, not a client project. The prompts and files are shortened.

Requirements

The request, typed the way you would message a colleague:

add discount codes to the checkout. customers enter a code and get
money off their order, either a percentage or a fixed amount

In Kiro: start a Spec session rather than a Vibe chat, choose requirements first, and paste the request. In Spec Kit: type /speckit-specify followed by the same request.

The first draft looks complete:

1. WHEN a user enters a valid discount code
   THE SYSTEM SHALL apply the discount to the order.
2. WHEN a user enters an invalid code
   THE SYSTEM SHALL display an error message.
3. THE SYSTEM SHALL support percentage and fixed-amount discounts.

Commit it, then ask the three questions. "Valid" and "an error message" are not defined, so nobody could test them. Nothing covers an expired code, a code already used, or two codes on one order. And the draft never says whether the discount applies to delivery or how amounts are rounded, so the agent will settle both on its own while it codes.

So you give it your decisions, exactly:

Update the requirements with these decisions:
- An expired code is rejected, and the message shows the date it expired.
- A code already used on this account is rejected.
- Codes are not case sensitive. SAVE10 and save10 are the same code.
- Only one code per order. A second code replaces the first after
  the customer confirms.
- The discount applies to the items only, not delivery or VAT.
- Amounts are whole kobo. Round once, at the order total.

In Spec Kit, /speckit-clarify will also ask you up to five questions about the spec; answer them with the same decisions. Read the rewritten file once more, check nothing changed that you did not ask for, and approve. In Kiro that means saying yes when it asks whether the requirements look good. Spec Kit has no approve button, so committing is your approval.

Design

In Kiro, approving the requirements moves on to design.md. In Spec Kit, run /speckit-plan with the tools to use, for example the existing database and no new packages.

The draft data model:

DiscountCode: code (text), type (percent | fixed),
              value (decimal), expiresAt (date)
Order:        discountCodeId (optional)

Two of the checks fail. Nothing records who has used which code, so the rule that a code already used on an account is rejected cannot work. And value is a decimal, which drifts by fractions of a kobo that stop adding up across thousands of orders. The decisions: add a redemption record holding the code, the account, the order and the time, and store every amount as a whole number of kobo, like the rest of the shop. Commit the draft, give the decisions, read the change, approve.

Tasks

In Kiro the task list follows from the approved design. In Spec Kit run /speckit-tasks, then /speckit-analyze to check that the spec, plan and tasks agree with each other.

After re-slicing, the list looks something like this:

1. Codes can be stored and looked up, case-insensitively
   Requirements: codes are not case sensitive
   Done when: a test finds SAVE10 by "save10 "
2. A valid code reduces the items subtotal
   Requirements: 1, 3, items only, whole kobo
   Done when: tests cover percentage and fixed codes,
   with delivery and VAT unchanged
3. Expired and already used codes are rejected with their messages
   Requirements: expired, already used
   Done when: both rejections have a test
4. A second code replaces the first after confirmation
   Requirements: one code per order
   Done when: a test covers both confirm and cancel

Each task is one behaviour, end to end, with its tests inside it rather than in a testing phase at the end.

Build and review

Set the tests to run after every task before anything is built. In Kiro, an agent hook can run them each time a task finishes. In Spec Kit, a git pre-commit hook that runs the test command does the same job. Break one test on purpose to see the hook fail once. A hook you have never seen fail is one you are only hoping works.

Then build one task at a time: Start task next to task 1 in Kiro's tasks.md, or /speckit-implement limited to the first task in Spec Kit. After each one, check the tests passed, read the diff against the task, and look for anything the spec did not ask for.

Suppose the agent stops a customer from removing a code once it is applied. Nobody decided that. It goes back into the requirements as a decision, then into a task, rather than being patched straight into the diff.

When the last task lands, walk the requirements one by one. Each should have a named test, and each failure should have been tried by hand once: an expired code, a used code, a second code. That is the definition of done, and it was written before the first line of code.

How long it takes

Writing requirements this way adds ten or fifteen minutes per feature at the start. It removes more than that from review and rework, because you stop discovering decisions in a diff that should have been made before the diff existed. The design and task checks add a little more on features that touch money or data you cannot recreate, and those are the features where a wrong guess costs the most.

When not to write a spec

A one line change, a prototype you will delete, or an afternoon learning a new package does not need three documents. The useful question is how long the code has to survive and who else depends on it. Vibe coding vs spec-driven development compares the two on the same feature through the git log each one leaves behind, and covers when each is the right call.

Write a spec when the task is ambiguous, involves several steps, handles money or logins, or is handed to an agent that needs the full context to get it right.

Mistakes that undo the method

  • Approving the first draft. It always looks finished. The guesses look exactly like real requirements, and you only find them by checking.
  • Asking the agent to "make it more detailed". That hands the decisions back to the agent. Give it the decisions themselves.
  • A testing phase at the end of the task list. Tests belong inside the task that creates the behaviour, or no task can prove it is finished.
  • Fixing the code but not the spec. If the two disagree, the next agent to read the spec builds the old behaviour again.
  • Reviewing every line instead of every requirement. The point of the spec is that you can check the work against a list, which matters more as review becomes the bottleneck.

Where to go next

Each step above has its own longer post:

If you want to practise the whole loop on two features, discount codes and refunds, in Kiro or Spec Kit, that is what my course Spec-Driven Development with AI Coding Agents teaches. It is in development and the waitlist is open.

Frequently asked questions

What is spec-driven development?
It is writing down what a feature must do, how it will work and the order to build it before any code is written, then building and checking the code against that written spec. The spec is usually three short documents: requirements, design and tasks. It works the same whether a person or an AI agent writes the code.
How is it different from test-driven development?
Test-driven development starts from tests that pin behaviour. Spec-driven development starts from a written description of intent and acceptance criteria, which then produce both the tests and the implementation. The two fit together: each requirement in the spec becomes at least one test.
Does the AI agent write the spec, or do I?
In Kiro and Spec Kit the agent drafts all three documents in seconds. Your job is to check each draft, make the decisions it guessed at, and approve it before moving on. The typing moves to the agent and the decisions stay with you.
Which tools support spec-driven development?
Kiro has spec sessions built in and writes requirements.md, design.md and tasks.md for each feature. GitHub's Spec Kit adds commands such as /speckit-specify, /speckit-plan and /speckit-tasks to several coding agents. You can also do it by hand with three Markdown files and any agent.
Is spec-driven development the same as waterfall?
No. A spec covers one feature, not a whole project, and it changes whenever the build shows it was wrong. Waterfall fixes all the requirements up front. Here, when reality disagrees with the spec, you fix the spec and carry on.
Do I need a spec for small tasks?
No. A one line change does not need a document. Specs pay off when a task is ambiguous, involves several steps, handles money or logins, or is handed to an agent that needs the full context.