What Is Spec-First Development? (Complete Guide)

Most development teams don't struggle with effort. They struggle with everyone meaning something slightly different by "done." Spec-first development is a discipline for fixing that — you write down what success looks like before anyone touches code, not after.

Published on 2025-11-20 · ✓ Updated 2026-03-20 · 7 min read · Author: Daniel Marsh · Review policy: Editorial Policy

The core idea

Spec-first development means you write a technical specification — covering what the system should do, what it explicitly should not do, and how you'll know it's working — before implementation begins. Not a design doc. Not a Jira ticket. An actual written contract that engineering, product, and QA can all read, question, and sign off on before a single line of production code exists.

The logic is simple: a wrong decision caught in a document costs you an hour. The same wrong decision caught in code review costs you a day. Caught in QA, it costs a week. Caught in production, considerably more.

What I kept seeing without it

In 2019, I moved into a tech lead role on a CRM platform with about twelve engineers. We had planning meetings. We had Jira tickets with acceptance criteria fields. We had standups. And we still spent roughly 30% of each sprint on rework — not because people were careless, but because the ticket said "add contact deduplication" and left everyone to independently fill in what that meant for edge cases, error handling, and rollback.

Here's how it actually plays out when there's no spec. A developer gets a ticket, reads it, fills the gaps with reasonable assumptions, and starts building. Edge cases get discovered in code review or QA. Non-goals never get stated, so scope grows organically. The spec — if there is one — gets written afterward as documentation for what was built, not what was intended.

This isn't a failure of individual engineers. It's structural. When there's no spec, every ambiguity gets resolved privately, by whoever is holding the keyboard at that moment. Those decisions accumulate silently, and the system ends up doing something surprising in production that nobody can trace back to a conscious choice.

I won't pretend writing specs fixes everything. It doesn't prevent bad technical decisions or make stakeholders agree on priorities. But the teams I've seen drowning in rework are almost never the teams that spent too long writing specs. They're the teams whose planning conversations stayed verbal.

Where ambiguity costs you

What goes in a spec

A useful spec isn't long. It's complete. It answers a specific set of questions that nobody else can answer later without guessing:

• Goal: What user problem or business outcome does this solve? One sentence, not a paragraph.
• Non-goals: What is explicitly out of scope? This section prevents more arguments than anything else in the document.
• Acceptance criteria: What observable behavior proves the feature works correctly? Each criterion should be testable by QA without interviewing the author.
• Edge cases: What inputs or system states require special handling? Empty collections, null values, concurrent writes, permission boundaries.
• Error paths: What does the system do when things fail? Which failures are recoverable? Which ones surface to the user?
• Rollback: How does the team reverse this change if something goes wrong in production?

None of this asks how the system should be implemented. A spec describes behavior. Architecture and technical choices belong to the engineering team. The spec just pins down what the output needs to be.

A real example: password reset

Abstract descriptions of specs are easy to explain. Here's what one actually looks like — the acceptance criteria for a password reset feature, written before implementation starts:

Feature: Password Reset via Email

Goal: Allow users who have forgotten their password to regain account access
Non-goals: Social login recovery, admin-initiated resets, SMS-based verification

Acceptance Criteria:
- Given a registered email address
  When the user submits the reset form
  Then a reset link is sent within 30 seconds and expires after 1 hour

- Given an email address not in the system
  When the user submits the reset form
  Then the same success message is displayed (no account enumeration)

- Given a valid reset link
  When the user sets a new password under 8 characters
  Then the form rejects the input with a specific validation message

- Given a reset link that was already used
  When the user clicks it again
  Then a clear "link expired" message is shown with a link to request a new one

Rollback: Feature flag `password_reset_v2` — flip to false to revert to legacy flow

A QA engineer can derive test cases directly from this. An engineer knows exactly what to implement. A product manager can confirm it matches intent. None of that is possible from a ticket that says "add password reset." The spec also makes one decision explicit that often gets missed: showing the same success message for unknown emails, to prevent account enumeration. That's a security decision. It should be deliberate.

The time investment objection

The most common pushback to spec-first is that it slows teams down. It's worth addressing directly, because it's based on a real observation: writing a spec takes time. A medium-complexity feature might take two to three hours to spec well. That's time you're not spending writing code.

But look at where the actual time goes in most delivery cycles. It's not greenfield development. It's revisiting decisions that were never made explicit, debugging behaviors caused by undocumented assumptions, navigating scope disputes in the middle of implementation, and handling QA findings that should have been caught earlier. That work is expensive, and it compounds. A two-hour spec investment typically prevents a two-day rework cycle — often more.

The real calculation isn't "spec time vs. no spec time." It's "when do you want to pay the cost of ambiguity?" Spec-first moves that cost to the cheapest possible moment. Code-first moves it to the most expensive.

Why written specs beat meetings

There's a version of "we discussed this in the planning meeting" that teams rely on way too much. Meetings produce shared understanding in the room at that moment, for the people who attended. A spec produces a written record that any team member can reference — including people who were in a different time zone, joined after the decision was made, or simply forgot the specifics three weeks later.

When product, engineering, and QA all review the same spec before implementation begins, each role brings their own perspective at the same time. Product catches missing requirements. Engineering flags technical constraints that change the approach. QA identifies criteria that can't be tested as written. This async review catches more problems than any synchronous meeting — and leaves a record of what was decided and why, which is often the more valuable artifact.

What spec-first isn't

Spec-first isn't waterfall. It doesn't require six months of planning before any code gets written. It doesn't mean every feature needs a twenty-page document. A simple configuration change might need half a page. A complex cross-service feature might need five. The length scales with the complexity and the stakes.

It's also not a compliance exercise. A spec that sits in a folder nobody reads is not doing anything useful. The value is in the conversation the review creates — the async collaboration before implementation that prevents the expensive in-code discoveries that come after. If you're writing specs that nobody reads before work begins, something in the process is broken before the document is.

How to start this week

Pick the next feature on your roadmap. Before anyone touches code, write one page: the goal, two or three explicit non-goals, and four to six acceptance criteria in Given/When/Then format. Share it for async review and pay attention to what reviewers catch.

When I first tried this with my team, the pushback was immediate — "this is going to slow us down." We did it anyway for one feature. The PM caught a missing permission boundary in review. The QA lead flagged an edge case that would have been a production bug. That single spec review probably saved us three days of rework. After that, nobody argued about whether it was worth the time.

Your experience might be different. Maybe your first spec review is uneventful. That's fine too — it means the team was already aligned, and now you have proof. Either way, try it once and see what the review surfaces. The value tends to be obvious enough to make itself permanent.