Table of Content

Read time

8 minutes

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.

Mihir Ajmera
Account Manager

Mihir Ajmera is a leading Technical Account Manager at Commerce Pundit, with 15+ years of experience in Enterprise-level Technologies and Digital Transformations, where he has earned a reputation for tackling difficult business issues with powerful and scalable Artificial Intelligence AI-based solutions. Mihir is an accomplished leader and prolific solution provider who provides valuable tips about implementing effective technological projects throughout their entire life cycle, from conception and architectural design to Implementation and Optimization, with the focus on maximizing business benefits by aligning them with technological innovations. His professional experience includes AI-Automation, Large Language Models (LLM), Custom Software Development, Enterprise e-commerce platforms, Cloud Architectures, System Integrations, and Strong Customer Success and account management skills.

Expertise: AI and Automation Custom Solutions Enterprise eCommerce

What our clients says

An assemblage of our most passionately crafted works alongside forward-thinking clients and friends throughout the years.

Eric Truong
Eric Truong CEO, LA Nails Supply
" Commerce Pundit’s collaboration created a stunning website representing our beauty nails business. Their SEO strategies boosted rankings and traffic.Transparent communication and prompt feedback incorporation exceeded expectations. "

0%

Increase in orders

0%

Increase in revenue

0%

Increase in site traffic

Contact Us