How to write a product requirements document (PRD).

What does a full PRD look like?

The short example above fits one job. A PRD for a bigger piece of work covers several jobs, so it carries more of the eight sections. Here's a made-up example, condensed, to show the level of detail in each.

Team seats for a booking app (example)

1. Overview. Let a business add up to 10 staff to one account, each with their own login and calendar. Target: before the spring busy season.

2. Problem and goals. Small studios share one login today. Staff see each other's private notes, and when someone leaves, the owner changes the password for everyone. "I have 4 instructors on one password and it's a mess every time someone quits." (Owner, a yoga studio, support email, 3 Oct). Goal: studios with staff stop sharing logins. Business goal: keep the accounts most likely to outgrow us.

3. Target users. The owner, who pays and sets things up. Staff, who only need their own calendar and clients. Not in this round: front-desk staff who book for everyone.

4. Success metrics. Within 60 days of launch, half of accounts with shared logins have added at least 1 seat. Support emails about passwords drop. Both are read from data we already collect.

5. User stories. As an owner, I can invite a staff member by email, so they get their own login. As a staff member, I see only my own calendar and clients, so private notes stay private. As an owner, I can remove a staff member, so their access ends the same day.

6. Functional requirements.

• P0: invite by email, a separate login per person, staff see only their own calendar.
• P1: the owner can remove a seat, the owner sees every calendar in one view, staff can update their own profile, the owner gets an email when an invite is accepted.
• P2: staff can swap bookings with each other.

7. Design and interaction. A "Team" page in settings, using the existing list and invite patterns. The calendar gains a staff filter for owners only.

8. Out of scope and open questions. Not this round: roles beyond owner and staff, per-seat billing changes, front-desk access. Open: does a removed staff member's client history stay with the business? (Owner decides by 20 Oct. If an agent reaches this, stop and ask.)

Then each requirement becomes a job, and each job gets a short spec with its own Done When lines. The P0 "staff see only their own calendar" becomes a spec ending in lines such as: given a staff member signed in, when they open the calendar, then they see only their own bookings. That's where the PRD hands over to the build.

Notice what the example leaves out: market sizing, a competitor grid, a 6-month timeline. They may matter to the business. They don't change what gets built or how it's checked, so they live elsewhere, with a link.

Problem · the customer's own words

“I have 4 instructors on one password and it's a mess every time someone quits”

ExampleOwner, a yoga studio

How do you fill in each section of a PRD?

The template above lists the eight sections. Here's what to write in each, the weak version people often write and the version that does the work.

If everything is P0, nothing is.

1. Overview

Name it by what becomes true, not by the project code. One line on what it is, one on when.

• Weak: "Seats v2."
• Strong: "Let a business add staff to one account, each with their own login."

2. Problem and goals

The problem in the customer's own words, who has it and why now. Then the goal it serves. A quote keeps you honest. If you don't have one, say so: that's useful to know before you build. See problem statement.

• Weak: "Users want team features."
• Strong: "Studios share one login, so staff see each other's private notes. 4 owners asked this month."

3. Target users

Who it's for, and who it's not for this round. Two or three roles beat long personas. What matters is what each role needs to do, which is where jobs to be done helps.

• Weak: "All users."
• Strong: "Owners who pay, and staff who only need their own calendar. Not front-desk staff yet."

4. Success metrics

How you'll know it worked after it ships, with a number and a timeframe. Pick metrics you can read from data you already have. A metric you can't measure is a hope.

• Weak: "Improve team adoption."
• Strong: "Half of accounts with shared logins add a seat within 60 days."

5. User stories

One story per thing someone can now do, each with the benefit. Keep them small enough that each could ship on its own. See user story.

• Weak: "As a user, I want teams."
• Strong: "As an owner, I can remove a staff member, so their access ends the same day."

6. Functional requirements

Each requirement is one testable behavior, tiered P0, P1 or P2. P0 is what must ship for this to count at all. If everything is P0, nothing is.

• Weak: "Seats should be secure."
• Strong: "P0: a staff member cannot open another staff member's client notes, by link or by search."

7. Design and interaction

Which screens change and which existing patterns to reuse. For a coding agent, words beat a mockup: "use the existing invite pattern from the sharing page" tells it where to look.

• Weak: "Clean, modern team page."
• Strong: "A Team page in settings using the existing list and invite patterns."

8. Out of scope and open questions

The near neighbors you won't build, and the decisions still open, each with who answers and by when. This section stops the document from growing every time someone reads it.

• Weak: "TBD."
• Strong: "Not this round: roles beyond owner and staff. Open: who keeps a removed person's client history? (Owner, by 20 Oct.)"

What's the difference between a PRD, a spec, a user story and acceptance criteria?

They nest. A PRD holds several user stories. Each story has acceptance criteria. When the work is handed to a builder, person or agent, each job gets a spec, and the spec ends with checkable lines.

	PRD	Spec	User story	Acceptance criteria
Answers	What are we building, for whom and why?	What does this job change, and how do we know it's done?	What can this person now do, and why?	What must be true for this item to count as done?
Size	A feature or a release	One job	One capability	A few lines per story
Reader	The team and anyone deciding	The builder: a person or an agent	The team	The builder and whoever checks
Includes	Problem, goals, users, metrics, stories, requirements, scope	Problem, evidence, what to build, files to touch, Done When	Role, action, benefit	Conditions, often as given, when, then
Lives	As long as the feature is being built	Until the job ships	Until it's built	With the story or the spec
Example	Team seats for a booking app	Staff see only their own calendar	As an owner, I can remove a staff member	Given a removed staff member, when they sign in, then access is refused

