How to write a PRD an AI agent can understand
A PRD for coding agents needs testable criteria, a list of files not to touch and clear limits. Structure, a worked example and the most common mistakes.
How is it different from a PRD for people?
A traditional PRD convinces a team and leaves room for conversation. An agent does not ask: when it finds a gap, it picks the implementation that seems most likely. That can be useful, or it can mean it changed a file nobody expected. ChatPRD describes this as a “fill in the blanks” problem: if you do not specify the technology or a requirement, the AI fills it in with whatever seems plausible. That is why a PRD for agents has to be more explicit in three things: scope, limits and how to check the result.
The foundation is the specification-first idea described in spec-driven development. GitHub presented it in September 2025 with its Spec Kit toolkit and a four-phase flow: specify, plan, break into tasks and implement. The PRD is the concrete document for the first phase.
Which sections should it have?
This structure combines the ChatPRD template with the one from Blake Crosley, who uses PRDs to have agents implement features:
- Product summary. One paragraph with the main goal, so the agent has context before the details.
- Users and use cases. Which role does what, and why. The “why” helps the agent choose between options.
- Requirements. Grouped by feature, each with its own list of conditions. Business rules sit inside the feature they apply to.
- Technical constraints. Framework, database, allowed dependencies and security rules. Do not assume the agent will infer them. The ones that apply to the whole project can live in CLAUDE.md or AGENTS.md.
- Out of scope. What is explicitly not done. It is the cheapest way to prevent features nobody asked for.
- Files to modify and files not to modify. With concrete paths.
- Acceptance criteria. The list that the agent and a person review at the end.
ChatPRD warns against vague goals: “improve the user experience” is too broad and can push the AI into many unrelated changes (ChatPRD, PRDs for AI Software Engineering).
How do you write an acceptance criterion?
A criterion works if someone can verify it by looking at the screen or running a test. Illustrative example of the difference:
| Vague criterion | Testable criterion |
|---|---|
| Dark mode should work well | The toggle appears in Settings; when enabled, the background changes to #111; the value is saved in user_preferences.dark_mode |
| Search should be fast | Results appear in under 300 ms with 1,000 records |
| Errors should be clear | If the email is empty, “Enter your email to continue” appears under the field |
Crosley writes criteria as Markdown checkboxes that the agent ticks during implementation. His current template includes the files to modify, the files not to touch, test expectations and constraints such as adding no new dependencies. He also notes that agents sometimes ignore constraints, and that explicit exclusions (“do NOT do X”) work better for him than instructions phrased in the positive (Blake Crosley, PRD-driven development).
Which tasks work and which do not?
Crosley reports approximate success rates from his own repository, after more than 30 PRDs. They are figures from one author and one project, not a general measurement, but the pattern is useful:
| Task type | Approximate success |
|---|---|
| CRUD endpoint | 95% |
| New tests | 90% |
| Database migration | 90% |
| UI component following an existing pattern | 85% |
| Bug fix with reproduction steps | 80% |
| New feature with no precedent | 50% |
According to the same author, it fails more with ambiguous requirements, architecture decisions, performance optimization and security-critical code such as authentication edge cases. The practical conclusion: a well-written PRD widens what the agent can do alone, but in ambiguous areas human review remains the main safeguard.
Example
Illustrative example: a designer wants the agent to add a dark mode option to a dashboard. The PRD has a three-line summary, a list of requirements (the toggle appears in Settings, the preference is saved per user, the default is light), one constraint (“add no dependencies”) and a list of files not to touch: the login component and the database configuration. There are four acceptance criteria, all testable. When the agent finishes, the designer reviews the diff against those four criteria before accepting it.
How do I apply it tomorrow?
- Write the PRD for a small task, such as adding a field to a form, using the seven sections in this article. Note how long it takes you and how many questions remain unanswered.
- Before asking for the change, ask the agent to repeat the PRD in its own words. If it repeats it wrongly, the document has a gap.
- List three files that must not be touched and write them in the PRD with the reason.
- When reviewing, mark each criterion as met or not met. If a criterion cannot be marked, rewrite it as an observable condition.
- Keep the PRD in the same repository as the code and update it in the same change when a rule changes. If it lives elsewhere, it easily goes stale.
To see the full flow, read spec-driven development. And to debug a response that fails a criterion, see debugging with AI.
Common mistakes
- Writing the PRD as a conversation instead of a list of conditions.
- Leaving out the list of files not to touch.
- Criteria that depend on subjective judgment.
- Not saying what is out of scope.
- Asking for security or architecture features without human review.
- Updating the code but not the PRD, so the document goes stale.
Sources
- ChatPRD, “PRDs for AI Software Engineering”: https://www.chatprd.ai/resources/prd-for-ai-codegen
- Blake Crosley, “PRD-driven development”: https://blakecrosley.com/blog/prd-driven-development
- GitHub Blog, “Spec-driven development with AI: Get started with a new open source toolkit”: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/