How to write a PRD for Claude Code
The short answer
To write a PRD for Claude Code, keep it short and checkable: the problem with the evidence, what becomes true, the files or areas involved, what not to touch, decisions already made, Done When lines it can verify, and where your rules file is. Write it once as plain Markdown so Cursor, Codex and Grok can read it too.
A PRD for Claude Code is a product requirements document written so a coding agent can build from it without guessing. It keeps what the agent cannot know and drops the narrative it does not need.
TL;DR
- A person who is unsure asks. An agent often guesses and keeps going. Write what removes the guess.
- Add five things a team PRD often leaves out: where in the code, what not to touch, what is decided, checks it can run, and where the rules are.
- Keep it plain Markdown in the repo. Then Claude Code, Cursor, Codex and Grok can all read the same file.
When to use it: any job larger than a one-line fix. When not: a small clear change needs only the outcome and a Done When line. For the human-readable version, see the PRD template, and for the basics, how to write a PRD.
What does an agent need that a person doesn't?
A teammate reads a PRD and fills the gaps from memory: the last meeting, the codebase, the unwritten rule. An agent starts each session with none of that. So the useful PRD for an agent has these parts, in this order of importance.
1. Done When lines it can check. "Fast" and "works well" cannot be checked. "Given a paid account, when they pause for 2 months, then no invoice is created" can. Write each line so the agent can run it, or point to a test or a page and see it pass. This is the biggest difference between a PRD for people and one for agents. See definition of done for AI agents.
2. The files or areas, if you know them. "The billing settings page and the daily billing job" saves a search and prevents a new, parallel implementation. If you do not know, say "not sure, search first". A wrong path is worse than none.
3. What not to touch. Name the near neighbors: "do not change the cancel flow, the invoice template or the pricing table". An agent that is not told where the edge is will tidy past it.
4. Decisions already made, with the reason. "Maximum 3 months, because nobody asked for longer." Otherwise the agent will reopen them, or quietly choose a different answer.
5. Where the rules file is. Standards, commands, test setup and style belong in AGENTS.md (or CLAUDE.md), not in each PRD. Claude Code reads CLAUDE.md at the start of every session and can read a repository's AGENTS.md in its place. If you have both, a CLAUDE.md can import AGENTS.md with an @AGENTS.md line. Your PRD should say "rules: AGENTS.md" and leave it there.
Add open questions too, marked: "if you reach this, stop and ask". An agent that knows what is unsettled will ask instead of inventing.
What can I leave out?
Most of what makes a PRD look finished to a committee: market sizing, personas, a launch timeline, a long background. If it does not change what gets built or how it is checked, it is context for people, not instructions for the agent. Keep a link to it, not a copy.
Keep the problem and the evidence, though. Two sentences and a quote do real work: they tell the agent what the change is for, which decides the small calls the PRD does not cover.
A PRD skeleton for an agent
Copy this, fill it in and save it as a Markdown file the agent can read. Then tell the agent to read it and check each Done When line before it says it is done.
# <Title: what becomes true>
Read this file, then the rules in AGENTS.md. Check each Done When line before you say you are done, and tell me which you ran and what you saw.
## Problem and evidence
<1-2 sentences.>
> "<their exact words>" (<account>, <where, when>)
Asked by: <number> accounts (<names or revenue>)
## What becomes true
<The outcome, present tense. Then the direction in a line.>
## Where in the code
- <path or area> (new | modify)
- If unsure: search first and tell me what you found.
## Do not touch
- <neighbor 1>
- <neighbor 2>
## Already decided
- <decision> because <reason>. Do not reopen.
## Done When
- Given <state>, when <act>, then <something you can check>.
- Given <state>, when <act>, then <something you can check>.
## Open questions
- <question>. If you reach this, stop and ask.
## Rules
AGENTS.md at the repo root: commands, tests, style.
How do I keep one PRD readable by Claude Code, Cursor, Codex and Grok?
Make it boring on purpose.
- Plain Markdown, plain headings. No tool-specific syntax or embedded diagrams that only one tool opens.
- One place for rules. AGENTS.md is a plain Markdown file in the repo root that many coding agents read. Keep how-we-build there. If you use Claude Code, a short CLAUDE.md that imports it keeps one source.
- One copy of the PRD. In the repo, or in a tool every agent connects to. Two copies drift, and you find out when an agent builds the old one.
- Say where it is. Start each job with "Read the PRD at <path>, then the rules in AGENTS.md."
- Ask for the receipt. "Check each Done When line and tell me which you ran and what you saw." That works the same everywhere.
Should I let the agent write the PRD?
You can draft it with the agent, but you decide what is in and out of scope. Give it your notes, the customer quotes and the repo, and ask it for a draft with Done When lines. Then read it as the person who owns the decision. Check the not-in-scope list and the open questions first: those are where drafts are thinnest.
How does Annsa do this?
Annsa is the source of direction for your agents, and its spec has this shape on every priority.
- The why and the evidence. Requests come in from Slack, Intercom, call transcripts, surveys, imports, GitHub, the API or by hand. Each keeps the customer behind it, their exact words, the account and its revenue.
- Done When lines. The spec holds them. You write it, your agent writes it over MCP, or Ask writes it.
- Files to touch. When Ask or your agent writes the spec with the repository as context, it can name the files and patterns involved. See codebase-aware spec.
- One spec for every agent. Claude Code, Cursor, Codex and Grok connect over MCP (remote, nothing to install), claim the work, read the spec and record evidence against each Done When line.
- Your order. Priorities are ranked inside your bets: what a person marked broken first, then what customers asked for, then ideas. You choose.
- Telling people. When the job ships, Share Back drafts a note to each person who asked. You send it.
See the spec, writing a spec and spec-driven development.
Sources: How Claude remembers your project, Anthropic, on CLAUDE.md and AGENTS.md. AGENTS.md, the open format for agent instructions. Product requirements document, Wikipedia.