PRD Template for AI Coding Agents

A PRD for an AI coding agent is a markdown file in your repository that says what to build, for whom, in what order, and how to tell when each piece is done. The agent reads it at the start of every session, because it remembers nothing from the last one. The template below has eight sections. Copy it into docs/prd.md, fill it in, and point your agent at it.

The template is the easy half. A PRD for an agent fails in a specific way, as it grows, and the second half of this page is about that.

The template

# PRD: <feature name>

## Outcome
One sentence about what changes for the user when this ships.
"New customers can pay without creating an account" beats "Checkout v2."

## Users
Who this is for, and the job they're trying to get done.

## Constraints
Rules every story must follow: stack, libraries to use or avoid,
security requirements, code conventions. Write them once, here.

## Release 1
The smallest set of stories that delivers the outcome. Build these first, in order.

### Story: <title>
As a <user>, I want <behavior>, so that <reason>.
Acceptance criteria:
- WHEN <condition> THE SYSTEM SHALL <behavior>
- WHEN <condition> THE SYSTEM SHALL <behavior>

## Later
Stories that are agreed but not in release 1. The agent does not build these.

## Out of scope
What this PRD deliberately doesn't cover, so the agent doesn't add it.

## Decisions
- <date>: <what was decided> because <why>.

## Open questions
- [NEEDS CLARIFICATION] <question the agent must ask about, not guess>

What each section is for

Outcome is the sentence the agent checks its work against. If a story doesn’t move it, the story is in the wrong release.

Constraints live at the top because they apply to every story. Repeating them per story costs tokens and invites contradictions. Spec Kit calls this layer a constitution.

Release 1 is the only section the agent should build from. Separating it from Later is the most useful thing a PRD can do for an agent, because an agent handed a list of everything builds everything.

Acceptance criteria are in EARS form, “WHEN … THE SYSTEM SHALL …”, the notation Kiro uses. Plain sentences work too, as long as a test could be written from them. “Works correctly” can’t be tested.

Decisions keeps the why. Without it, the next session reverses a choice it can’t see the reason for.

Open questions uses Spec Kit’s [NEEDS CLARIFICATION] marker, which tells the agent to stop and ask instead of filling the gap with something plausible.

Using it with Claude Code or Cursor

Save the file in the repository, not in the chat. A PRD written into a conversation is gone when the conversation ends, and the next session starts from whatever the agent can find in the code.

Then tell the agent where it is. In Claude Code, reference docs/prd.md from CLAUDE.md. In Cursor, reference it from a project rule. Ask for one story at a time from Release 1, and end each session by asking the agent to add what it learned to the file: a new decision, a question it hit, a story that turned out to be two.

That last step is the one that keeps the PRD true. It’s also the one that makes it grow.

Where a PRD for an agent breaks

Every session, the agent reads the whole file. The file gets longer with every decision and every split story, and the context window doesn’t. At some length the agent stops reading carefully. It skims, or loses the section that fell outside the window, and builds from what’s left. The spec-driven development guide has the numbers: Spec Kit producing 2,577 lines of markdown for a 689-line feature, and an agent building email login when the spec said username.

The usual fix is to split the PRD into one file per feature. That keeps each read small. It loses the one thing the single file had: which feature comes first, and which one depends on which.

The same PRD as a map

A PRD’s structure is mostly order and priority, written out as headings. A story map draws the same structure with position, so none of it has to be read as text:

Here’s the part that matters for the agent. Each card’s description and acceptance criteria are markdown, so the map is a spatial index over small documents. People read the map. The agent reads the cards. Over MCP it can ask for only the Release 1 slice, or a one-line summary of every card, and then fetch in full the card it’s about to build. The PRD is all still there, and none of it has to fit in one read.

CardBoard calls this spec mapping.

Move your PRD onto a map

If you already have a prd.md, you don’t need to retype it. Connect Claude to CardBoard over MCP and give it a prompt like this:

Read docs/prd.md. Create a user story map in CardBoard for it. Put the user’s steps across the top as activities, and each story under the step it belongs to, with its acceptance criteria. Put the Release 1 stories in a slice named after the outcome, and the Later stories below it. Add the constraints to the top card and the decisions as comments.

The cards arrive as proposals. You accept them, move the ones it placed badly, and from then on the agent builds from the map, one slice at a time, and proposes changes back onto the cards they’re about.

Frequently asked questions

What should a PRD for an AI coding agent include?

An outcome, the users, constraints that apply to every story, the stories for the first release with testable acceptance criteria, what comes later, what’s out of scope, decisions with their reasons, and open questions the agent should ask about instead of guessing.

Where should I keep the PRD?

In the repository, as a markdown file the agent reads every session, such as docs/prd.md, referenced from CLAUDE.md or a Cursor rule. A PRD kept in a chat disappears when the conversation ends.

How long should a PRD for an agent be?

Short enough that the agent reads all of it carefully every session. When it isn’t, don’t just trim it. Split it so the agent reads only the release it’s building, with a map or one file per feature.

What’s the difference between a PRD and a spec?

For coding agents, very little. Spec-driven tools like Spec Kit and Kiro produce the same contents a PRD has: goals, user stories, acceptance criteria, constraints, and decisions. The spec-driven development guide covers where the practice came from.

Can Claude turn a PRD into a story map?

Yes. Connected to CardBoard over MCP, Claude can read a PRD and propose a story map from it: activities, stories with acceptance criteria, and a first release slice. Each card arrives as a proposal you accept or dismiss.

Written by Josh Colter, who owns and builds CardBoard, the story mapping tool featured in Jeff Patton’s User Story Mapping.