How to write a PRD for AI coding tools that actually ship the right code

A PRD written for a human reader and a PRD written for an AI coding agent look different. The human version assumes context, infers missing pieces, and tolerates ambiguity. The AI version has to spell out the file tree, the schema, the API contract, the success criteria with numbers, and the out-of-scope list. Get the shape right and Lovable, Cursor, Bolt, v0, Claude Code, Codex, Replit, or Windsurf will ship something close to what you meant on the first try. Get it wrong and you burn an afternoon of clarifying-question round-trips.

The minimum shape that works across every tool

A PRD that runs cleanly through any 2026 AI builder has eight sections. None of them can be skipped. The order matters.

1. TL;DR. Two to four sentences. What is being built, for whom, by when, and what counts as success. This is the section the agent reads first and references when it has to make a choice.
2. Goals. Business goals and user goals, separately. Each goal must include a number. "Increase retention" is not a goal; "reduce 30-day churn from 12% to 8%" is.
3. Personas. Two to three primary users. Each with a name, a context (role, company size), and the friction they're feeling today.
4. Functional requirements with priority. P0 (must ship), P1 (should ship), P2 (nice to have). Number them. Reference them in test scenarios.
5. UX flow. A list of screens or states. For each, what data is shown, what actions exist, what happens on success and failure.
6. Success metrics. User-centric (engagement, conversion), business (revenue, retention), technical (latency, error rate). Each with a target number.
7. Technical considerations. Stack hints, integrations, constraints. This is where you tell the AI tool what defaults to assume.
8. Out of scope. Explicit non-goals. The agent will otherwise build the thing you didn't ask for, eat tokens, and surprise you.

Tool-specific sections that change everything

The eight sections above are the universal shell. Each AI tool wants a different appendix.

Writing the wrong appendix doesn't break the build, but it wastes one full agent run as the tool re-asks for the right shape. Plan for the tool you're using before drafting.

Length: long enough to be specific, short enough to be read

The sweet spot is 800 to 2000 words. Under 800 and you're leaving too much to the agent's imagination. Over 2000 and you're burning context window on prose the agent will skim. The eight-section structure above usually lands in this range without padding.

A common failure is over-writing the personas section. A persona doesn't need a backstory; it needs a name, a role, and one friction point. Three sentences each, three personas, 9 sentences total. Stop there.

Avoid these anti-patterns

These wreck the agent run more often than not.

1. Vague success criteria. "Users find it intuitive" is unmeasurable. "80% of new users complete onboarding within 5 minutes" is.
2. Implementation details disguised as requirements. "Use a Postgres database with a users table" mixes the what with the how. Put implementation in the technical section, not the requirements list.
3. Open-ended scope. "And anything else that improves the experience." The agent will obediently invent things. List the out-of-scope items explicitly.
4. Hidden assumptions. "It should work like Linear's keyboard shortcuts" assumes the agent has internalized Linear. Spell out the actual behavior.
5. Missing acceptance per requirement. Every P0 item should have a paired acceptance line. "P0-1: Users can export their data as CSV. Acceptance: a 1,000-row export downloads in under 3 seconds."
6. Single-paragraph prose dumps. AI tools parse structure. Use bullets, numbered lists, tables, and headers. Prose paragraphs are read; structured content is followed.

A real PRD that ships

app/
  page.tsx                       // marketing landing
  api/auth/twitter/route.ts      // OAuth callback
  api/cron/daily-digest/route.ts // 7am job
  app/dashboard/page.tsx         // digest archive
  app/settings/page.tsx          // user settings
db/schema.ts                     // users, subscriptions, digests
lib/twitter/list.ts              // fetch list members
lib/twitter/rank.ts              // engagement ranking
lib/email/digest.tsx             // Resend email template

How long this PRD took to write

Twenty-five minutes from blank doc to the version above. The structure is the lever. Once you've internalized the eight sections and the per-tool appendix, you stop staring at a blank page and start filling slots. Most PRDs that ship cleanly with AI tools follow this exact shape.

The fastest way to get good at this

1. Write your next PRD using MakeMyPRD as the starting point. It produces the eight-section structure from a one-paragraph idea in under a minute.
2. Add the tool-specific appendix yourself. The generator can't know which tool you're using; you do.
3. Run the PRD through the agent and see what it asks back. Every clarifying question is a section you should have written better. Add it to your template.
4. Save your favorite PRDs as references. After 3 to 5, you'll have a personal style that's faster to apply than starting from scratch.
5. Date them. A PRD written in February 2026 may not reflect the tools you use in November 2026. Versioning matters.

FAQ

Should I include code in the PRD?

Almost never. Include the file tree, the schema definitions, and the API contracts. Don't include actual implementation code — the agent should write that. The exception is a single short example showing the expected shape (e.g., a 5-line type signature for a custom hook).

How do I handle a feature that needs back-and-forth design exploration?

Don't put it in the PRD as a single feature. Break it into a small v1 you can fully spec, then plan iteration cycles after seeing the v1 work. PRDs are not the place for "we'll figure it out as we go" — the agent will figure something out, and it probably won't be what you wanted.

What if my PRD is for an existing codebase, not a green-field project?

Add a "Current state" section between TL;DR and Goals. Describe the existing files, schema, and patterns the agent should respect. Most AI tools (especially Cursor and Claude Code) can read the repo, but a written summary still helps focus the agent on the relevant slice.

How do I write a PRD for an AI agent product?

Same structure, with an extra section on the agent's capabilities, the tool's it has access to, and the success criteria for autonomous behavior. The PRD template for AI Agent linked below has the full shape.

Do I need to write a new PRD for every feature?

No. For small features (under 1 day of work), a one-page brief is fine. For features that touch 3+ files or 2+ team members, a full PRD pays for itself. The signal is whether you'd want a written record if someone asked "what was supposed to happen here" in six months.