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.

Published on 2026-02-25 · Updated 2026-05-11 · 8 min read · Author: Spec Coding Editorial Team · Review policy: Editorial Policy

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

I've watched teams spend three weeks producing a 40-page spec that answered none of the actual questions. The document existed. It was reviewed. Everyone signed off. Then in week four of implementation, someone asked "what if the user cancels mid-flow?" and nobody knew. 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. A good spec is 60% 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. Mine usually 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 most production incidents come from, 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.

Mistakes I see repeatedly

• 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.

Most teams that claim spec-first doesn't work for them haven't 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.

Field note: what changed after the spec was rewritten

In one billing workflow I reviewed, the original ticket said only "support partial refunds." The first implementation would have allowed duplicate refunds because retry behavior was left to the payment worker. Rewriting the request as a spec changed 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 was not the document. The value was 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.

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?

Flagship Use Path

This is one of the primary Spec Coding references for Spec-first adoption. Use it with a real ticket, pull request, or release review instead of treating it as background reading.

• Start here when: a team needs a shared definition before changing its planning or PR workflow.
• Copy this: the delivery review packet and the refund idempotency example.
• Evidence to attach: one real ticket with goal, non-goal, acceptance evidence, and stop-loss owner.
• Pair it with: Spec-First Development Hub and Feature Spec Template.

Flagship review path:
- Open this page during planning or review.
- Copy the relevant artifact into the work item.
- Replace example values with your system, owner, and failure mode.
- Block implementation if the evidence line is still blank.

Second-pass reviewer note: keep the spec small enough to argue with

For this review I checked whether the article makes spec-first feel like a working habit, not a slogan. The strongest examples are the ones where a written decision changes implementation: refund idempotency, rollback ownership, and what QA can verify without asking the author.

Reviewer decision log:
- Kept: refund and form-submission examples because they force implementation choices.
- Added emphasis: small specs are better when they expose one expensive ambiguity.
- Watch later: avoid turning spec-first into a universal process for trivial copy or styling changes.
- Reader action: copy one acceptance criterion into a real ticket, then ask which engineer could reject it.

Editorial Review Note

Reviewed Apr 29, 2026. This update added a reusable artifact, checked the article against the related topic hub, and tightened the next-step links so the page works as a practical reference rather than a standalone essay.