How to Write a PRD an AI Can Build From (with a template)

Hand an AI coding tool a vague sentence and it hands you back vague software - confidently, and fast, which is the dangerous part. Hand it a good PRD and something different happens: it builds the thing you meant, the first time, and you spend your afternoon reading a diff instead of relitigating what you asked for. The whole gap between an AI that feels like a toy and one that feels like a teammate lives in that one document.

Most guides to writing a PRD are written for product managers handing a spec to a human engineering team, and they're fine at that. This one is written for the thing that's changed: increasingly the first reader of your PRD isn't a person, it's an agent that will go and build exactly what the document says - including the bits you didn't mean. That raises the stakes on clarity in a way a human team, who'll ask you a clarifying question over coffee, never did. Below is what a PRD is, a seven-part template you can lift wholesale, a worked example, and the two lines I've learned matter more than all the rest. It costs you fifteen minutes and saves you an afternoon; you need nothing but a text file.

What a PRD is

A PRD - product requirements document - is the written spec a build starts from: one page that says what you're building, why, and how you'll know it's done. The term is a hangover from classic software product management, where a product manager would hand engineering a stack of them; Marty Cagan's Silicon Valley Product Group has been the canonical reference on writing them for the better part of two decades, and the advice at the core has barely moved.

That core, which every good guide agrees on and which matters twice as much when an agent is reading: a PRD describes the why and the what, never the how. You are the one who decides what "done" looks like and why it's worth doing. You are emphatically not the one deciding which function goes in which file - that's the build's job, whether the builder is a junior engineer or Claude Code. The moment a PRD starts specifying implementation, it stops being a brief and starts being a bad first draft of the code.

Here's the shift that makes this worth relearning in 2026. When the reader was a human team, a fuzzy PRD degraded gracefully - someone would poke their head round the door and ask what you meant. When the reader is an agent, a fuzzy PRD degrades confidently: the model fills your ambiguity with its own reasonable-sounding guess, builds on top of that guess, and by the time you notice, the wrong assumption is three files deep. The PRD is where you close those gaps before they get expensive.

The template

Here's the shape I use for every build, whether I'm handing it to Claude Code or thinking it through myself. It's deliberately short - the test of a PRD isn't length, it's whether someone who wasn't in your head that morning could build the thing and know when they'd finished. Lift it wholesale:

# PRD: [what this is]

## The outcome
One sentence. What exists at the end that doesn't exist now.

## Why
The problem this solves. If I can't write this, I stop.

## Scope
IN:  [what this build includes]
OUT: [what it explicitly does not - this is the useful list]

## Definition of done
- [ ] A testable statement, not a feeling
- [ ] How I'll know it works: [the command, the URL, the check]

## Constraints
Environment, versions, anything already load-bearing that must not move.

## Open questions
What I don't know yet. Left visible, not guessed.

Six headings, and each one is doing a specific job for the agent that reads it:

1. The outcome is the target. One sentence, phrased as the state of the world after the build - "a CLI that converts our CSV exports to the new JSON schema", not "improve the export process". An agent optimises toward whatever you name here, so name the finish line, not the direction of travel.
2. Why is the guardrail. It sounds like a formality and it's the opposite: when the agent hits a decision the PRD didn't cover (it always does), the "why" is what it reasons from. A PRD with no "why" makes every unspecified choice a coin-flip.
3. Scope is the brake, and its IN/OUT split is where most of the value hides - enough that it gets its own section below. A quick, battle-tested way to sort the IN list is MoSCoW: Must, Should, Could, Won't. The "Won't" column is just your OUT list wearing a tie.
4. Definition of done is the acceptance test. Not "it should work well" - a command you can run, a URL that should load, a specific check that passes or fails. This is the single line that lets you, or the agent, verify the build rather than admire it.
5. Constraints are the tripwires: the Node version that can't move, the API that's already load-bearing, the thing that will quietly break if the agent modernises it. Write down what must not change, because an eager builder left unwarned will happily "improve" your production dependency.
6. Open questions is the most honest section and the one people delete first. Writing "I don't know yet" is how you stop a confident wrong answer getting baked in at build time. An agent will never volunteer that it's unsure; you have to hold that uncertainty yourself, on the page, where you can see it.

