How to write a PRD an AI coding agent can actually follow

Coding agents are very good at doing what you asked. They’re much less good at doing what you meant. Most frustration with them (it built the wrong thing, added features nobody wanted, rewrote a file it shouldn’t have touched) traces back to vague instructions.

A product requirements document, or PRD, fixes most of that. It doesn’t need to be long. A good one for a first version fits on two pages. It just needs to be specific in the places where agents tend to guess.

What an agent needs that a teammate doesn’t

When you hand a colleague a rough brief, they fill the gaps with context: what the company sells, who the customer is, what “simple” means around here. An agent has none of that unless you write it down. It fills gaps too, but with generic assumptions drawn from countless other apps.

So a PRD written for an agent should be explicit about:

• Who the user is, in a sentence or two, so the agent makes sensible choices about wording and layout.
• The one core flow, written as numbered steps a user takes.
• What’s out of scope, because agents love to add things.
• The data: the main things you store and the fields each one has.
• Acceptance criteria: how you’ll check that each part works.
• The stack, so the agent doesn’t pick its own.

A template you can copy

Save this as PRODUCT_PRD.md in the root of your project so the agent can read it whenever it needs to.

# Product: [Name]

## Problem
[Who] spends [how long / how often] doing [task] because [reason].
Today they use [current workaround].

## User
[Role] at [type of company]. Not technical. Uses the app on desktop
during the workday.

## Core flow (v1)
1. User signs up with email.
2. User creates a [thing] by filling in [fields].
3. User sees a list of their [things], newest first.
4. User opens one, edits it, and saves.

## Data
- [thing]: id, user_id, title, status (draft | sent), created_at

## Out of scope for v1
- Teams and shared workspaces
- Integrations with other tools
- Mobile app
- Admin dashboard

## Acceptance criteria
- A signed-out visitor cannot see any [things].
- User A cannot see or edit User B's [things].
- Saving with an empty title shows an error and saves nothing.

## Stack
Next.js, Supabase (database + auth), deployed on Vercel.

Writing the parts that matter most

The core flow is the heart of the document. Write it as steps a user takes, not features the app has. “User creates a proposal by entering client name, scope, and price” is buildable. “Proposal management” isn’t.

Out of scope is the section people skip and regret. If you don’t write “no teams in v1,” an agent asked to build sign-up may helpfully scaffold organizations, invites, and roles. Now you have three times the code to understand and test.

Acceptance criteria turn opinions into checks. Write them so a stranger could test them: a specific action and a specific result. They also give you something concrete to ask the agent later: “Check the code against the acceptance criteria and tell me which ones aren’t met yet.”

How to use the PRD with an agent

The PRD isn’t one giant prompt. If you paste it in and say “build this,” you’ll get a large pile of code that half works and is hard to review. Feed it in pieces instead:

1. Ask the agent to read PRODUCT_PRD.md and propose a build plan in small steps. Tell it not to write code yet.
2. Edit the plan. Remove anything out of scope and reorder so you get a working flow as early as possible.
3. Ask for step one only. Review it, run it, commit.
4. Repeat, and update the PRD whenever you learn something new.

Treat the PRD as a living document. When a user conversation changes your mind, change the file first and the code second. That way you and the agent are always working from the same plan.

Common mistakes

• Describing the product you want in a year instead of the one you can build this month.
• Listing features without the order a user encounters them.
• Leaving the data section empty, so the agent invents a structure you’ll fight later.
• Writing “should be fast and secure” instead of a criterion you can actually test.

BLDR Lite includes a free mini PRD exercise if you want to try this on your own idea before you build anything.