Method reference · workflow
Spec-Driven Development (Spec Kit / Kiro)
First, you write a spec in plain English. The spec becomes the single source of truth. An AI agent uses it to generate, test, and check the code. You edit this one document directly. This is the most disciplined of the curated-store methods.
GitHub Spec Kit · AWS Kiro
Single canonical doc
Our benchmark: most portable curated store
…still drifts / drops under lag
What it is
Spec-Driven Development (SDD) is the opposite of writing code first. You write a spec, and an AI agent builds the code from it. Two main tools use this method: GitHub Spec Kit and AWS Kiro. GitHub's tool uses a command-line interface and chat commands like /specify, /plan, and /tasks. AWS Kiro is an IDE that guides you from requirements → design → tasks. Martin Fowler’s team describes a range of approaches. In one, the spec is a guide you later throw away. In another, the spec remains as a contract. The most ambitious approach uses the spec as the only source. Humans only edit the spec, and the code is always regenerated from it. This last approach is the least proven (martinfowler.com).
Setup
- Spec Kit: Install the CLI (uv tool install specify-cli …), then run specify init <project>.
- Run these commands in order in your agent: /constitution (principles), /specify (the what), /plan (the how), /tasks (the breakdown), and /implement.
- Kiro: Open a feature. Kiro generates a requirements.md file with user stories. You approve it. Then it generates a design.md file. You approve that. Finally, it creates tasks.md and runs the tasks.
- Commit the spec files with your code. This lets you track changes to your project's goals in pull requests.
Sample directory structure
# GitHub Spec Kit — numbered per-feature folders
.specify/
└─ memory/constitution.md # project-wide non-negotiable principles
specs/
├─ 001-user-login/
│ ├─ spec.md # the WHAT: requirements, flows (no tech)
│ ├─ plan.md # the HOW: architecture, stack
│ └─ tasks.md # ordered, actionable task list
└─ 002-two-factor-auth/ …
# AWS Kiro
.kiro/
├─ steering/ # product.md, structure.md, tech.md (persistent context)
└─ specs/<feature>/
├─ requirements.md # EARS: "WHEN <event> THE SYSTEM SHALL <behavior>"
├─ design.md
└─ tasks.md
Pros & cons
Strengths
- One true, editable source. The spec is a file you commit and version. You can edit it directly and see changes in pull requests. Your project's goals live with the code, not in an old wiki.
- A structured process. This is better than coding from a vague idea. Each stage can be reviewed. This helps you find unclear requirements before any code is written.
- Shared rules. A file like constitution.md sets rules for the whole project. This keeps multiple developers and AI agents on the same page. It also helps new team members get up to speed.
- Good for breaking down problems. It can turn a simple prompt into detailed requirements. It also helps you think about edge cases you might have missed.
Weaknesses
- Too many spec files. The process can create a lot of Markdown files. Reviewing all of them can be harder than reviewing the code itself.
- Specs get out of date. As you add more features, older specs can become inaccurate. There is no easy way to combine or update them.
- Hard to make changes. The process mostly flows in one direction. It's difficult to go back and forth between editing the spec and the code.
- Feels like the old "waterfall" method. Planning everything upfront doesn't work well when you need to make quick changes.
- Too much process for small tasks. A simple change can trigger the full process. This creates many files for requirements, design, tasks, and tests.
- Agents might ignore the spec. Even after all this work, the AI agent might not follow the spec completely.
Common user feedback
The best independent source is a hands-on review by Martin Fowler. The complaints about specs getting out of date come from Spec Kit's own issue tracker. We've noted that GitHub and AWS promote their own tools.
- Reviewing specs can be harder than reviewing code. When testing Spec Kit, Fowler said: “I’d rather review code than all these markdown files.” With Kiro, a small bug created “4 user stories with 16 acceptance criteria.” He called it “using a sledgehammer to crack a nut.” (martinfowler.com).
- Specs get outdated as features are added. This feedback comes from the tool's own issue tracker. One user said, “over time and with the multiplication of features, some descriptions become outdated”. An early spec might become “partially outdated,” and there's no way to merge the changes (spec-kit #620).
- You can't easily edit the spec. One user reported, “/speckit.specify always creates a new branch + artifact… not for iterative editing or updates”. They found that workarounds were “unclear, error-prone” (spec-kit #1191).
- It feels like the old "waterfall" method. In a Hacker News thread, one person wrote: “as soon as you want quick changes you have to abandon the spec. Iterating the spec and the code quickly is impossible for any… complex project.” (Hacker News).
- The process wastes time and money. One Kiro user said it created many tests before they even knew if the feature was a good idea. They also noted that “Asking Kiro to summarize context burns 1 vibe request. Then re-entering a refined prompt burns another.” (dev.to).
How it did in our benchmark
We used a single SPEC.md file that held six key facts. The score shows how many of those six facts were still correct. We took the average of three runs.
The spec-driven method was the
most portable curated store in our study. It uses a single, small document. Any AI model from any company could read and use it, scoring 5.0–6.0 across all six models. This is better than a Memory Bank, where outdated files can confuse weaker models. It is the most disciplined approach. But it has a major weakness. The spec is only correct
if you remember to update it with every change. If you forget, the spec becomes outdated. When that happens, its score drops to ~3–4/6, just like any other manually updated method.
See the full results →