Spec-Driven Development Without the Confusion: A Practical Guide for People and AI Agents

Imagine telling a technician:

"Fix my air conditioner."

The technician could probably do it. But first, they need to know what is wrong: does it not turn on? Does it cool poorly? Is it making noise? Is it leaking water? What model is it? Is there a maximum budget?

Software works the same way.

When someone says, "build a booking page" or "add Google login," it may sound like a clear instruction. In reality, it is only the beginning of a conversation. Rules, exceptions, and a definition of "done" are still missing.

Spec-Driven Development (SDD) is a way to organize that conversation before writing code.

Key idea

Before building, write down what the system should do, what it should not do, and how you will know that it works.

You do not need huge documents. You need fewer assumptions.

First: what does the name actually mean?

"Spec" comes from specification.

"Driven development" means that development is guided by something.

So, in simple terms, Spec-Driven Development means developing software based on or guided by specifications.

A specification is a clear set of agreements about a feature. It is not code. It is not a technical novel either. It is a short and concrete answer to questions like:

• What problem are we solving?
• Who are we solving it for?
• What should happen when everything goes well?
• What should happen when something fails?
• What are we not building right now?
• How do we verify that it was implemented correctly?

Look at the difference.

Request without a specification

Allow customers to request a repair from the website.

Request with a specification

A customer can submit a repair request.

They must provide their name, phone number, area, and a description of the problem.

The request is saved with a "pending" status.

The customer receives a request number on screen.

Payments and photo uploads are not included in this first version.

If saving fails, the system must not display a success message.

The second request leaves much less room for misinterpretation.

Why did this way of working emerge?

It did not suddenly appear because of artificial intelligence.

Software teams have been using requirements, user stories, use cases, API contracts, and acceptance tests for a long time. They all try to accomplish the same thing: agree on the expected result before building it.

AI made that discipline urgent again.

An agent can create files, screens, endpoints, and tests very quickly. That is useful. It also means the agent can build the wrong idea very quickly if the instruction is vague.

Think of an agent as a very fast technician who never gets tired. If you say, "fix this," it will make decisions on its own. If you give it a clear list of symptoms, constraints, and expected outcomes, it has a much better chance of getting it right.

Modern agent-oriented tools such as Kiro and GitHub Spec Kit organize this process into three simple stages:

1. Requirements: what should happen.
2. Design: how it could be built.
3. Tasks: what will be done step by step.

It is not magic. It is simply a good conversation written down.

What is Spec-Driven Development useful for?

Spec-Driven Development is especially useful when making a mistake costs more than clearly explaining the request.

For example, some real-world cases could be:

Case 1: Money

If you are changing payments, subscriptions, invoices, or discounts, one small decision can affect real money.

Example:

Allow a user to cancel a subscription.

Before writing code, you need to clarify:

• Is the subscription canceled immediately or at the end of the already-paid period?
• Is there a refund?
• Does the user lose access immediately?
• What happens if Stripe or the payment provider fails?

Case 2: Customer data

If you store phone numbers, addresses, documents, or personal information, you need to define who can access that data and how long it should be retained.

Case 3: Connected services

If your system communicates with email providers, WhatsApp, Google, Cloudflare, or a payment provider, you need to decide what happens when the external service does not respond.

Case 4: AI agents

If an AI agent will implement part of the work, a specification prevents the agent from becoming the product manager, architect, QA engineer, and fortune teller at the same time.

Easy rule to remember

If two people can understand the same task in different ways, write a specification.

A specification is not the technical design

This is a common source of confusion.

A specification says what result you want.

A user can download their data from their profile.

A technical design explains how you plan to achieve it.

The system generates a CSV file, stores it for 24 hours, and sends the user a download link.

Both are important. But they are not the same thing.

Why separate them?

Because the expected outcome can remain correct even when the technical solution changes.

Today you may generate a CSV file. Tomorrow you may need JSON or a ZIP file. The main promise remains the same:

"The user can download their data."

Let’s look at a complete example

We will use a real-life style example from one of my clients: a page that allows customers of Eddy Reparaciones to request help.

The initial request

Build a repair request form.

There is nothing wrong with that request. It is simply incomplete.

An agent could create a beautiful screen and still leave important questions unanswered:

• Which fields are required?
• Where are the requests stored?
• What does the customer see when the process finishes?
• Can the same request be submitted twice?
• Are we going to charge the customer from that page?

The specification

# Repair Request from the Website

## Goal

Allow a customer to submit a repair request from the Eddy Reparaciones website.

## Information we collect

- Full name.
- Phone number.
- Area or address.
- Type of repair.
- Problem description.
- Preferred time.

## Rules

- All fields are required except additional details.
- The phone number must contain at least 7 digits.
- After submitting, the customer sees a confirmation and a request number.
- The request is stored with a creation date and an initial "pending" status.
- A quick double-click must not create two identical requests.

## If something goes wrong

- If information is missing, the field that needs attention must be identified.
- If the request cannot be saved, the system must not show a false success confirmation.

