What Is Spec-First Development? (Complete Guide)

Spec-first isn't a methodology. It's a forcing function: you write down the hard decisions before code makes them for you, and you accept that half of what you wrote will turn out wrong. That's fine. Wrong-and-written beats right-and-undocumented every time.

What spec-first actually means

Strip the buzzword and you get something uncomfortable: you have to decide things you'd rather not decide yet. What happens when the payment gateway times out? What's the exact behavior when two users edit the same record simultaneously? Whose job is it to approve the rollback? Most teams prefer to discover these decisions during implementation, because at least then the problem feels concrete. Spec-first says no — surface them before anyone writes a test.

The spec is just a document. The real artifact is the argument you have while writing it.

Why most attempts fail

A familiar failure looks like this: a team spends weeks producing a long spec that answers none of the actual questions. The document exists. It gets reviewed. Everyone signs off. Then, well into implementation, someone asks "what if the user cancels mid-flow?" and nobody knows. That's not a spec. That's a compliance artifact.

The failure mode is almost always the same: writing about the feature instead of the decisions. Most of a good spec is edge cases, failure modes, and explicit non-goals. If it reads like a feature brochure, it hasn't done its job.

The three questions any spec has to answer

Before you send a spec for review, it needs to answer these in under ten seconds of reading:

• What can the reviewer reject? If there's no concrete thing they can point at and say "no, not that," the scope is too mushy.
• What can the tester verify? If QA has to interview you to write test cases, the acceptance criteria aren't criteria.
• What can the operator stop? If on-call can't name the signal that means "abort," you don't have a rollout plan, you have hope.

Most first drafts fail at least one, and plenty fail all three. That's why you write it first — so the gaps show up on the page instead of in production.

Acceptance criteria that aren't decorative

Here are the acceptance criteria most teams write:

- User can submit form
- Form validates required fields
- Success message appears

Here's what that leaves out: what does "validates" mean — client-side, server-side, or both? What happens if the server rejects something the client accepted? What does the success message say, and for how long does it stay up? What happens if the user double-clicks submit?

Compare with criteria that actually prevent invention during implementation:

- Given a submission with a valid email and required fields
  When the user clicks submit
  Then duplicate requests within 2 seconds are debounced
  And a record appears with status="pending" in under 500ms
  And the UI transitions to the confirmation state

- Given the server returns 409 Conflict on duplicate email
  When the response arrives
  Then the form re-enables
  And the email field shows the conflict inline
  And no pending record is created client-side

The second version forces three decisions the first left for later: debouncing behavior, the 409 contract, and the error UX. That's the entire point.

What to ask before anyone starts coding

Review your own spec like you didn't write it. Try these:

• Which decisions here would still be ambiguous to someone who wasn't in the meeting?
• Can QA derive their test matrix without asking me anything?
• If this release fails at 2am, does the on-call engineer know what to do?

If you can't answer without starting a Slack thread, the spec is carrying unpriced risk. You'll pay for it later, usually the afternoon before a demo.

Rollout is part of the spec, not a footnote

A spec that ends at "shipped" isn't finished. Rollout is where many production incidents start, and it's where most specs go quiet.

• Staging plan. Not "we'll turn it on." Who flips the switch, in what order, and what signals confirm it's working at each stage?
• Stop-loss thresholds. Name the number. "Rollback if error rate exceeds baseline by 3× for 10 minutes" beats "rollback if things look bad."
• Rollback mechanics. Code revert, config flag, job pause, or migration reversal? Some of these take seconds; others take hours. Know which yours is before you ship.

Common mistakes

• Using "reasonable" or "sensible" to describe behavior. These words mean different things to different readers and get challenged during QA. Replace them with numbers or explicit rules.
• Punting security and permissions to "a later ticket." These decisions shape the data model. Defer them and you're either rewriting migrations or shipping with holes.
• Not writing down what you're not building. Non-goals prevent scope creep at implementation time. Skip them and every sidebar conversation feels like a blocker.

How much spec is enough?

Write the amount that prevents reinvention during implementation. That's the whole rule.

Building the fifteenth internal dashboard? Two pages is probably plenty. Building payment rails? You probably need ten. The length should match the risk, not the process.

One sanity check: count the decisions the spec makes. If the answer is "zero, it's describing the feature," rewrite it. If the answer is "forty," you've smuggled implementation into the spec — trim back.

The bottom line

Spec-first works because it moves arguments earlier, where they're cheap. You argue on the page instead of in review, on a whiteboard instead of in an incident postmortem. The document itself isn't the point. The process of writing it is what produces the thinking you actually need.

Teams that say spec-first doesn't work for them often haven't really tried it. They've tried writing long documents nobody read. That's a different failure mode. Start with the three questions, get comfortable being wrong on the page, and the rest follows.

In practice: what changes after the spec is rewritten