User stories have a history worth knowing. Kent Beck introduced them in 1997, on a project at Chrysler. The "As a role, I can do something, so that I get a benefit" format came from a team at Connextra in London in 2001. Ron Jeffries described a story as 3 things: the card, the conversation and the confirmation. The confirmation part is the acceptance criteria, and it's the part that matters most when an agent is the builder, because an agent can't have the conversation in the hallway.

Acceptance criteria written so an agent can check them are what Annsa calls Done When lines. For a lighter document than a PRD, for work that's already decided, use the feature description template.

How do PRDs change when agents build?

When Claude Code, Cursor, Codex or Grok build from your requirements, the PRD gains a reader that takes every word literally and fills every gap with a guess. That changes what's worth writing.

Fig 4.1 · A literal reader

The PRD becomes the why, and specs become the what-now. A PRD that tries to be the build instructions for 10 jobs gets long, and an agent reading it for one job reads the other 9 too. Keep the PRD as the shared why: the problem, the users, the goals and the scope. Then split it into one spec per job, each short enough to read cold. See the spec.

Out of scope does more work. A person who's unsure asks. An agent often keeps going. Every near neighbor you name in "not this round" is a build an agent won't wander into.

Decisions need their reasons. "Max 10 seats, because no current account has more than 8 staff." Without the reason, an agent may reopen the decision, or quietly pick a different number when it meets an edge case.

Open questions need a stop sign. Mark each one: "if you reach this, stop and ask." An agent that knows what's unsettled will ask. One that doesn't will invent an answer and build on it.

Requirements must be checkable. "Secure" and "fast" can't be checked. A requirement an agent can test is one it can prove it met. That's the biggest single difference between a PRD written for people and one written for agents. See definition of done for AI agents.

Prototypes got cheap. In 2006 Marty Cagan argued that the only spec that does the job is a high-fidelity prototype, because it can be tested with users before engineering starts. Agents make that cheaper again: a rough one can take an afternoon. So it can make sense to build a throwaway version, show it to 3 customers and write the PRD from what you learned, not before it.

The rules move out. Coding standards, test commands and style belong in the repo's rules file, AGENTS.md, which several agents read. The PRD says "rules: AGENTS.md" and stays about the product.

For the agent-ready version of the template, with "do not touch" and "already decided" sections, see how to write a PRD for Claude Code.

How do you review a PRD?

Read it once as the customer, once as the person building it and once as an agent with no other context. Then run through this list.

PRD review · Team seats the example above

Checked

• The title says what becomes true.
• Every requirement is testable, tiered P0, P1 or P2.

Open

• Who keeps a removed person's client history? Owner, by 20 Oct.

• The title says what becomes true, in words a customer would use.
• The problem has the customer's own words and who said them, or says there's no quote yet.
• The evidence shows how many accounts asked, and which ones.
• The goal names a metric you can read from data you already have, with a timeframe.
• Every requirement is one testable behavior, tiered P0, P1 or P2, with fewer P0s than P1s.
• Each user story names a role, an action and a benefit, and could ship on its own.
• Out of scope names near neighbors, not far-off ideas.
• Each decision has its reason in a few words.
• Each open question has an owner and a date, and tells a builder to stop and ask.
• No adjectives stand in for requirements. Fast, simple and intuitive get replaced with something you can check.
• The rules file is linked, not copied.
• It's short enough that a new person, or a new agent session, can read it in 10 minutes.

If 2 reviewers read the same requirement differently, rewrite it. That disagreement is the most useful thing a review finds.

Who signs it off, and when is it frozen?

In a big company, a PRD collects sign-offs from engineering, design and the business before work starts. On a small team, the person who owns the product decision reads it, and the people building it say whether it's clear. Nobody freezes it. It's living: when a decision changes, the PRD changes, with a line on what changed and why.

You may also meet the MRD, a market requirements document. It describes the market and the customer need, and the PRD says what the product does about it. Most small teams fold the useful part, the customer's problem, into the PRD.

AI PRD generators write a plausible document in a minute. They can't know your customers or your code, so the problem, the evidence and the scope still have to come from you.

What are the most common PRD mistakes?

• Starting from the feature. "Build team seats" skips the problem. Start from what hurts, and the feature may turn out smaller.
• No evidence. A PRD without the customer's words is an opinion with headings. Keep the quote and the account next to the requirement.
• Everything is P0. Then the order doesn't survive the first deadline. Cap the P0s.
• Writing the how. Database tables and component names in a PRD lock in choices before anyone has looked at the code. Leave the how to the spec and the builder.
• An empty out-of-scope section. It's the section that stops scope creep. Leaving it blank invites it.
• Open questions with no owner. They stay open until someone builds an answer by accident.
• Untestable metrics. "Improve engagement" can't fail. Name the number and when you'll read it.
• Writing it once and never again. A PRD is living. When a decision changes, update it, and say what changed and why.
• One giant document for agents. Split it into a spec per job. An agent reading a 20-page PRD for a one-day job reads the wrong 19 pages.
• Hiding guesses. A guess written as a fact gets built. Mark it as an open question instead.

Where do you go from here?

For the one-line definition, see PRD. To write your own, start from the PRD template, which has the problem, evidence, scope, Done When lines and open questions ready to fill in. For work that's already decided, the feature description template is a single page. And if a coding agent will build it, read how to write a PRD for Claude Code for the parts an agent needs that a person doesn't.

Sources

• Product requirements document, Wikipedia.
• User story, Wikipedia (Kent Beck, 1997; Connextra, 2001; Ron Jeffries' three Cs).
• Marty Cagan, Revisiting the product spec, SVPG, 12 October 2006.