Spec-First vs Agile: Conflict or Complement?

"We're agile — we don't do big up-front design." I've heard this objection in some form every time I introduce spec-first to a team. And every time, it turns out the objection is solving a different problem than the one I'm describing.

Published on 2025-12-15 · ✓ Updated 2026-03-25 · 6 min read · Author: Daniel Marsh · Review policy: Editorial Policy

The objection (and why it's not entirely wrong)

The Agile Manifesto values working software over comprehensive documentation. That's a real principle, not a straw man. And I'll be honest — there are situations where spec-first genuinely doesn't fit well. Exploratory prototypes, research spikes, quick UI experiments where you need user feedback before you know what "done" means. If you're running a design sprint to figure out whether the feature should exist at all, writing acceptance criteria first is premature.

But most of the work that ships to production isn't exploratory. It's features with known requirements, defined user flows, and real consequences for getting the edge cases wrong. For that kind of work, writing a one-page spec with a goal, acceptance criteria, and explicit non-goals isn't waterfall. It's just thinking — with the output written down so everyone means the same thing.

What spec-first actually means in practice

It doesn't mean a 40-page requirements document before anyone opens their IDE. The minimum viable spec is: one-sentence goal, explicit non-goals, measurable acceptance criteria, list of known edge cases. That fits in a ticket body. Most medium-complexity features shouldn't take more than two hours to spec at this level.

The decisions you skip in the spec don't vanish. They show up during implementation as quiet engineering calls that never get reviewed, during QA as test coverage gaps, and during release as "wait, I thought we agreed on X" arguments. Spec-first just moves those decisions to the cheapest moment.

Acceptance criteria is already an agile practice

This is the part that usually lands for skeptical agile teams: acceptance criteria is not a spec-first invention. It comes directly from the user story format. "As a user, I want X so that Y. Acceptance: [conditions]." Every agile team writing user stories already has the framework. The problem is most teams write acceptance criteria that can't actually be tested.

Weak (agile theater):
  Story: As a user, I can export my data.
  Acceptance: Export works correctly.

Strong (actually testable):
  Story: As a user, I can export my contacts to CSV.
  Acceptance:
  - Given I have 0 contacts, export returns an empty CSV with header row
  - Given I have contacts, CSV includes: id, name, email, created_at
  - Given export has > 10,000 rows, job runs async, user receives download link by email
  - Given export fails, user sees error banner, no partial file is offered for download

The second version takes maybe 15 more minutes to write. QA can start building tests from it before the code is merged. That's the whole idea.

Right-sizing by risk

Not every feature needs the same depth of spec. Here's a rough calibration that works across different team velocities:

For low-risk work — UI copy, color updates, config toggles — a ticket description is enough. No formal spec needed. For medium-risk work — a new endpoint, a new form, a third-party integration — a one-page spec with goal, acceptance criteria, and known edge cases pays for itself. For high-risk work — data migrations, permission model changes, billing logic, anything irreversible — write a full spec with non-goals, dependencies, rollout plan, and rollback definition. Review required before implementation starts.

The question isn't "do we need a spec?" — it's "how much spec prevents expensive rework for this specific feature?"

Where it fits in a sprint

The most practical change is treating spec writing as part of sprint planning, not a separate upstream phase. Before a story enters the sprint, it needs acceptance criteria that QA could use to write test cases without asking further questions.

Stories that pass that check are sprint-ready. Stories that fail go back for a 10-minute clarification before consuming engineering time. The cost of this gate is one short conversation. The cost of skipping it is discovering the ambiguity mid-implementation, when changing direction is genuinely painful.

The "we'll figure it out" problem

Fast-moving teams often treat ambiguity as flexibility. Adapting to what you discover is healthy for product direction — finding out users want feature B more than feature A is exactly what agile enables. But it's not healthy for implementation decisions that get encoded in data structures, APIs, or state machines.

A team that "figures out" the permission model as they build will produce something that handles the cases they thought of. The cases they didn't think of either won't work, or will work by accident in brittle ways. A short spec surfaces those decisions while they're still cheap to change.

Specs tend to speed up iterations after sprint 1

When acceptance criteria are clear, QA writes tests in parallel with engineering. When non-goals are explicit, engineers stop gold-plating things nobody asked for. When edge cases are documented, the review cycle is one pass instead of three. These are not theoretical gains — they show up in actual sprint throughput.

The teams I've seen struggle with spec-first were almost always trying to write too much: 20-page documents for 2-day features. The answer isn't to skip specs; it's to right-size them. A spec should take a fraction of the time it prevents in rework. If it's taking longer than that, you're over-speccing.

A minimal spec template for agile teams

Feature: [Name]
Goal: [One sentence — what outcome does this deliver?]
Non-goals: [What are we explicitly not building in this sprint?]

Acceptance criteria:
- Given [precondition]
  When [user or system action]
  Then [observable result]
(repeat for each significant case)

Edge cases to handle:
- [specific input or scenario] → [expected behavior]

Dependencies: [external services, other teams, feature flags]
Rollout: [who gets it first, how we know it worked]

Every team can fill this out for a medium-complexity story in under 30 minutes during planning. Fewer implementation surprises, shorter review cycles, fewer post-release clarifications. The return is visible in the same sprint.

They answer different questions

Agile answers "which problem should we solve?" Spec-first answers "how will we know when we've solved it?" These aren't competing approaches — they're addressing different gaps. A team that does agile well but skips specs can pivot quickly and rediscover the same implementation decisions multiple times. A team that does both moves quickly and actually ships what was agreed on.

I used to think these were in tension. After running both practices together for three years, I now think they're closer to prerequisites for each other. Agile without specs is fast and imprecise. Specs without agile are thorough and slow. The combination is what most teams are actually looking for when they say they want to "move fast without breaking things."