Take a billing workflow where the original ticket says only "support partial refunds." Built straight from that ticket, the first implementation would allow duplicate refunds, because retry behavior is left to the payment worker. Rewriting the request as a spec changes the actual design, not just the wording.

Before:
- User can refund an order.

After:
- Given a refund request with idempotency_key=abc
  When the payment provider times out
  Then the worker records status="pending_provider_confirmation"
  And retrying with the same key returns the same refund_id
  And support cannot create a second refund while the first is pending

The value is not the document. The value is forcing the team to decide retry behavior before the first production timeout.

Review drill

Use this piece during a team trying spec-first for the first time. Keep the discussion tied to one real change; otherwise the article turns into a nice idea that never touches the spec.

• First target: Choose one class of work, not the whole engineering process.
• Artifact: Decide where specs live and how they are linked from issues and pull requests.
• Review rule: Write when a spec can proceed to implementation and who signs off.
• Learning loop: Use incidents and rework to improve the template instead of adding more ceremony.

The first rollout should feel boring and narrow. That is a feature, not a failure.

Adopting spec-first in a team: a 30-day plan

Getting one person to write one good spec is easy. Getting a team to keep doing it is a social problem, not a technical one. The template takes an afternoon; most of the effort goes into showing that specs save time on this team's own work.

Before week one: start from an incident, not the process

Pick a recent incident or missed deadline and trace it back to the decision nobody made early enough. One sentence like "if we had written down the refund edge case at kickoff, QA would not have spent three days arguing about it" persuades more than any presentation about process. Spec-first does not sell as a philosophy. It sells as the fix for a problem the team already agrees it has.

Week by week

Write the pilot rule down so nobody has to guess what it covers:

Pilot rule
- Full spec: money movement, auth, data migration, external API contract
- Light one-page note: copy, small layout, internal-only refactor
- Required before code (full spec): owner, non-goals, failure paths, rollback trigger
- Review slot: one 25-minute review per week on a real ticket
- Success signal: fewer PR comments asking what the behavior should be
- Exit gate: keep the rule only if it changed a design decision or
  prevented rework at least twice during the pilot

A template short enough to get used

If the outline runs past one page, people won't start. Six sections cover most features in 2–4 pages:

## Goal
One sentence. User or system outcome.

## Non-goals
3-6 items people might expect that we are not doing.

## Acceptance criteria
Given/When/Then. At least one failure path per happy path.

## Edge cases
By category: input boundaries, state transitions, concurrency,
time-based behavior, errors.

## Rollout & rollback
How it ships, what rollback means physically, stop-loss thresholds in numbers.

## Open questions
Each one has an owner and a deadline to decide.

Skip "Background" and "Motivation" unless the feature genuinely needs them. Once the practice spreads, tier the templates by complexity instead of growing one: a short one for CRUD-shaped features, a fuller one for flows that touch money or identity, and a separate one for architecture changes. Let the author pick.

Where adoption usually fails

• Gating too early. If specs become a required review artifact before the team has seen them help, they get written as compliance theater: the shortest document that satisfies the process. Add the gate only after two or three specs have caught real problems.
• Mandating specs you don't write. Whoever introduces spec-first writes the first two or three, visibly, for their own work. A lead who requires specs but writes none has a credibility problem.
• One template for every feature. A 12-section template scares off simple work and turns into paperwork. Tier it, as above.
• No retro loop. After four to six weeks, take the last five incidents and ask whether a spec could reasonably have prevented each one. A clear pattern is the evidence for widening the policy. A weak pattern means scale back.

Measure clarifications, not spec count

"Percentage of features with a spec" measures paperwork. The useful number is how often implementation stops to ask the spec author a question. Supporting signals are QA bounce-backs, clarification comments in PRs, and incidents traced to a misunderstood requirement. If those drop, the specs are working. If they stay flat while the spec count rises, the specs are ceremonial.

Be explicit about where spec-first does not apply: small UI tweaks, documentation updates, dependency bumps. The goal is not universal coverage. It is that wherever ambiguity costs time, it gets surfaced on the page instead of during implementation. Teams that force specs onto everything tend to drop the practice once the overhead stops matching the value.

Delivery Review Packet to Copy

Use this when the article becomes part of planning, design review, or release readiness. It keeps ownership and stop conditions visible.

Delivery review packet: What Is Spec-First Development? (Complete Guide)

Decision to make:
- What Is Spec-First Development becomes clearer when the team makes the hidden decisions visible before coding starts.

Owner check:
- Product owner:
- Engineering owner:
- QA or operations reviewer:

Scope boundary:
- In scope:
- Out of scope:
- Assumption that still needs approval:

Acceptance evidence:
- Test or fixture:
- Log, metric, or screenshot:
- Manual review step:

Process boundary: owner, decision log, evidence, and stop-loss threshold must be named before implementation starts.

Reviewer prompt:
- What would still be ambiguous to someone who missed the planning meeting?
- What evidence would make this safe enough to ship?