What is Spec-First Development?

The definition

Spec-first development is the practice of producing a complete written product specification — covering every user journey, every screen, and every system boundary — before any code is written, any architecture is designed, or any build is started.

The specification is not a requirements document. It is not a list of features. It is a complete map of every interaction a user has with the system, written in enough detail that a developer who has never spoken to the client could build the correct product from it.

The spec is reviewed and approved by the client before any engineering begins. If the spec is wrong, the project is corrected in writing — not in code.

“The most expensive bugs in software are not code bugs. They are understanding bugs — where the team built exactly what the spec said, and the spec was wrong. Spec-first development attacks the root cause, not the symptom.”

— Janaka Ediriweera, Co-founder, specshop.dev

Why it matters — and why most teams skip it

Most software projects fail in the spec, not the build. The code works. The database holds the data. The deployment is clean. The problem is that the team built the wrong thing — because the wrong thing was specified, or nothing was specified at all.

Teams skip the spec because it feels slow. Shipping code feels like progress. Writing documents does not. This intuition is wrong. Every hour of spec work saves approximately three hours of code rework — and that ratio grows exponentially on projects with more than two developers or more than one user type.

In the age of AI-agent software development, the stakes are higher. AI agents build fast. Extremely fast. A build that would take a human team two weeks takes AI agents two days. This means the cost of a bad spec has also accelerated — when you can build the wrong thing in two days instead of two weeks, the ability to know what the right thing is before you start matters more, not less.

How spec-first development works

Spec-first development has three stages. At specshop.dev, we run them in strict sequence and do not begin the next until the previous is approved.

Stage 1: Journey mapping (before the spec)

We do not start by writing the spec. We start by mapping user journeys. A user journey is a complete description of one thing a user needs to accomplish: who they are, what triggers the action, every step they take, every decision point, every screen they see, and what happens when it succeeds or fails.

Journey mapping precedes spec writing because most product problems are journey problems. Teams describe features before they understand workflows. When you start with journeys, you discover the problems that feature-first thinking misses entirely.

Stage 2: The spec (the output of journey mapping)

The spec writes itself from the journey maps. When every journey is clearly defined, the screens are implied. The data model is implied. The user roles and permissions are implied. The spec is the formalisation of what the journey maps revealed — not a separate creative act.

A complete spec contains: every user journey, every screen with its contents and states, every system boundary and integration point, every edge case and error state, and the acceptance criteria for every piece of functionality. It is written in plain language, not technical jargon, so the client can read and approve every line.

Stage 3: Human approval before build

The spec is reviewed and approved by the client before any code is written. This is non-negotiable. Not because clients are obstructionists — but because the spec is the last moment where changes are cheap. A change to a journey map costs 30 minutes. The same change to a deployed codebase costs days.

In our process at specshop.dev, the approval gate is explicit: the client signs off on the spec and the clickable prototype before we begin architecture. If they cannot sign off, we revise until they can — or we part ways with the spec and design assets in their hands.

Spec-first vs. traditional SDLC

Spec-first vs. vibe coding

Vibe coding is the practice of using AI tools to build software iteratively without a pre-defined spec — describing what you want in natural language, reviewing the output, and refining from there.

Vibe coding is fast for Day 1. It is a structural problem for Day 2 and beyond. When software is built without a spec, the original intent exists only in the AI conversation that produced it. The moment that conversation ends, context is lost. Nobody — human or AI — can maintain software that was never specified, because there is no source of truth for what the software is supposed to do.

Spec-first and vibe coding are not opposites on a speed spectrum. They are different bets on where the real cost of software lives. Vibe coding bets that speed at build time is worth the maintenance debt. Spec-first development bets that understanding the problem correctly is the fastest path to a system that survives contact with real users.

What a product spec actually contains

A complete product spec for a software build contains the following sections. This is the structure we use at specshop.dev on every Spec + Build engagement.

1. Project overview — the problem being solved, the users it is for, and the success criteria
2. User roles — every distinct type of user, their permissions, and their core goals
3. User journeys — one journey per core workflow. Each journey includes the trigger, every step, every decision point, every screen, and every error state
4. Screen specifications — every screen in the system, with its contents, states (empty, loading, error, populated), and the actions available on it
5. Data model — the entities the system manages, their attributes, and their relationships
6. Integration points — every third-party service, API, or system the product connects to
7. Edge cases and constraints — every scenario that falls outside the primary happy path
8. Acceptance criteria — the specific conditions under which each piece of functionality is considered complete

We share this framework — the Spec Starter Kit — for free. It includes the user journey mapping template, the spec writing framework, the 7 questions to answer before any build starts, and the “kill the project” checklist.

Get the Spec Starter Kit — free →

Frequently asked questions

Is spec-first development the same as waterfall?

No. Waterfall is a project management methodology that sequences all phases of development end-to-end before any delivery. Spec-first development is a product clarity practice that precedes build — the build itself can be iterative, agile, or AI-agent-driven. The spec defines what is being built; the build process is a separate decision.

How long does writing a spec take?

For a project with 2–3 core user workflows and up to 3 user types, we typically spend 5 working days on the Define stage: journey mapping, spec writing, UI/UX design, and clickable prototype. For more complex systems, the Define stage is longer. We do not compress it — the spec phase is where the real thinking happens.

Who writes the spec — us or you?

We write it. Your job is to explain the business problem, validate the journeys we design together, and approve the output. You bring domain expertise. We bring product engineering methodology. Most clients are not technical — and do not need to be.

Can we use the spec with a different developer?

Yes. The spec is yours. If you engage specshop.dev for The Spec ($5,000) and take it to another development team, that is completely fine. The spec is designed to be developer-agnostic — any competent team can build from it.

What is spec-driven development vs. spec-first development?

The terms are used interchangeably. “Spec-first” emphasises that the specification precedes code. “Spec-driven” emphasises that the specification drives the build. At specshop.dev we use both terms to describe the same methodology.