Foundationsboth

Writing good product specs

The doc that aligns ten people before a single line of code.

The short version

A great spec answers why and what, never how. State the problem, the user, the one success metric, and what you are explicitly not doing, then get out of the way. If engineers read it and know exactly what to build but feel free in how to build it, it is working.

Why it matters

A spec is the cheapest place to be wrong. Changing a sentence costs nothing; changing shipped code costs a sprint. The spec is where you front-load the disagreements, about scope, about the user, about what "done" means, so they happen in a doc review instead of a launch retro.

The PMs who struggle write specs as feature descriptions. The PMs who compound write them as aligned decisions: by the time the doc is approved, the argument is already over.

The checklist

The problem, in one sentence. If you can't state it in one line, you don't understand it yet.

Who has it, and how badly. A named user and the concrete cost of the status quo.

The one success metric. Not five. The single number that, if it moves, makes this worth doing.

Non-goals. The most important section. What you are deliberately not solving, so scope can't creep.

Open questions. Naming what you don't know builds more trust than pretending you do.

Common mistakes

Specifying the how, designing the solution instead of framing the problem.

Five success metrics, which means none. Pick the one.

No non-goals, so scope creeps in every review.

Writing it alone, then "presenting" it. A spec is co-written in the hallway before it becomes a doc.

The template

Every spec I write, startup or enterprise, human-drafted or AI-assisted, uses the same three-part skeleton: Requirements (what & why), Design (how), and Tasks (the ordered path to done). The body below is placeholder text; what matters is the shape and the section order.

Notice the rhythm: prose to frame intent, bullets to enumerate, checkboxes for anything testable. If a line can be checked off, it is a checkbox, that is what makes a spec verifiable instead of aspirational.

product-spec.md

// 3-part skeleton, Requirements · Design · Tasks

# Feature: <one-line name>

Lorem ipsum dolor sit amet, one paragraph stating the problem and who has it. The reader should understand the why before any how.

## 1. Requirements (what & why)

Problem statement: consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore.

Acceptance criteria, testable, each a checkbox:

- [ ]Ut enim ad minim veniam, quis nostrud exercitation.

- [ ]Duis aute irure dolor in reprehenderit in voluptate.

- [ ]Excepteur sint occaecat cupidatat non proident.

Non-goals, what we are deliberately NOT doing:

-Sed ut perspiciatis unde omnis iste natus error.

-Nemo enim ipsam voluptatem quia voluptas sit.

Dependencies: at vero eos et accusamus et iusto odio.

## 2. Design (how)

Technical approach: neque porro quisquam est qui dolorem ipsum quia dolor sit amet.

Data model changes:

-Quis autem vel eum iure reprehenderit qui in ea.

-Voluptate velit esse quam nihil molestiae.

Edge cases & risks:

-Temporibus autem quibusdam et aut officiis debitis.

-Nam libero tempore, cum soluta nobis est eligendi.

## 3. Tasks + Definition of Done

Ordered breakdown, each task carries its own "done when":

- [ ]Itaque earum rerum hic tenetur, done when sapiente delectus.

- [ ]Ut aut reiciendis voluptatibus, done when maiores alias.

- [ ]Feature DoD: omnis voluptas assumenda est, omnis dolor.

➜

Writing specs with AI (the AI-DLC angle)

Here is the thing most people get wrong: the spec template does not change when AI enters the picture. The same three-part skeleton above is what you produce whether a human types every word or an agent drafts it. AI is the accelerant, not a different artifact, and the bottleneck it shifts is drafting speed, not the thinking.

What you must keep human is intent: the problem, the non-goals, and the one metric. Those are judgment calls an AI cannot make for you, because they encode what the business actually values. Hand the AI everything downstream of intent, expanding acceptance criteria, enumerating edge cases, drafting the task breakdown, and it compresses hours of typing into minutes. That is how a single PM scales their spec output across more surface area without lowering the bar.

This is the same point as the AI-DLC perspective: generation gets cheap, so validation becomes the binding constraint. A spec drafted by AI still needs a human to verify the non-goals are right and the one metric is the right one. The spec is where you do that validation, cheaply, on a page, before any code exists.

Steering files: set context once

The scaling unlock is steering files, a small set of always-loaded context documents (project goals, conventions, constraints, the spec format itself) that every new spec inherits automatically. Write them once at the onset of a project; from then on, every AI-assisted spec starts already knowing your standards instead of being told them each time.

In practice this means a new spec is not a blank page. The AI already knows the product, the audience, the non-negotiables, and the exact section structure, so it drafts a first version that is 80% right, and the PM spends their time on the 20% that is judgment.

A worked example with Claude Code

Concretely, here is how the loop runs with Claude Code today, using features that already exist, no custom tooling:

Seed steering context. Put a CLAUDE.md (or a steering file it loads) at the repo root with the product context, conventions, and this exact 3-part spec format. Every session inherits it.

State intent, not implementation. Describe the problem, the user, the non-goals, and the one metric in plain language. This is the part only you can do.

Let it draft the spec. Ask it to produce the spec in the standard format. It fills acceptance criteria, edge cases, and the task breakdown from the intent + steering context.

Validate, do not rubber-stamp. Read it as an editor: are the non-goals right? Is the metric the right one? Did it invent scope? This review is the real work, and the cheapest place to catch a wrong assumption.

Iterate in place. Correct intent and regenerate, rather than hand-editing line by line. The spec converges in a few passes and stays the single source of truth as implementation proceeds.

In a startup

One page, maybe a Slack thread. The spec's job is speed-of-alignment between three people. Skip the formality; keep the non-goals.

In an enterprise

The spec is also a political artifact, it's how you get sign-off from teams you don't control. The stakeholder list and the approval trail matter as much as the content.

Quick check

0/3

Optional, find the right answer for each to complete the concept. Keep trying; nothing is gated.

1. What should a great product spec primarily answer?

2. Which spec section is described as the most important?

3. How many success metrics should a spec commit to?

Continue the path

Next concept →

Scoping & cutting

Related perspective →

AI-DLC: the validation crisis