What is a PRD, and does a coding agent need one?
A product requirements document (PRD) is a written description of what a product or feature should do, who it serves, and why. A coding agent does not need a formal PRD for a fix that fits in one sentence. A larger change needs what a PRD records, the goal and the limits, which a short prompt usually leaves open.
Wikipedia's article says a PRD should generally avoid defining how the product will do it, so that designers and engineers can choose the solution.
A prompt of one line names the change. It rarely says why the change is needed or what must stay the same, and the agent fills each gap with a default that nobody chose. A PRD settles those points in a file that a person reviews before the code exists. In spec-driven development, the same content sits in a written specification that drives the agent's work.
How does a PRD work with a coding agent?
A PRD reaches a coding agent as text in its context, the same way a prompt does. For one feature, the PRD usually moves through these steps:
- A person writes the PRD, or has the agent draft it, and saves it as a Markdown file in the repository.
- A person reviews the PRD's goal, scope, and acceptance criteria before any code exists.
- The agent reads the file and writes a plan, e.g. in plan mode, that names the files it will change.
- A reviewer checks the plan against what the PRD puts out of scope.
- The agent writes the code and its tests and reports that the work is "done."
- A reviewer checks the diff against the same list.
- A person or a test checks the running software against each acceptance criterion.
Spec Kit, an open-source toolkit from GitHub, keeps each feature's spec in the repository, in its own folder under specs/, with the plan beside it.
What is an example of a PRD for a coding agent?
Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme wants a coding agent to "Let customers edit their delivery address during checkout." The product owner turns that request into this PRD, and the developer saves it as docs/prd/edit-address.md:
PRD: Edit the delivery address during checkout
Problem: customers who spot a wrong address on the review step
must restart checkout, and some leave without buying.
Goal: customers change the address without leaving checkout.
Users: signed-in customers on the review step.
Out of scope: address autocomplete, and any change to the payment step.
Open question: can the address change after payment?
Acceptance criteria
1. The review step and the confirmation show the new address.
2. The cart keeps its items and its total when the address changes.
3. An empty address shows an error and keeps the old one.
The work then takes these steps:
- The developer starts the agent in plan mode and points it at the file, e.g. with
@docs/prd/edit-address.mdin Claude Code. - The agent's plan adds an address autocomplete package. The developer deletes that step, because the PRD puts autocomplete out of scope.
- The agent edits 3 files and reports that its tests pass. None of the tests checks the cart.
- The developer runs acceptance tests, written from the criteria before the agent started, on a staging copy of the store. The address saved, but the cart emptied.
- The developer sends criterion 2 and the failure to the agent, which edits the code. The developer reruns the acceptance tests, and all 3 criteria hold.
The PRD did not find the bug. It gave the plan review a limit to enforce and the test a criterion to check. This example is simplified. A real PRD would also say how the team measures the goal, e.g. the share of checkouts completed after an address change.
How detailed should a PRD be?
A PRD for a coding agent should settle each choice that the agent would otherwise fill with a default, and little more. The file takes up space in the agent's context window, and Claude Code's best practices say that performance degrades as that window fills. A PRD for one feature usually has these sections:
- Problem. The problem says what goes wrong for users and why it needs fixing.
- Goal. The goal names the outcome and how the team will measure it.
- Users. The users section names who the change is for.
- Out of scope. This section, also called non-goals, lists what the change must leave alone, e.g. the payment step.
- Constraints. The constraints name rules the solution must follow, e.g. no change to an API that other services call.
- Acceptance criteria. The criteria are conditions that a person or a test can check as true or false.
- Open questions. The open questions list choices nobody has made, so the agent can ask instead of picking a default.
The detail should grow with the cost of a wrong default. Spec Kit's method document tells the agent to mark a gap in a request with [NEEDS CLARIFICATION] instead of guessing. Spec Kit's specify command marks only a few gaps and lists its other guesses as assumptions, so a reviewer reads that list too.
For larger features, Claude Code's guide recommends having the agent interview the developer and then write a spec. It says the most useful specs are complete on their own. They name the files and interfaces involved, state what is out of scope, and end with a check that the feature works end to end. A classic PRD leaves files and interfaces to the spec or the plan.
Criteria that cover only the happy path leave failure cases to the agent's defaults, so a PRD names at least one failure case, e.g. an empty address. Rules that apply to every change, e.g. a passing build, belong in the team's definition of done, not in each PRD.
What are the limits of a PRD?
A PRD has these limits:
- Nothing enforces it. The agent can still make out-of-scope edits, e.g. adding the autocomplete package that the plan review removed. A reviewer still compares the diff with the PRD.
- It goes stale. When later changes skip the PRD, it stops describing the software, which is spec drift. Editing the PRD in the same change as the code keeps the two in step.
- It holds only the decisions made before the work. The answer to an open question, e.g. whether the address can change after payment, often comes in the session and never reaches the PRD. A reviewer can recover intent from a saved session.
- It can record the wrong need. If customers leave checkout for another reason, the change can meet all 3 criteria while they keep leaving.
- A feature PRD stops at the feature. Its criteria can all hold while a customer task that spans several features fails, which a user journey test checks.
How is a PRD different from a spec and a plan?
A PRD says what to build and why, a spec says exactly how it must behave, and a plan says how to build it:
| Document | Question it answers | Usually written by |
|---|---|---|
| PRD | What to build, for whom, why, and what to leave out | A product owner or product manager |
| Spec | Exactly how the software behaves, down to each input and error | A developer, often with the agent |
| Plan | How the agent will build it, file by file | The agent, reviewed by a person |
A PRD can cover a whole product or release, while a spec usually covers one feature. In practice the line blurs. A feature PRD often holds the same content as a spec, and Spec Kit's method document calls its feature spec a "PRD." A technical requirements document (TRD), sometimes called a functional specification, breaks a PRD's requirements into technical detail, which a coding agent's spec and plan usually hold.
How does SpecStory help with PRDs for coding agents?
A PRD records the decisions made before the work. Later answers, e.g. whether the address can change after payment, stay in the agent sessions.
SpecStory keeps the conversations behind your code. It keeps the prompts and decisions from your coding agent sessions, so you can reuse them when the next task begins. Your sessions become local Markdown files you can read, search, and keep alongside your code, so the next PRD can start from them. Saving a session does not itself test the software.
FAQs
What is a technical requirements document?
A technical requirements document (TRD), also called a functional specification, is the document that turns a PRD's requirements into technical detail. When a coding agent does the work, that detail usually sits in the spec and the plan instead.
Should a PRD live in the repository?
A PRD usually belongs in the repository when a coding agent works from it. The agent can read the file there, and a reviewer can compare it with the diff. Editing the PRD in the same change as the code keeps the two in step.
Should a coding agent draft the PRD?
A coding agent can draft the PRD, e.g. by interviewing the developer and writing up the answers. A person still reviews the goal, the users, and the scope before any code exists, because the agent fills each gap with a default that nobody chose.
What sections does a PRD usually have?
A PRD for one feature usually has sections for the problem, the goal, the users, what is out of scope, the constraints, the acceptance criteria, and the open questions.