Framework · AI & design · 3 min read
Spec-driven development
A way of working where every feature starts from written specs (requirements, then design, then tasks) that humans review and agents implement, so UX can own the experience before any code is generated.
- 1Requirements
Users, flows, states, rules and acceptance criteria. UX owns the experience.
"What must the user be able to do?" - 2Design
How it is built: components, tokens, data and architecture decisions.
"Which components and data?" - 3Tasks
Small, checkable steps that an agent can implement one by one.
"What is the next step?" - 4Implement
Agents generate the code; people review it against the spec.
"Does it match the spec?"
Humans review each spec before generation. When behaviour changes, update the spec first.
Use it when
- Engineering starts using a spec-driven tool and asks design for "the requirements" in a structured format.
- AI-generated features keep missing states, edge cases or accessibility needs that the designer knew about.
- You want design decisions to live next to the code, versioned and reviewable, instead of only in a design file.
How to use it
- Learn the engineering flow. Find out which structure your engineers use. Common ones go from requirements to design to tasks, for example GitHub Spec Kit (constitution, specify, plan, tasks, implement) and AWS Kiro (
requirements.md,design.md, tasks). Output: the spec files and steps your team uses. - Claim the experience sections. Agree with engineering that UX owns users, flows, states, rules, data shown, accessibility and acceptance criteria for the experience. The UX spec becomes an input to the engineering spec. Output: a named owner for each section of the spec.
- Write the spec from your design spec. Use your team's AI-ready spec template (see Design specs for AI) and reference design-system components and tokens by name. Keep the stable rules in the Context files. Output: a reviewed experience section in the spec.
- Review the spec before generation. Run a short spec review with the PM and an engineer: is every state covered, every rule clear, every open question listed? Treat it as the "Definition of Ready" for AI generation. Output: an approved spec, with open questions resolved or marked.
- Keep the spec and the code together. Version the spec in the repository with the code. When behaviour changes, update the spec first, then regenerate or adjust. Check the result against the spec in design QA. Output: a spec that still matches the shipped feature.
Worked example
An internal operations platform with 6 product teams. Engineering on the billing team adopts a spec-driven tool. The first agent-built "invoice exceptions" view works but has no empty state, no keyboard support and invents its own status labels.
| Section of the spec | Before | After the designer owns it |
|---|---|---|
| Users | "Billing users" | Billing clerks who clear 100+ exceptions a day, mostly by keyboard |
| States | Not written | Empty, loading, error, 5,000 rows, partial failure |
| Rules | Not written | Exceptions older than 5 days are flagged; only leads can write off amounts |
| Design system | Not written | Data table, status badge and bulk action bar from the library; status tokens only |
| Accessibility | Not written | WCAG 2.2 AA, visible focus, no colour-only status |
| Acceptance criteria | "Shows exceptions" | Clerk can filter, select and resolve 20 exceptions without a mouse |
The second generated version needs far fewer review comments, and the spec review takes 20 minutes instead of several design QA rounds.
Watch out for
- Letting the agent write the experience. If the spec says only "show exceptions", the agent decides the flow, the states and the wording. Write those sections yourself.
- Reviewing code instead of specs. Fixing behaviour in generated code is slower than fixing one line in the spec. Review the spec first.
- Specs that drift. A spec that is not updated when the feature changes becomes misleading for the next agent run. Version it with the code.
- Specs that look complete but aren't true. AI can draft a polished spec full of assumptions. A human checks every rule against what users really need.
Template
Copy this into the experience part of your spec (for example a requirements.md or a spec file in the repository).
## Experience (owned by UX) Owner: Reviewed on:
### Users and context
- Who, how often, in what situation, with what expertise
### Flow
1.
2.
### States
- Empty / Loading / Error / Large data / Partial failure / No permission
### Rules
- Business and interaction rules, edge-case policy
### Design system
- Components (library names):
- Tokens:
- New components needed? -> contribution process
### Accessibility
- WCAG 2.2 AA; keyboard; focus; no colour-only status
### Acceptance criteria (experience)
- [ ]
- [ ]
### Open questions
-