Spec-First vs Agile: Conflict or Complement?

I get this question almost every time I introduce spec-first to a team: "Isn't this just waterfall in a hoodie?" The short answer is no — spec-first and agile aren't the same layer of the system. Agile is how you decide what to build next. Spec-first is how you decide what "done" means. Confusing the two is what makes both fail.

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

The layer confusion

Agile is a scheduling and feedback system. It says: ship in small increments, get user feedback, adjust the plan. It's about which feature to work on next and when.

Spec-first is about how you handle any single piece of work once you've decided to do it. It says: before you start coding, write down what the system needs to do and how you'll know it worked.

These are orthogonal. You can be fully agile and still write specs. You can avoid specs and still be waterfall. The two operate at different levels.

What people actually mean when they say "agile"

"Agile" in most companies doesn't mean the 2001 manifesto. It means: two-week sprints, standups, tickets in Jira, pull requests sized to fit a sprint, and an aversion to long documents. The aversion to documents is where the conflict with spec-first appears.

But the aversion is usually to the wrong documents: 40-page BRDs, 6-month roadmaps written in prose, architecture diagrams that go stale the day they're approved. Those aren't specs. A good spec for a single feature is 2-4 pages, written in a few hours, and either accurate or deleted. It's closer to a pull-request description than a BRD.

Where the actual conflict shows up

The conflict isn't ideological. It's practical. In agile-flavored teams, three things make spec-first feel heavy:

• Sprint pressure. "We planned 10 points this sprint — spending 3 hours on a spec doesn't fit." Fair. But the spec is part of the work, not overhead added to it. Estimate the spec as part of the ticket.
• The "we'll figure it out" culture. Agile teams often pride themselves on adapting. Specs feel like premature commitment. The reframe: specs aren't commitments to ship, they're commitments to having thought about the edge case before implementation found it.
• Review bottlenecks. Every additional review step feels like friction. Spec review happens before code review, asynchronously, in the same doc. It doesn't add a review — it moves one earlier, where it's cheap.

How spec-first fits inside agile rituals

I've run this setup in teams doing standard agile delivery:

• Backlog grooming: tickets above a certain complexity threshold get "spec required" flag.
• Sprint planning: specs for the upcoming sprint are written and reviewed asynchronously before planning meeting. The planning meeting is about capacity, not about understanding the work.
• Sprint execution: spec-required tickets start with spec writing (1-3 hours), then spec review (1 day async), then implementation. Total from ticket pickup to done is usually the same or faster than without, because mid-implementation clarifications drop.
• Retro: look at incidents, rework, and mid-implementation questions from the last sprint. Did any trace back to missing spec content? Use that to refine the "spec required" threshold.

Nothing in this is incompatible with two-week sprints. It's just insertion of one additional artifact for complex work.

What each does well

Agile's actual strengths — responding to user feedback, not over-committing to a roadmap, shipping incrementally — are still there. Spec-first doesn't touch those. It operates inside a single ticket, not across the roadmap.

Spec-first's actual strengths — surfacing edge cases early, aligning reviewer expectations, making acceptance criteria testable — don't require you to abandon agile. They require one extra artifact per complex ticket.

The cases where they genuinely conflict

There are two. Worth being honest about.

Spikes and prototypes

If the ticket is "explore whether we can do X," writing a spec in advance doesn't make sense. You don't know what X is yet. Spikes should skip the spec and produce one as their output — a spec that informs the real ticket.

True agile experimentation

If you're running a week-long A/B test and planning to throw out whichever variant loses, you don't need a spec for each variant. You need acceptance criteria for the experiment itself. The variants are throwaway; the test is the thing.

The "but waterfall" objection

The objection: "If you write specs first, you're back to waterfall." No. Waterfall is when you write all the specs for all the features up front, then design, then build, then test — one phase completes before the next starts.

Spec-first is feature-by-feature. You spec the thing you're about to build. The next feature doesn't have a spec yet because you don't know what it is yet. That's still agile — you're just treating each ticket as a short waterfall instead of a free-for-all.

Short waterfalls inside agile iterations are how every mature agile team I've seen actually operates. Spec-first just makes the "short waterfall" part explicit.

The honest answer

Spec-first works best inside an agile process, not outside it. Agile gives you the feedback loop and the schedule; spec-first gives you the internal discipline for each unit of work. Teams that adopt only one of them have two failure modes: all-agile teams ship fast but with constant rework, and all-spec teams ship slow because they over-specify things that don't need it.

The sweet spot is agile at the roadmap layer, spec-first at the feature layer. If your team already does agile well and wants to reduce rework, add spec-first to complex work and watch what happens over 4-6 weeks. If it doesn't help, drop it. That's also agile.

Review drill

Use this piece to tune the team workflow, not to debate labels. Spec-First works inside agile when the team knows which changes need a written decision before sprint work starts.

• Threshold: define the size, risk, contract change, migration, or cross-team dependency that requires a spec.
• Timing: put spec review before implementation starts, while still allowing small low-risk tickets to move quickly.
• Feedback: measure whether clarification comments, reopened tickets, and late scope changes fall after adoption.

Update the team working agreement with the threshold and review timing. Otherwise the process depends on memory and personality.

Example: a color-copy change can skip the spec; a billing-state change cannot. Write that threshold into the team agreement so planning does not become a case-by-case argument every week.

Worked Review Example

A team can keep two lanes. Small UI or copy tickets move through the normal agile flow with lightweight acceptance criteria. Contract changes, billing behavior, migrations, permission changes, and cross-team dependencies require a spec before sprint work starts. That rule keeps low-risk work fast while forcing risky work to settle decisions early enough for reviewers to challenge them.

If the team is worried about process drag, start with one repeat-problem category for four weeks: permission changes, billing changes, or service contracts. Do not require full specs for every ticket on day one. A narrow trial shows whether Spec-First reduces rework or merely adds ceremony.

Four-Week Trial Metric

A useful trial does not measure how many specs were written. Measure how many implementation comments asked for missing scope, how many QA cases were blocked by unclear acceptance criteria, and how many tickets reopened after merge. If permission-change tickets produced 14 clarification comments in the previous sprint and 4 after the spec gate, the process is earning its keep. If the numbers stay flat, the spec template is probably asking the wrong questions.

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: Spec-First vs Agile: Conflict or Complement?

Decision to make:
- Fit Spec-First into agile delivery by defining which tickets need a spec, where review belongs, and how sprint rework gets reduced.

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?

Editorial Review Note

Reviewed Apr 28, 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.