Marcus Andrey Study
Ler em português Library

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.

  1. 1Requirements

    Users, flows, states, rules and acceptance criteria. UX owns the experience.

    "What must the user be able to do?"
  2. 2Design

    How it is built: components, tokens, data and architecture decisions.

    "Which components and data?"
  3. 3Tasks

    Small, checkable steps that an agent can implement one by one.

    "What is the next step?"
  4. 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.

Spec-driven development turns written specs into agent work, with human review between each step.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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
-
Source
GitHub Spec Kit, AWS Kiro
Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close