How to Adopt Spec-First in a Team (30-Day Plan)

Most teams that try to adopt spec-first development fail not because the practice is wrong, but because they change too much at once. This guide covers a practical seven-step sequence: starting with one feature, using a template, making spec review part of the workflow, getting buy-in from PM and QA, and expanding from there.

Published on 2026-01-03 · ✓ Updated 2026-03-25 · 7 min read · Author: Daniel Marsh · Review policy: Editorial Policy

Why most adoption attempts fail

I've introduced spec-first development to three different teams. The first time, I did it wrong — I sent a Confluence page titled "New Spec-First Policy" with a 12-section template and told everyone to follow it starting next sprint. Two weeks later, one engineer had written a spec. It was twenty minutes before the PR was already open. Nobody reviewed it. The practice was dead before it started.

The second time I tried something different: I wrote one spec myself, shared it for review, and waited to see what happened. The QA lead flagged a missing edge case. The PM realized a non-goal wasn't actually agreed upon. That single spec review changed the conversation. After three features, the team asked me to formalize the process.

What follows is the sequence that worked. It's not the only way, but it avoids the mistakes I made the first time. If you're in a hurry, the short version is: start with one feature, not a policy.

Week 1: one feature, one spec

Pick the next medium-complexity feature on the roadmap. Before any coding begins, write a one-page spec yourself. Include: the goal in one sentence, three to five non-goals, and four to six acceptance criteria in Given/When/Then format. Share it with the engineer who will build it and the QA engineer who will test it.

Don't aim for a perfect spec. Aim for a spec that someone will actually read and push back on. The first time I did this, the QA lead's review comment was "what happens if the user has no email on file?" — a question nobody had raised in planning. That's the whole point.

# Spec: User Email Notification Preferences (v1)

Goal: Allow users to opt out of non-critical email notifications from their account settings.

Non-goals:
- Push notifications
- Per-notification-type granularity (all-or-nothing in this release)
- Admin override of user preferences

Acceptance Criteria:
- Given a logged-in user on /settings/notifications
  When they toggle "Marketing emails" to off and save
  Then no marketing emails are sent to their address for 7+ days

- Given a user with notifications disabled
  When a transactional email (password reset, receipt) is triggered
  Then the email is sent regardless of the notification setting

Week 2: extract a template

After the first spec, extract its structure into a reusable template. A minimal template covers six sections: goal, non-goals, acceptance criteria, edge cases, error paths, and rollback. Put it somewhere the team can find it in thirty seconds — /docs/templates/ in the repo works better than a wiki page nobody bookmarks.

One thing I learned the hard way: don't over-design the template. My first version had fifteen sections. Nobody filled in more than six. Cut it down to the minimum that prevents real mistakes, and let teams add sections as they need them.

Week 2–3: spec review before code

This is the hardest step, and the one most teams skip. Make spec review a prerequisite for starting implementation — not an optional artifact attached to the pull request afterward.

In practice, update the definition of "ready to start": a ticket is ready when the spec has been reviewed by engineering and QA and blocking questions are answered. One sentence in your workflow definition, but it changes when ambiguities surface — before implementation instead of during code review.

Fair warning: the first time you enforce this, someone will push back with "I already know what to build, the spec is a formality." Let them write the spec anyway. In my experience, the spec review still catches something — usually a non-goal that wasn't agreed on or an edge case QA would have found two days later. If it genuinely catches nothing, that's useful data too.

Getting PM and QA buy-in (separately)

Product managers and QA engineers benefit from spec-first in different ways. Getting their buy-in requires making those benefits concrete.

For a PM: the spec is the place where product decisions get made explicit before engineering begins. When an engineer asks "what should happen if the user is inactive?" the spec review is where that question gets answered, not mid-implementation in a Slack thread. PMs who have experienced the cost of mid-implementation scope clarifications are usually easy to convince.

For QA: testable acceptance criteria mean QA can write test cases from the spec before implementation is complete. The QA engineer is no longer waiting for a build to discover what needs to be tested. They are part of the review process that makes the spec testable. This shifts QA from reactive to proactive — which most QA engineers strongly prefer.

The "it slows us down" conversation

You will have this conversation. Probably more than once. And honestly, the objection isn't wrong — writing a spec takes one to three hours. That's real time you're not spending writing code.

The counter-argument that worked for my teams wasn't theoretical. I asked them to track, for just two sprints, how many hours went to mid-implementation scope clarifications, rework from code review comments about behavior (not style), and QA bugs that traced back to undocumented assumptions. On one team, the answer was roughly 15% of the sprint. A two-hour spec that prevents even half of that is a clear win.

That said, I've also seen teams where spec-first genuinely didn't help much — usually small teams of 2-3 engineers who pair frequently and have deep shared context. If your team is like that, maybe you don't need this. I'd still recommend trying it for three features and measuring, rather than assuming.

Week 4: retrospect after three features

After three features using the spec-first process, run a short retrospective specifically about the practice. Ask the team: did the spec review catch anything that would otherwise have surfaced later? Were the acceptance criteria useful for QA? Did the non-goals prevent any scope additions? What would make the template better?

This retrospective serves two purposes. It surfaces real improvements to the process. And it gives the team a chance to see, in concrete terms, what value the practice produced. Three features is enough to have examples. It is also short enough that the practice has not become entrenched in a way that makes honest evaluation uncomfortable.

Beyond week 4: making it stick

Expand to all medium-and-above complexity features. Keep it optional for small changes — bug fixes, minor UI tweaks, config updates. The discipline should be proportional to the risk.

You'll know it's working when skipping the spec starts feeling like a risk rather than a shortcut. On my last team, an engineer once opened a PR without a spec and another engineer commented "where's the spec?" before looking at the code. That was the moment I knew the practice had stuck — not because I was enforcing it, but because the team had internalized why it mattered.

One last thing: this process isn't rigid. Some teams do it in three weeks, some take six. One team I consulted with skipped Step 4 entirely because their PM was already writing informal specs and just needed a better template. Adapt the sequence to your situation. The only step that's truly non-negotiable is the first one — start with one real feature, not a policy document.