The One-Page Spec

Your AI will build anything you describe. That's the problem. Without a spec, every prompt is a new idea, and three weeks later you have forty half-finished features and nothing a customer can use.

Professional teams solve this with a short written plan before any code exists. You don't need a 30-page requirements document. You need one page.

The template

Copy this into a file called SPEC.md at the root of your repo:

# <Product name> — v1 spec

## Who is it for?
One sentence. A real person or role, not "users".

## What problem does it solve?
The pain, in their words. What do they do today instead?

## What does v1 do? (max 3 user stories)
- As a <role>, I can <action> so that <outcome>.
- ...

## How do we know it works? (acceptance criteria)
- Given <situation>, when <action>, then <result>.

## Not in v1 (the parking lot)
- Ideas we like but are NOT building yet.

## Done means
- Deployed to production, tests passing, one real user has used it.

Why three stories?

Three is enough for something useful and too few to hide in. If you can't pick your top three, you don't understand the problem yet. Go talk to the person you're building for.

Writing acceptance criteria the AI can use

Acceptance criteria are the most valuable part of the page, because you can turn them straight into tests (see Make the AI write the test first).

Bad: "Invoices should work properly."

Good:

• Given a customer with an unpaid invoice, when they open the portal, then they see the amount due and a Pay button.
• Given a paid invoice, when the customer opens it, then the Pay button is gone and the status says "Paid on <date>".

Each line is concrete, testable, and tells the AI exactly what "done" looks like.

Use the spec in every session

Start each AI coding session by pointing the agent at the spec:

Read SPEC.md. We are working on story 2 only. Do not add anything that isn't in the acceptance criteria. If you think something is missing, tell me instead of building it.

Most AI coding tools also support a project instructions file (CLAUDE.md, .cursorrules, AGENTS.md). Put a line in it saying "SPEC.md is the source of truth for scope."

Your assignment

1. Write SPEC.md for the thing you're building right now. Keep it to one page.
2. Move everything beyond three stories into Not in v1.
3. Post it on the Shop Floor under Spec Review and ask: "What should I cut?"