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
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.
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:
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.