Spec-first for AI coding agents See the coupon case

Write spec.md before
the agent codes.

Spec coding means turning a vague AI coding request into a short, reviewable spec before the agent writes its first diff. In 78 recorded Claude Code runs, 28 of 30 runs with a spec passed every hidden check; 12 of 48 runs without one did.

−"Build coupon codes for checkout. Make it work nicely."
+AC-1: an expired code shows an inline error, total unchanged
+AC-2: a code already used on another order cannot be applied twice
+AC-3: the payment intent amount equals the discounted total
The problem

AI doesn't fail at writing code. It fails at guessing the missing spec.

Most rework isn't code quality—it's misaligned assumptions. A one-line prompt leaves every unstated decision to the model, and the model will make one. If you cannot write the spec, the feature probably is not ready to build.

01

Scope drift

The assistant adds adjacent refactors, new fields, or product behavior that nobody reviewed.

Fixed by ## Out of scope
02

Untestable acceptance

The PR looks plausible, but reviewers cannot map the diff to clear user-visible behavior.

Fixed by ## Acceptance
03

Missing evidence

Tests, screenshots, logs, rollout signals, and rollback paths are invented after the code lands.

Fixed by ## Evidence
Measured, not assumed

We ran the same tickets with and without a spec.

Claude Code got three ordinary tickets: a coupon feature, an API error cleanup and a schema change. We ran them 78 times across four Claude models and scored every run with hidden tests frozen before the first one. One-line prompts usually produced code that ran. The spec decided whether it was the code that was asked for.

With a spec, 28 of 30 runs passed every hidden check

Across Opus 5.5, Sonnet 5.5, Haiku 4.5 and Fable 5.1, the smallest and largest models landed within two runs of each other.

Compare the four models

Without a spec, 12 of 48 runs did

Failures were rarely crashes. They were decisions nobody approved: a dropped column that billing still read, an error shape the mobile app depended on, a coupon with no reuse limit.

Open every prompt, diff and score

One prompt, three runs, three different checkouts

One vague coupon ticket came back with two reuse policies and two ways of charging a coupon that expires during checkout. The three spec runs matched each other.

Vibe coding vs spec coding
One change, one packet

Anatomy of a reviewable spec

A single spec.md is enough for small work. Riskier changes get a tiny folder that separates behavior, tasks, and evidence, so reviewers can challenge the right layer. Here is the same coupon change, file by file.

  1. 01

    Context

    Where this lives, which files already matter, and which existing patterns should be reused.

  2. 02

    Goal

    The user or system behavior that changes after the work ships.

  3. 03

    Plan

    Reviewable implementation steps, named files, dependencies, and test commands.

  4. 04

    Out of scope

    The adjacent refactors, nice-to-haves, and tempting side quests the agent must not start.

  5. 05

    Acceptance and evidence

    Observable criteria plus the tests, logs, screenshots, or rollout signals needed before merge.

docs/specs/checkout-coupon/
## Context
Existing checkout totals are computed in billing/totals.ts.

## Goal
Apply one valid coupon before payment is created.

## Plan
1. Validate coupon through a small API endpoint.
2. Update checkout summary after validation.
3. Keep draft order state idempotent.

## Out of scope
- coupon admin UI
- multi-coupon stacking
- unrelated totals refactor

## Acceptance
- expired coupons show inline error
- payment amount uses discounted total
- refresh keeps the selected coupon
Positioning

How it sits next to neighboring methods

Spec Coding is not a full product process and not a heavy formal spec system. It is the small working file between a vague chat prompt and a production diff.

MethodPrimary artifactBest for
Vibe codingchat onlyExploration, throwaway scripts, and prototypes where being wrong is cheap.
spec-codingfeature.spec.mdDay-to-day feature work where alignment matters but a 30-page PRD is too much.
SDD / formal specspec.md + design.md + tasks.mdRegulated systems, multi-team delivery, and changes where wrong code is expensive.
Working BackwardsPR / FAQProduct framing before implementation. Spec Coding handles one feature below it.
Shape Uppitch + appetiteCycle planning and shaping. The spec is the implementation agreement inside the shaped work.

Terminology. People search for this practice as spec-first, spec as code, code spec, spec code, or coding spec. On this site, all of those point to the same practical artifact: a short spec.md kept close to the code and reviewed before implementation.

Workflow

AI coding workflow

Use this path when the next step is a real change in a real repo. Each step points to a page, template, example, or generator you can use immediately.

Template library

Open, copy, edit, review.

Templates are presented like repo files because that is how teams actually use them. Copy puts the Markdown on your clipboard and previews it below.

FileWhen to useLinesUpdatedAction
feature.spec.md Standard feature work: new endpoint, new screen, or new flow. 42 2026-05-15 open
api.spec.md API contracts, request/response examples, errors, and compatibility rules. 48 2026-05-15 open
database.spec.md Schema changes, indexes, constraints, backfills, and rollback planning. 39 2026-05-15 open
spec.md Goal, non-goals, acceptance criteria, open questions, and evidence required. 36 2026-05-11 open
design.md Architecture choice, interfaces, rejected alternatives, rollout, and rollback. 52 2026-05-11 open
tasks.md Reviewable implementation slices with allowed files and test commands. 44 2026-05-11 open
evidence.md Tests, screenshots, logs, metrics, manual checks, and release stop signals. 31 2026-05-11 open

All 9 templates

FAQ

Questions teams ask first

What is spec coding?

Spec coding is writing a short, reviewable spec (goal, scope, out of scope, acceptance criteria, and the evidence you expect) before an AI coding agent changes code, then reviewing the agent's diff against that spec instead of against the chat history. It is the hands-on form of spec-driven development (SDD): the spec lives in the repo as spec.md and stays the source of truth for the change.

Won't specs slow us down?

The most expensive specs are the ones you skip. A short spec that catches one scope ambiguity before code review saves a week of rework. Start with the decisions that have historically caused you the most production pain: acceptance criteria, edge cases, and rollback plans.

If I already use AI to code, do I still need specs?

Even more. Without specs, AI drifts: extra features, changed fields, non-stop rewrites. Specs are guardrails.

Is it good for solo builders and small teams?

Yes — small teams suffer most from lost context and verbal agreements. Specs make you productive even after context breaks.

What if requirements change mid-sprint?

Update the spec. That's the point — specs are living documents, not contracts carved in stone. Version them in git alongside your code. The spec always reflects current truth.

How is a spec different from a PRD?

A PRD describes what the product should do from a business perspective. A spec describes what the code must do from an engineering perspective — with acceptance criteria, edge cases, and testable contracts. They complement each other.

Is spec coding the same as spec-first, spec as code, or code specs?

They overlap. Spec-first describes the habit of writing behavior before code. Spec as code keeps that spec in the repository. Code spec, spec code, and coding spec are common search phrases for the same small artifact: a reviewable spec.md that guides implementation.

Next change

Write the spec before the next prompt.

Paste one requirement, get spec.md, tasks.md, acceptance criteria, and an evidence checklist. Generated locally in your browser.