A PRD template your coding agent can actually follow
The template, a filled example, and the five places a PRD written for people breaks when the reader is an agent.
Where this comes from
Quotes are verbatim from public Hacker News comments: parthupadhye, March 2026, esperent, August 2026 and submeta, April 2025. The template is ours; its requirement fields (ID, statement, priority, rationale, acceptance criteria, link to a story) are the ones Entalpa stores for every requirement. We have not measured how much a structured PRD reduces agent deviation compared with a free-form prompt. That run is planned and will be published with its method, not summarised as a number here.
Why a PRD written for people fails with an agent
When you replace a human engineer with an AI agent, the system stops halting on ambiguity — it fabricates a plausible but invalid solution and keeps moving.
parthupadhye, Hacker News
A PRD for a team can afford to be loose, because the engineer reading it asks. The gaps get closed in a thread, in standup, in a comment on the ticket. An agent does not ask. It reads the gap as permission, picks the most typical answer, and reports the task done. The same document that worked for a team becomes a list of guesses when the reader is Claude Code, Cursor or Codex.
People who build this way already know it. The workflow that keeps coming up is the same one every time:
But I need to write a PRD, break it down into features, epics and user stories, let the llm write code, review the results.
submeta, Hacker News
So the question is not whether to write a PRD. It is what a PRD has to contain when nobody on the other end will ask a follow-up question.
The template
Copy it into your repository as a markdown file, one per feature. Every section is there because an agent behaves differently without it; the next section says how.
# PRD: <feature name>
## Goal
One sentence: what changes for whom, and how you will know it worked.
## Users
- <who uses this, and what they are trying to get done>
## Out of scope
- <what this feature deliberately does not do>
## Requirements
### REQ-001 <short name>
- Requirement: <one verifiable statement>
- Priority: must | should | could
- Why: <the user or business reason>
- Acceptance:
- <a check someone can run and get yes or no>
## Decided, do not change
- <behaviour that looks wrong but is deliberate, and why>
## Open questions (blocking)
- Q1: <a question nobody has answered yet>
## Instructions for the agent
- Cite requirement IDs in every commit and test name.
- If a requirement is ambiguous, or an open question affects your task, stop and ask. Do not pick an answer.
- Do not edit this file.Five things a normal PRD leaves out
- An ID on every requirement. REQ-001 is something the agent can cite in a commit, a test name and a plan step, and something you can point at next session. "The expiry thing" is not.
- Acceptance criteria that return yes or no. "Secure" and "fast" are wishes. "A link opened at 61 minutes shows link expired" is a check the agent can write a test for, and one you can verify without reading the diff.
- An explicit out of scope. Agents widen scope when nothing says where the edge is. A list of what the feature does not do is the cheapest guardrail there is.
- Decisions that look like mistakes. If a behaviour is deliberately non-standard, write it down, or the next agent sent to fix a nearby bug will standardise it. That exact failure is written up in what your agent breaks.
- Open questions that block the build. A question with no answer is the one place an agent will invent one. Listing it, and telling the agent to stop there, turns a silent guess into a question you answer once.
I find if I'm leaving it run overnight, calling the plan a "PRD contract" and a looping message reminding it not to go out of scope reduces that to manageable levels.
esperent, Hacker News
That is the out-of-scope section and the agent instructions, arrived at by hand. The template writes them down once.
A filled example: password reset
"Add password reset" is the prompt most agents are given. Every line below is a decision the agent would otherwise make for you, and the typical answer is wrong for at least one of them in most products. The same feature is taken apart in why your agent guesses requirements.
# PRD: Password reset
## Goal
A user who forgot their password can set a new one without contacting support.
## Out of scope
- Magic-link login. SMS reset.
## Requirements
### REQ-001 Reset link expiry
- Requirement: A reset link is valid for 60 minutes from the moment it is sent.
- Priority: must
- Why: A link sitting in an inbox is a standing credential.
- Acceptance:
- A link opened at 59 minutes works; at 61 minutes it shows "link expired".
### REQ-002 Single use
- Requirement: A reset link can be used once.
- Priority: must
- Acceptance:
- Opening a used link shows "link already used", not the reset form.
### REQ-003 Sessions end on reset
- Requirement: Setting a new password signs out every other session.
- Priority: must
- Acceptance:
- A second browser signed in before the reset is signed out after it.
### REQ-004 No account probing
- Requirement: The reset form responds identically for known and unknown emails.
- Priority: must
- Acceptance:
- Same message, same status code, and no measurable timing difference.
## Decided, do not change
- Emails are lower-cased and trimmed before lookup. Legacy accounts were created that way.
## Open questions (blocking)
- Q1: Do admins get the same flow, or a support-assisted one?the test
Hand the filled PRD to a colleague who has never seen the product. Every question they ask is a line the agent would have guessed.
How to hand it to the agent
- Save it as specs/<feature>.md and reference it from CLAUDE.md or AGENTS.md, so the agent reads it without being told each session.
- Ask for a plan first, and check that every plan step names the requirement ID it implements. A step with no ID is scope you did not ask for.
- Review the plan against the PRD, not the diff against your memory. The reasoning is in reviewing the spec, not the diff.
- When the agent stops at an open question, answer it in the PRD, not in the chat. An answer in the chat is gone next session.
When the file stops being enough
A markdown PRD is the right start and, for a small project, the right end. It has two limits. It sits in a directory the agent can write to, so "do not edit this file" is a request, not a rule. And it is one file per feature: once there are twenty, nothing tells you which requirement a change touched, or which story a requirement came from.
Entalpa keeps the same structure as a store instead of a file. Stakeholders, stories and requirements are linked, each requirement carries its ID, priority, rationale and acceptance criteria, open questions are raised before the build, and a locked requirement is excluded from what the model is allowed to regenerate. Your agent reads it over MCP; the setup for each client is on connect your agent. Describe the feature in plain words and Entalpa drafts the sections above for you to review.
Questions this raises
What is a PRD?
A product requirements document says what a feature must do and how you will know it works: the goal, who it is for, the requirements, and the acceptance criteria. It does not say how to build it; that is the plan, which comes after.
How is a PRD for an AI agent different from a normal one?
It cannot rely on the reader asking. Every requirement needs an ID and a yes-or-no acceptance check, scope has to be stated explicitly, and unanswered questions have to be marked as blocking, because an agent fills any gap with the most typical answer and keeps going.
Should the agent write the PRD?
It can draft one, and a draft is useful for finding the questions you had not thought of. The decisions in it have to be yours: an agent-written PRD that nobody reviewed only moves the guessing one step earlier.
How long should a PRD be?
As long as the decisions in the feature. The password reset example above is four requirements and one open question; a billing change might be forty. Length is not the measure; whether a stranger could build it without asking is.
Entalpa gives your agent one locked source of truth
Structured, traceable requirements your agent reads over MCP — so it works from a curated spec instead of reconstructing your project every session. Free to start, no card, and MCP calls never spend credits.