## We are not doing this yet

- Online payments.
- A complete technician dashboard.
- Photo or video attachments.
- Automatic scheduling.

## How we know it works

- [ ] A valid request is saved only once.
- [ ] The customer receives a request number.
- [ ] Invalid data is not saved.
- [ ] If the database fails, the customer sees a real error.

Notice something important.

This specification does not say whether we will use React, PHP, Python, a specific database, or a specific API.

That comes later.

First, we agree on what should happen.

The "aha" moment: a specification is also a list of tests

Every important rule should be verifiable.

For example:

If a statement cannot be tested, it is often a sign that the requirement is still too vague.

For example:

The form should be easy to use.

That is a good intention, but it is hard to verify.

You could replace it with something more concrete:

- Required fields are clearly marked.
- Each error appears next to the incorrect field.
- The submit button is disabled while the request is being processed.
- The customer sees a confirmation when the process finishes successfully.

Now there is something specific to review.

How to use a specification with an AI agent

This is where it becomes practical.

Do not give the agent only this:

Build a repair request form.

Give it the specification and ask it to work in stages.

Prompt for the first stage

Read the specification in docs/specs/repair-request.md.

Do not modify any files yet.

1. Tell me which questions are still open.
2. Propose the minimum technical design.
3. Break the work into small tasks.
4. Map each acceptance criterion to a test.

Do not implement anything until I approve the plan.

This prompt does something important: it prevents the agent from building before you have reviewed the plan.

You can also do this using the planning mode of the AI tool you are working with, whether that is Claude, Codex, or another coding agent.

Prompt for implementation

After approving the design, you can give the agent this:

Implement the approved plan for the repair request feature.

Rules:

- Follow the specification.
- Do not add payments, login, an admin dashboard, or attachments.
- Make small changes and explain each one.
- Write and execute tests for every acceptance criterion.

When finished, provide:

1. Modified files.
2. Actual test results.
3. Criteria that could not be verified.
4. Instructions for manual testing.

This prompt can also be executed using an automatic or manual mode, depending on the AI tool you are using.

Important

An agent can say, "I’m done." The specification and tests are how you verify that claim.

What if I work with multiple agents?

That also works.

The specification becomes the shared map that all agents use.

For the Eddy Reparaciones example, the work could be divided like this:

Agent 1: reviews requirements and identifies open questions.

Agent 2: designs the form interface.

Agent 3: creates the endpoint and data persistence.

Agent 4: writes validation and integration tests.

Agent 5: verifies that everything complies with the specification.

Do not put five agents to work at the same time without a shared guide. That can produce five different interpretations of the same idea.

First: specification.

Then: design.

Then: separated tasks.

When a short note is enough

You do not need a full specification for every small change.

If you are changing a title, adjusting a color, or fixing a typo, a short description and a visual review may be enough.

Use more detail when the change:

• Affects payments or money.
• Handles personal data.
• Grants or removes permissions.
• Deletes or migrates data.
• Depends on another service.
• Can break existing functionality.
• Will be implemented by an agent with significant autonomy.

Think of it like a recipe.

To boil water, you do not need a three-page recipe.

To prepare dinner for twenty people, you probably want to know what ingredients to buy, in what order to cook them, and how to verify that nothing was forgotten.

Common mistakes

Writing too much

A specification that nobody updates is just decoration.

Start small:

• goal,
• rules,
• errors,
• out of scope,
• acceptance criteria.

Saying how before saying what

"Use a queue," "create three tables," or "use this library" may all be valid decisions.

But first define the expected outcome.

Then choose the tool.

Leaving errors until the end

The happy path is easy: the customer fills out the form, the system saves the request, and everyone is happy.

Problems appear when data is missing, an API goes down, or someone clicks the button twice.

Write down the important failure cases from the beginning.

Letting the agent fill in important gaps

An AI agent can make reasonable decisions.

That does not mean those decisions are your decisions.

If something matters for customers, security, money, or data, put it in the specification.

Reusable template

You can use this example template for a feature, requirement, module, or similar work item:

# Feature Name

## The Problem

What are we trying to solve?

## Who Will Use It?

Who uses this feature?

Are there different roles?

## What Should Happen?

- ...
- ...

## What Can Go Wrong?

- ...
- ...

## What Are We NOT Building Yet?

- ...

## How Will We Verify It Works?

- [ ] ...
- [ ] ...

## Open Questions

- ...

The last section is extremely useful.

You do not need to know everything before you begin.

But it is much better to write:

"We still need to decide this."

than to make a hidden assumption.

Summary in one sentence

Spec-Driven Development means agreeing on the expected behavior before building it, so that people and AI agents work with fewer guesses and more verifiable outcomes.

A good specification does not slow you down.

It prevents you from moving quickly in the wrong direction.

References

• Kiro Docs: Specs — an example of a requirements, design, and task workflow for AI agents.
• GitHub Spec Kit — a toolkit for defining what to build before delegating implementation work to a coding agent.