Table of Content
What is spec-driven development?
Spec-driven development is a way of building software with AI coding agents where a written specification comes first and the code follows from it. You describe what to build and why, turn that into a plan and a list of tasks, and only then let the agent implement, with tests in every change and a person reviewing the result. The spec, not a one-off prompt, is the source of truth, which is what keeps agent-written code reviewable.
TL;DR
- Spec-driven development puts a written spec, plan and task list ahead of the code. Agents implement against them instead of improvising from a chat prompt.
- Two public toolkits describe the same idea. GitHub Spec Kit (MIT licensed, per its README) runs constitution, specify, plan, tasks, implement and converge steps. Kiro (per its documentation) produces three files per spec: requirements, design and tasks.
- We used the method on a real build, ArchetypeDG, a custom headless commerce platform delivered in about 8 weeks. Per our published case study, 75% of commits carried an AI co-author credit, and the repository holds 218 API endpoints and 395 automated test files.
- The rules that kept it safe were simple: no feature without a written spec, agents may not invent APIs or schema, tests ship with every change, and humans decide on risk.
- A worked example below compares time spent on one feature with a spec-first process and with an improvised prompt. A second example checks coverage against a 95% target on money paths.
- It is not free. The method adds up-front writing, and it is overkill for a throwaway script. The table near the end says when to skip it.
- The hours and coverage figures in the worked examples are illustrations built for this guide. The ArchetypeDG numbers are from our own case study and say how they were measured.
- CommercePundit builds software with AI agents under this process. See the last section.
What does spec-driven development look like step by step?
Spec driven development, often written without the hyphen, has a similar sequence in the public tools. GitHub Spec Kit, whose README we read in November 2026, describes it as defining what to build and why, then turning the specification into a plan, tasks and working code. It sets a project constitution once and repeats the other steps for each feature. Kiro, per its documentation, gives every spec three files, one per phase.
| Step | GitHub Spec Kit command (per README) | Kiro file (per docs) | What a person does |
|---|---|---|---|
| Principles | Constitution: the project guiding principles, such as code quality, testing and maintainability | Not part of the three per-spec files; check Kiro documentation for project-level rules | Write the rules the agent may not break, once |
| What and why | Specify: describe the feature | requirements.md: user stories and acceptance criteria | Write or approve the requirements in plain words |
| How | Plan: technical approach, such as framework and data storage | design.md: architecture and implementation considerations | Review the design before any code |
| Break down | Tasks: split the plan into tasks | tasks.md: discrete, trackable tasks | Check the tasks are small and testable |
| Build | Implement: build the feature | Run tasks one at a time or together | Review the changes and tests |
| Check | Converge: verify the result; repeat implement and converge until it reports Converged | Task status tracked as work runs | Accept only when the checks pass |
The names differ and the shape is the same: intent, design, tasks, implementation, verification. You do not need either tool to work this way. A folder of markdown files and a team habit is enough. If you want the background on loose, prompt-first coding, our guide to what vibe coding is explains it and where it fits.
How is spec-driven development different from vibe coding?
| Question | Spec-driven | Prompt-first (vibe coding) |
|---|---|---|
| Starting point | A written spec with acceptance criteria | A chat prompt |
| Source of truth | The spec and plan files in the repository | The conversation history, which is easily lost |
| Where decisions live | In reviewable documents before code exists | Scattered across prompts and generated code |
| Review | Compare the code to the spec and the tests | Read the code and hope it matches intent |
| Best for | Production software with money, accounts or compliance | Prototypes, experiments and throwaway tools |
| Main risk | Time spent writing specs for small jobs | Confident code that nobody can explain |
Both have a place. The question is what a mistake costs. If an error can double-charge a customer or expose an account, write the spec. If you are testing an idea over a weekend, do not.
Worked example: how we ran it on a real build
ArchetypeDG is a US direct-to-consumer brand. We built its custom headless commerce platform, an operations console and a partner portal in about 8 weeks, using AI coding agents under a spec-first process. The facts below are from our published case study, which states how each number was measured.
| Metric | Result | How it was measured (per the case study) |
|---|---|---|
| Time to build | About 8 weeks | First commit to a production-ready build |
| AI-assisted delivery | 75% | Commits carrying an AI co-author credit divided by all commits |
| API endpoints | 218 | Route handlers in the codebase |
| Automated test files | 395 | Unit, API and browser test files, plus visual, accessibility and performance suites |
| Business modules | 40+ | 19 storefront and 22 admin modules in the module inventory |
| Automated workflows | 12 | Event-driven and scheduled jobs such as payment guards, labels, returns and emails |
The 75% figure measures who co-authored commits, not how good the code is, and the case study says so. What made the speed safe was the process around it. Per the case study, the team agreed an architecture plan, decision records and a written engineering constitution before code. The constitution kept agents inside the rules: spec, plan and tasks first, tests with every change. See the full project in our ArchetypeDG case study.
The rules that kept AI-written code reviewable
| Rule | What it means in practice |
|---|---|
| Spec first | No feature without a written spec |
| Guardrails | Agents may not invent APIs, schema fields or cloud settings |
| Tests required | Payments, auth, inventory and returns carry a 95% coverage target |
| Humans decide | Risk signals advise a person and never block an order on their own |
| Hardening in the pipeline | Automated security scans run on every change; production waits for manual approval |
The rule about not inventing APIs matters most. Language models fill gaps confidently, and an endpoint or database column that does not exist is a bug that looks like working code. A spec that names the real contracts, and a reviewer who checks against it, closes that gap.
Worked example: where does the time go on one feature?
These hours are assumptions for one medium-sized feature, such as a returns workflow. Replace them with your own. The point is the shape: spec-first moves effort to the front, and prompt-first moves it to the back as rework.
| Phase | Spec-first (hours) | Prompt-first (hours) |
|---|---|---|
| Write the spec and acceptance criteria | 4 | 0 |
| Plan and design review | 2 | 0 |
| Break into tasks | 1 | 0 |
| Prompt the agent | included | 0.5 |
| Agent implements | 3 | 3 |
| Human review and testing | 4 | 4 |
| Rework after review finds mismatches | 0 (assumed small) | 10 |
| Total | 14 | 17.5 |
With these assumptions the spec-first route finishes in 14 hours against 17.5, and it leaves a spec, a plan and tests that the next change can reuse. If your rework estimate is only 3 hours instead of 10, prompt-first wins on this one feature: 10.5 hours. The method pays off on features where a mismatch is expensive and on projects with many features, because the spec and constitution carry forward.
Worked example: a coverage gate on money paths
A rule such as 95% coverage on money paths only works if the pipeline checks it. The module names and percentages below are invented to show the check, not data from any client.
| Module | Type | Coverage | Required | Result |
|---|---|---|---|---|
| Payments | Money path | 96% | 95% | Pass |
| Authentication | Money path | 97% | 95% | Pass |
| Inventory | Money path | 93% | 95% | Fail by 2 points |
| Returns | Money path | 95% | 95% | Pass |
| Email templates | Other | 71% | No gate | Not gated |
| Admin reports | Other | 64% | No gate | Not gated |
One gated module fails: Inventory is below the target, so the change does not merge until tests are added. The two ungated modules can lag without blocking a release. Naming which paths are critical, and gating only those, keeps the rule strict where it matters and light elsewhere. Our guides to regression testing and web application testing cover how to build the test side of this.
What should a feature spec contain?
Spec template
Goal and user problem. Out of scope. Users and roles. Acceptance criteria written as checks. Data it reads and writes, naming the real tables or contracts. External services and the real API calls it may use. Error and edge cases. Security and privacy notes. Test plan, including which paths are money or account paths. Open questions for a person to answer before building.
The last line matters. A spec with open questions is honest. The agent should stop and ask, not guess. Keep specs short enough that a person will read all of them: one page for a small feature is plenty.
When is spec-driven development overkill?
| Situation | Use a spec? | Why |
|---|---|---|
| A throwaway script or one-time data fix | No | The cost of a mistake is low and the code will be discarded |
| A prototype to test an idea | A one-paragraph goal | Speed matters more than structure |
| A feature that touches payments, accounts or personal data | Yes, in full | Errors are expensive and need an audit trail |
| A product that will live for years | Yes | The spec and plan become the documentation the next developer inherits |
| Work with several people or several agents | Yes | The spec is how they stay aligned |
| A well-understood small bug fix | A short note | Reproduce, fix, add a test |
For early products, a lighter version works: a spec for the money and account paths, a paragraph for the rest. Our MVP development guide shows how to scope a first release so the spec effort goes where it counts.
How do you keep AI agents safe on a real codebase?
| Control | What it does |
|---|---|
| Written constitution | Rules the agent may not break, agreed before code |
| Real contracts in the spec | Names actual APIs and schema so the agent does not invent them |
| Tests with every change | Catches behavior drift immediately |
| Review by a person | Compares the change to the spec, not just to itself |
| Sandboxed execution | Runs agents away from your machine and secrets; see Docker sandboxes for AI coding agents |
| Gated release | Staging deploys automatically; production waits for a person |
| Acceptance testing by real users | Catches the gap between spec and need; see user acceptance testing software |
What mistakes weaken spec-driven development?
| Mistake | What happens | Fix |
|---|---|---|
| Writing the spec after the code | The spec describes what exists, not what was wanted | Write and approve it first |
| Specs that are too long | Nobody reads them; the agent skims them | One page per feature; link details |
| No acceptance criteria | No way to say it is done | Write criteria as checks |
| Letting the agent invent contracts | Phantom endpoints and columns | Name real contracts; review against them |
| Gating everything on coverage | Slow merges on low-risk code | Gate money and account paths only |
| Treating AI share of commits as a quality metric | Speed is mistaken for correctness | Report tests, defects and review outcomes beside it |
Frequently Asked Questions
What is spec-driven development?
It is a way of building software with AI coding agents where a written spec, plan and task list come first and the code follows. The spec is the source of truth and a person reviews the result against it.
How is spec-driven development different from vibe coding?
Vibe coding starts from a chat prompt and iterates on the output. Spec-driven development starts from a written spec with acceptance criteria and keeps the spec in the repository, so intent is reviewable. Vibe coding suits prototypes. Specs suit production software.
What is GitHub Spec Kit?
It is an open-source toolkit, MIT licensed according to its README, for spec-driven development with a coding agent. It sets a project constitution and then runs specify, plan, tasks, implement and converge steps for each feature.
What is Kiro spec-driven development?
Kiro describes specs as structured artifacts that turn ideas into implementation plans. Each spec produces three files, requirements, design and tasks, one per phase.
Does spec-driven development slow you down?
It adds up-front writing, but it can save time on features where rework is expensive, because intent is agreed before code. On a throwaway script it is overkill and slows you down.
What is a project constitution in spec-driven development?
It is a short set of rules the agent must follow, such as testing requirements, code quality standards and a ban on inventing APIs or schema. It is written once and applies to every feature.
How do you stop AI agents from inventing APIs?
Name the real APIs and schema in the spec, forbid invention in the constitution, require tests with every change and have a person review the code against the spec.
Can AI agents write most of the code safely?
They can contribute a large share when the process is controlled. In our ArchetypeDG build, 75% of commits carried an AI co-author credit, alongside specs, tests and human review. That share measures authorship, not quality.
What should a good spec include?
The goal, out-of-scope items, users and roles, acceptance criteria written as checks, the real data and APIs involved, edge cases, security notes, a test plan and open questions.
Who should use spec-driven development?
Teams building production software that handles money, accounts or personal data, products that will live for years and anyone coordinating several developers or agents. Prototype builders can use a lighter version.
Bottom Line
Spec-driven development is a discipline, not a product: write what you want, plan it, break it down, let the agent build it and check the result against the spec. It earns its cost on software where mistakes are expensive. If you want a team that builds with AI agents under this process, see our AI development services and vibe coding services.