Spec-Driven Development with Kiro: A Worked Example

Most people start using an AI coding tool the same way. They type a request, the tool writes code, and they fix whatever is wrong. This works for small jobs. For bigger ones, it often goes badly. The AI guesses what you meant, builds the guess, and you only learn it was wrong later.

Spec-driven development tries to fix this. You write down what you want first. You check it. Only then does the AI build. Kiro, the tool from Amazon, is built around this idea. People search for "kiro spec-driven development" because they want to know how it works in practice.

This article explains it step by step, with one worked example. We read Kiro's official documentation on 9 October 2026 for every fact about the tool. The example itself is made up, and we label it clearly. We did not run it in Kiro, so the files we show are what a good spec could look like, not real Kiro output. Kiro will word things in its own way.

What a spec is

A spec is a plan in plain files. According to Kiro's documentation, a spec turns an idea or a bug report into a plan, with tasks you can track. Every spec produces three files:

• requirements.md says what the feature must do. It holds user stories and acceptance criteria. For a bug, a bugfix spec uses a file called bugfix.md instead.
• design.md says how it will be built. It covers the structure, how the parts talk to each other, error handling and a plan for testing.
• tasks.md is a list of steps that can be tracked as they are done.

The order matters. The documentation describes two ways to start a feature spec. In Requirements-First, you go from requirements, to design, to tasks. You use it when you know the behaviour you want but the structure is open. In Design-First, you go from design, to requirements, to tasks. You use it when you already have a structure in mind, or you are moving design documents into Kiro.

There is also a Quick Spec. The documentation says it runs all three phases without approval gates and goes straight to the task list. That is faster, and it is also the mode where you lose your chance to check each document. We come back to this later.

Why this helps, especially if you are not an expert

Think about hiring a builder to make a small shop. If you say "make me a shop", you may get something very different from what you pictured. If you first agree on a one-page plan, you can point at the page and say "this is wrong". Everyone can read a plan. Few people can read the finished work.

A spec gives you that page. You may not understand the code. You can understand a sentence like "an order must never be marked paid twice". You can read it, agree with it, and test it. That is the main gain: the spec turns an invisible guess into something you can check.

The documentation shows the style Kiro uses for requirements. It is called EARS notation, and its form is: WHEN something happens, THE SYSTEM SHALL do something. The documentation gives its own example about a form that receives bad data and shows error messages next to the fields. This form is short and hard to misunderstand. It also gives you something to test: do the thing, and see if the result happens.

A worked example: an order-status lookup

Illustrative example: the shop, the feature and the files below are made up to show how this works. They are not real Kiro output, and Kiro's own wording will differ.

Imagine a small online shop. Customers keep asking by message, "Where is my order?" The owner wants a simple page. The customer enters an order number and a phone number, and the page shows the order status.

Step 1: Start with one plain sentence

Before opening any tool, write the idea in your own words:

Customers should be able to check where their order is, without
messaging us. They enter an order number and the phone number used
at checkout, and see the status. Nobody should be able to see
someone else's order.

The last sentence is the most important one. It is easy to forget, and it is where a careless build causes harm. If you leave it out, the AI may build a page where anyone can type any order number and read the customer's name and address.

Step 2: Read the requirements, and fix them

In Kiro, you start a spec, choose Feature, then choose Requirements-First. Kiro then writes requirements.md from your idea. Here is the kind of thing a good version might contain:

Requirement 1: Look up an order
User story: As a customer, I want to enter my order number and phone
number, so that I can see my order status.

Acceptance criteria
1. WHEN a customer enters a correct order number and the matching
   phone number THE SYSTEM SHALL show the order status.
2. WHEN the order number or the phone number does not match
   THE SYSTEM SHALL show the same message, "Order not found.
   Check your details.", and no other information.
3. WHEN a customer asks for an order that belongs to someone else
   THE SYSTEM SHALL NOT show any detail of that order.

Requirement 2: Limit guessing
Acceptance criteria
1. WHEN more than 10 lookups come from one source in one minute
   THE SYSTEM SHALL refuse further lookups for a short time.

Now do the part that matters. Read each line and ask three questions.

• Is it what I meant? If the AI wrote something you did not ask for, remove it.
• What is missing? What happens if the order is cancelled? What if there is no phone number on the order? Add a line for each.
• Can I test it? If you cannot imagine a test, the sentence is too vague. Rewrite it until you could try it with your own hands.

Notice criterion 2. It says to show the same message when the number or the phone is wrong. That is a deliberate choice. If the page says "wrong phone number" in one case and "order not found" in another, an attacker can use the difference to find out which order numbers exist. We did not take this idea from Kiro. It is a common safety habit, and it is the kind of detail you should add if the AI leaves it out. Our own store tracking works the same way: it asks for the order number plus the email or phone used at checkout, and shows a general "not found" message when they do not match.