A worked example

Templates are abstract, so here's a real one, filled in - the kind of thing I'd paste into Claude Code before letting it touch a file. It's short on purpose:

# PRD: CSV-to-JSON export converter

## The outcome
A command-line script that turns our current CSV product exports into the
new v2 JSON schema, so the storefront can consume them without manual reformatting.

## Why
The storefront migration lands next month and expects v2 JSON. Reformatting
40 exports a week by hand is the bottleneck. This removes it.

## Scope
IN:  read a CSV, map columns to the v2 schema, write valid JSON, report bad rows.
OUT: no GUI. No live storefront upload. No CSV *writing* - we only read them.

## Definition of done
- [ ] `python convert.py sample.csv` writes sample.json that validates against v2-schema.json
- [ ] A malformed row is skipped and logged, not fatal
- [ ] Runs on the two real exports in /samples without hand-editing

## Constraints
Python 3.11 (matches the deploy image). No new dependencies beyond the standard
library if avoidable. The v2 schema at v2-schema.json is fixed - do not modify it.

## Open questions
Do we need to preserve the original row order in the output, or is it irrelevant
to the storefront? (Assume irrelevant unless told otherwise.)

Notice how little of it is about code. There isn't a function name in sight. What's there instead is every decision an agent would otherwise have to guess: what counts as done (a real command against a real file), what's off the table (no GUI, no upload), what mustn't move (the schema, the Python version), and the one thing I hadn't yet decided (row order), flagged rather than fudged. Hand that over and the build is almost boring. That's the goal.

The two lines that matter most

If you take nothing else from this, take these two sections, because they're the ones that separate a PRD that works from a wishlist that doesn't - and they're the two people cut first when they're in a hurry.

The first is the OUT list. Scope creep is the default failure of any build, and it's worse with an agent than with a person, because the agent is relentlessly agreeable - it will cheerfully keep going, adding the thing you didn't ask for, gold-plating a corner you didn't care about, right off a cliff you never mentioned. An explicit OUT list is the cheapest brake there is. "No GUI. No live upload." is two seconds to write and saves you a day of politely undoing helpful work.

The second is open questions. Every build has a decision you haven't made yet, and the instinct under time pressure is to paper over it and hope. Don't. Write it down as an open question, and - this is the trick - state your assumption alongside it ("assume irrelevant unless told otherwise"). Now the agent proceeds on a flagged assumption you can see and correct, instead of a silent one you'll discover three files later. Visible uncertainty is cheap; buried uncertainty is where the afternoon goes.

The mistakes that turn a PRD to mush

A few failure modes turn up again and again, mine included:

• Specifying the how. The commonest one. You start describing the database table, the loop, the file structure - and now you've written worse code than the agent would have, in prose. Stay on the what and the why; let the build own the how.
• A definition of done you can't run. "It should work reliably" is not a test, it's a hope. If the "done" line isn't a command, a URL, or a check that comes back pass or fail, you can't verify the result and neither can the agent.
• No OUT list. Covered above, and worth repeating: an unbounded scope is an open invitation to build the wrong, bigger thing.
• Guessing instead of flagging. Turning an open question into a silent assumption. The PRD is the one place uncertainty is free to admit; spend it there.
• Writing a novel. A PRD is a page, not a specification document. If it's sprawling, link out to the detail rather than embedding it - the reader, human or agent, needs the shape, not every leaf.

Where to go from here

Write one, by hand, for the next small thing you want built - and write the OUT list first, before the outcome, because knowing what you're not doing clarifies what you are. Keep it to a page. Make the "done" line a command you can run. Then hand it to your AI coding tool and watch how much less it guesses.

The PRD is step one of a longer loop - the plan, the environment, the build, the checks - and I've written up the whole workflow I run from PRD to deploy if you want to see where this fits. If you're newer to the tools, the ladder from chatting to shipping starts a rung below this one. And if you don't have Claude Code yet, you can start with a free week and give it a real job - one you've written a PRD for.