Kiro also has an optional step that can help here. The documentation calls it Analyze Requirements. You run it after the requirements are made and before the design. You find it in the chat options, or in the Continue dropdown in the editor. It checks for contradictions, unclear wording, conflicting limits and gaps. It does not replace your own reading, but it is a second pair of eyes.

Only when you are happy do you approve the requirements and move on.

Step 3: Read the design

Kiro next writes design.md. The documentation says it covers the structure, how components work together, sequence diagrams and what to think about when building. You do not need to understand every line. Look for answers to simple questions:

• Where is the order data kept, and does the page read it directly, or through a small service?
• What exactly is sent back to the browser? It should be the status and little else. It should not include the whole order record.
• Where is the limit on repeated lookups enforced?
• What is the plan for testing? A good one names the cases from your requirements.

Here is a short sample of the sort of thing to look for:

Response: { status: "shipped", updated_at: "..." }
It must not include: name, address, phone, email, item prices.

Errors: any lookup that fails returns the same message and the same
response time shape, whether the order exists or not.

If the design sends back the full order, say so. Ask Kiro to change it, and read the new version before you approve it. This is exactly where a non-expert can still catch a real problem. You do not need to know how to write the code. You need to know what must not leave the system.

Step 4: Read the task list

Last comes tasks.md, the step-by-step plan. A sensible list for our example might look like this:

1. Create the lookup endpoint that takes order number and phone.
2. Return the status only, and the same error for any failure.
3. Add the limit on repeated lookups.
4. Build the lookup page with one form and one result area.
5. Write tests for: right details, wrong phone, unknown order,
   someone else's order, too many lookups.
6. Check that no personal details appear in the response.

Check that each requirement has at least one task, and that the tests match your acceptance criteria. If a requirement has no task, it will probably be forgotten. The documentation describes the task file as a plan you can track, and says that running all tasks executes them in dependency-based waves, with independent tasks running at the same time. That means Kiro may do several things in parallel, so reviewing the list before you run it is worth the time.

Step 5: Run it in small pieces and test as you go

You can run tasks one at a time. For a beginner, that is the safer choice. After each task, look at what changed. After the page exists, try it yourself:

• Enter a correct order and phone. You should see the status.
• Enter a correct order and a wrong phone. You should see the general message and nothing else.
• Enter a made-up order number. You should see the same message.
• Try twelve lookups quickly. The limit should stop you.

These are your own tests, and they come straight from the sentences you approved. If one fails, you know exactly which sentence was not met. That is much easier than trying to find a bug in code you cannot read.

Step 6: Keep the spec up to date

When you want a change later, change the spec first. Say you want to add "estimated delivery date". Add that to the requirements, check the design, and add the tasks. The spec then stays an honest record of what the software is meant to do. Six months later, when you or a new developer need to understand the feature, the files explain it. This is the answer to the problem of software that nobody understands any more.

A second example: a bugfix spec

Illustrative example: this bug and these notes are made up, and are not real Kiro output.

Suppose customers sometimes get charged twice. Without a plan, a quick fix might add a check and break something else. With a bugfix spec, you start by writing down three things in bugfix.md.

Current behaviour
When a customer refreshes the payment page after paying, the
order is marked paid a second time and a second receipt is sent.

Expected behaviour
An order is marked paid once. A refresh shows the same receipt
and does not send another.

Behaviour that must not change
- A failed payment can still be retried.
- A refund still works on a paid order.
- Orders paid by bank transfer are still confirmed by the owner.

The last list is the one most people skip. It protects you. When the fix is made, you test the "must not change" items too. Many bugs return because a fix quietly broke a nearby feature, and nobody had written down what "nearby" meant.

A checklist for reviewing any spec

You can use this list on any requirements file, from Kiro or from any other tool. It takes about ten minutes.

1. Count the "never" sentences. Is there at least one for every kind of harm you can think of: wrong money, wrong person, lost data?
2. Look for words that cannot be tested. "Fast", "secure", "easy" and "user-friendly" mean nothing until you attach a number or an action.
3. Check each sentence for one idea. A sentence with "and" in the middle often hides two requirements, and one of them gets lost.
4. Look for the sad paths. What happens when the network fails, the input is empty, the user is not logged in, or the same request arrives twice?
5. Look for things that were added without you asking. AI tools sometimes add features. Each one is more to build and more to break. Remove what you do not need.
6. Match requirements to tasks. Every requirement should appear in the task list, and every task should serve a requirement.
7. Read it out loud to someone else. If they cannot explain it back to you, it is not clear yet.

This habit is worth building even if you use a tool with no specs at all. It is the same thinking a careful developer does before a big change.

Steering files: teaching Kiro your rules once

A spec is for one feature. Steering is for the whole project. The documentation describes steering files as markdown files that give Kiro lasting knowledge about your project, so you do not have to repeat yourself in every chat.

They live in .kiro/steering/ in your project. Kiro can create three starter files:

• product.md is about what the product is for, who uses it, and the goals.
• tech.md lists the tools and technical limits.
• structure.md explains how files are organised and named.

You can also keep global files in ~/.kiro/steering/ that apply to every project. If a global rule and a project rule disagree, the project rule wins. A file can load always, only when certain files are involved, only when you ask for it, or when a request matches its description. For a non-expert, the best use is simple. Write down the rules that must never be broken, in plain words, such as "never log customer phone numbers" or "all prices are in naira". Then every spec starts from those rules.

Hooks: automatic checks

The documentation also describes hooks. A hook runs a command, or gives the agent a prompt, when something happens. Examples on the page are a hook that runs a code-style fixer each time the agent saves a certain kind of file, and a hook that asks "Submit this session's results?" before a final step runs. Hooks are stored as JSON files in .kiro/hooks/.

As a beginner you can leave hooks for later. But it is good to know they exist. They are one way to make a check happen every time, without relying on you to remember.

Bugfix specs: the same idea for broken things

When something is broken, the documentation describes a bugfix spec. Its main file, bugfix.md, covers three things: the current behaviour, the expected behaviour, and the behaviour that must stay the same. That third part is the clever one. Many fixes break something else, because nobody wrote down what was working. Making yourself list what must not change is a strong habit, with or without Kiro.

What to expect the first time

The first spec feels slow. You will read more than you expected, and you may be tempted to approve everything and move on. Do not. Plan for the first feature to take longer than a plain chat would. The time comes back later, when you change the feature and the files still explain it. A good first project is something small and real, with a few "never" rules, like our order lookup. Avoid starting with your biggest idea. You will make mistakes in your first few specs, and it is better to make them where they are cheap.

What it costs, and what it does with your work

Two practical points deserve a clear look before you begin.

Cost. Kiro's pricing page, read on 9 October 2026, shows a free plan with 50 credits a month. Paid plans are Pro at $20 for 1,000 credits, Pro+ at $40 for 2,000, Pro Max at $100 for 5,000, and Power at $200 for 10,000, each per month. Extra credits cost $0.04 each. The page says a credit is a unit of work, that simple prompts can use less than one credit, and that complex work such as running a spec task typically uses more than one. So the free plan will not stretch far if you run many tasks. Prices exclude tax, and the page says model availability varies by country. You may pay in dollars, so check that your card works abroad.

Your data. Kiro's data protection page says that for Free Tier and individual subscribers, content may be used for service improvement unless you opt out, and that this includes model training. It says enterprise users are not included. In the IDE, the opt-out is under Settings, User, Application, then Telemetry and Content. It also says that free users' inputs may be stored for up to 60 days for abuse detection, and that opting out does not stop that. For free and individual users, content is stored in US East (N. Virginia). If you work with customer data or code that belongs to a client, read this page before you start and decide if the free plan is right for that work.

A related point from the security page: Kiro runs in your own environment, and the agent can reach local files. The documentation says that supervised mode is a review workflow, not a security control or a sandbox. Do not point it at a folder that holds secrets you cannot afford to expose. Kiro has a .kiroignore file to keep files away from the agent, and writes to certain files, such as mcp.json and .git, need your approval in the IDE.

When spec-driven development is too much

It is not always the right tool. A spec takes time, and in Kiro it also uses credits. For a tiny change, such as fixing a typo or changing a colour, a normal chat is fine. Quick Spec is good for features you already understand well. The full flow earns its cost when:

• the feature touches money, accounts or personal data;
• other people will use the result;
• you will need to change it later;
• or you are not sure what you want and need to think it through.

Writing a spec is also useful when you do not use Kiro at all. You can ask any AI to draft requirements, then read them yourself and correct them. The tool matters less than the habit. If you are still deciding on a tool, our guide to Kiro vs Cursor compares the two, and our guide to adding an MCP server to Claude Code covers connecting outside tools.

Mistakes to avoid

• Approving what you did not read. The approval step only helps if you use it.
• Using Quick Spec for something risky. It skips the gates on purpose.
• Writing vague sentences. "The page should be secure" cannot be tested. "The page must not show any detail of someone else's order" can.
• Leaving out what must not happen. Most harm comes from missing "never" sentences.
• Treating a spec as a test. A written requirement does not prove the code works. You still test.
• Forgetting the cost and data terms. Check credits and the privacy page first.
• Letting the spec go stale. Update it when the software changes.

The idea in one paragraph

Spec-driven development moves your effort to the cheapest place. It is cheap to fix a sentence. It is expensive to fix a finished feature that is wrong. Kiro builds this order into the tool: requirements, then design, then tasks, each one open for you to read. If you are not a developer, that is the part you can do well. You know what the business needs, and what must never happen. A spec lets you put that knowledge to work, even if you never read a line of code. For the wider question of whether AI-built software is safe to depend on, read is vibe coding bad for non-developers.