How to write a PRD for Claude Code and Cursor

A PRD for Claude Code or Cursor has one job: leave the agent nothing to decide that has a business impact. This page shows how to write one: the parts it needs, a worked example with Gherkin scenarios, and the files that carry it into your repository. Spec-driven development lives or dies on whether the spec is good enough, and the hard part is finding what's missing.

Where the PRD is vague, the agent decides

Give Claude Code a one-paragraph PRD and it will build something. Fast, confident, and full of decisions you never made.

Here is a brief for a budget app for a shared flat: "A budget app for our flat: everyone sets a budget, adds expenses and sees who owes whom." The goal is clear.

Now count what the agent has to decide on its own. Is the split equal by default? What happens when an expense pushes someone over their budget: block it, warn, allow it? What happens when someone deletes an expense that is already part of a settlement? Who counts as a member after someone moves out? The brief answers none of these. Agents guess where the spec is vague, and the guesses come out in the code without a label.

We call these silent decisions.

The usual fix is a longer prompt: more sections, a template, "be specific". It helps a little. But you can't be specific about a decision you haven't noticed you have to make. Someone has to find those four questions before any text gets written. A template only gives you boxes for the answers you already had.

Seven things a PRD for AI coding agents has to contain

An agent-ready PRD can be short, as long as it closes the gaps the agent would otherwise fill. For the flat budget app, that means seven things:

• A goal in one sentence, so every guess has something to be tested against: keep shared costs within budget and settle without arguments.
• The actors and what each may do: member, admin, a member who has moved out.
• Business rules, stated once: how an expense is split, how a cent is rounded, who pays the remainder, what happens when a budget is exceeded.
• Scope and non-goals: no bank sync, no foreign currencies, no receipts.
• Acceptance criteria as scenarios the agent can turn into tests.
• Failure states: what happens when the user deletes a settled expense, or enters a negative amount.
• Constraints that hold everywhere: money is stored as integer cents.

If you want a PRD template for AI coding agents, this is its shape:

# <Feature or product name>
## Goal             One sentence. Every guess is tested against it.
## Actors           Who uses it, and what each may do.
## Business rules   Stated once, one ID each (BR-001).
## Scope            In scope, and non-goals.
## Scenarios        Gherkin, one example per rule.
## Failure states   What happens when it goes wrong.
## Constraints      What holds everywhere. Goes into AGENTS.md / CLAUDE.md.

The shape is the easy part. The content is where the work is.

The acceptance criteria are the item people skip. Gherkin is the format that works, because each scenario is one example the agent can run:

Scenario: An expense is split equally between current members
  Given the flat has three members: Ana, Ben and Chris
  When Ana adds an expense of 10.00 for "Groceries"
  Then Ben owes Ana 3.33
  And Chris owes Ana 3.33
  And Ana carries the remaining cent

Two words of prose would have said "split equally". The scenario forces the question nobody asked: what happens to the third cent?

One more decision: where it lives. Rules that hold across the whole project (stack, conventions, money as cents) belong in AGENTS.md / CLAUDE.md or your Cursor rules. Behavior of one feature belongs in the spec for that feature. Mixed together, the agent weighs a naming convention the same as a business rule.

Seven items are easy for one story. Write them for forty stories and keep them consistent, and that's where it breaks.

A generated PRD has no visible gaps

You can ask Claude to write the PRD. It will. Two thousand words, every section filled, a tidy list of non-goals.

Now read it for the flat budget app and find what's missing. You can't, not easily. Plausible text has no seams. A review catches what is written wrong. A gap is what isn't written at all, and you'd already have to know the question to notice it. That's the original problem, one step later.

Template tools and PRD writers hit the same limit from the other side. They give your answers a good home, but the answers still have to come from you. A PRD generated from one prompt seldom says "we don't know yet." It's the most useful sentence a PRD can have.

An interview reverses the order: questions first, text second. "Who is still a member after moving out?" arrives while one sentence is enough to settle it. Found in code review, the same gap costs a rework.

What protects you is the list of questions you had to answer to write the PRD. The document records the answers.

Four phases, each closing a different gap

Speclr runs that interview in four phases. Each asks a different kind of question. Risks and constraints surface in every phase, wherever they show up.

Discovery asks whether and why. For the flat app: why would a flat want budgets at all, who lives there, what does "settled" mean? It ends in a short vision brief you can read in a minute, including the quality goal everything else is measured against: members can rely on every balance being correct. Behind the four questions from the start sits a bigger one: does this flat need a budget app at all? We take that up in [Link: Vision page]. asks whether and why. For the flat app: why would a flat want budgets at all, who lives there, what does "settled" mean? It ends in a short vision brief you can read in a minute, including the quality goal everything else is measured against: members can rely on every balance being correct. Behind the four questions from the start sits a bigger one: does this flat need a budget app at all? We take that up in [Link: Vision page].

Exploration is classic user story mapping. The backbone is the path a flat member walks: set a budget, add an expense, see balances, settle up. Budgets come first, because nobody can add a meaningful expense before one exists. Then each step gets sliced into stories: "set a budget" becomes a personal budget, a shared budget, a change mid-month. is classic user story mapping. The backbone is the path a flat member walks: set a budget, add an expense, see balances, settle up. Budgets come first, because nobody can add a meaningful expense before one exists. Then each step gets sliced into stories: "set a budget" becomes a personal budget, a shared budget, a change mid-month.

Planning is the second half of the map: cutting it into milestones. Which slices ship first? For the flat: budgets and expenses make the first release, settling up comes second. That is the MVP, the scope you launch with. is the second half of the map: cutting it into milestones. Which slices ship first? For the flat: budgets and expenses make the first release, settling up comes second. That is the MVP, the scope you launch with.

Refinement goes story by story. Each story gets its actors, its business rules and its Gherkin scenarios, so this is where user stories turn into Gherkin. It's also where "who may edit an expense" gets asked, with the rules from the other stories already on the table. goes story by story. Each story gets its actors, its business rules and its Gherkin scenarios, so this is where user stories turn into Gherkin. It's also where "who may edit an expense" gets asked, with the rules from the other stories already on the table.

You choose how much to drive: answer every question yourself, let Speclr pre-fill proposals you correct, or run a phase on auto. The interview also knows when to stop. Speclr scores how well each area is covered, and when coverage is strong it proposes to close the phase instead of asking for the sake of asking.

One good story takes four phases. The hard part is story forty.

Forty stories later, the rules start to disagree

Story 3 says: only the person who paid can edit an expense. Three weeks later, story 17 says: any member can correct any expense until it's settled, so mistakes don't pile up. Each story is reasonable. Each has clean scenarios.

An agent builds story 17 on Tuesday, in a fresh session that knows only story 17. Story 3 was built the week before. Now the app has two permission checks, or one that overwrote the other. Every test passes, because every test belongs to one story. The bug shows up as "sometimes I can edit Ben's expense, sometimes I can't."

Consistency belongs to the whole set of stories. No single story can show it, so no review of a single story will find it. That's why the check has to run across all of them, and why it has to run while the spec is still being written.

Speclr does this in three places:

• Rules live once. Business rules, actors and data fields belong to the project, not to a story. "Who may edit an expense" is one rule that stories reference, not seventeen copies. Business rules, actors and data fields belong to the project, not to a story. "Who may edit an expense" is one rule that stories reference, not seventeen copies.
• Conflicts surface in the same turn. When Refinement writes a rule that contradicts an existing one, the interview stops and asks: replace the old rule, narrow it as a special case, or accept that both stand. When Refinement writes a rule that contradicts an existing one, the interview stops and asks: replace the old rule, narrow it as a special case, or accept that both stand.
• A background check reads across stories. Perspective agents review the spec from their own viewpoint: consistency, risk, QA, security and architecture. They catch what the live check can't see: a rule against a data field, a constraint against a story in another phase. Perspective agents review the spec from their own viewpoint: consistency, risk, QA, security and architecture. They catch what the live check can't see: a rule against a data field, a constraint against a story in another phase.

Rules that hold across projects, your organization's constitution, are coming soon.

A consistent spec still has to reach the agent in a form it can use. That's the last step.

What happens when the dinner costs more than the budget

Take one rule from the flat app and run it both ways.

Ana adds a 60.00 dinner for the flat, split three ways. Her share is 20.00, and her budget has 15.00 left. The vague PRD says nothing about this, so the agent decides, and it picks the answer that sounds responsible: reject the expense with "budget exceeded."

That's the worst answer available. The money is already spent. The app refuses to record it, Ana enters it later by hand or never, and the balances everybody trusts are wrong. A reasonable guess, silently wrong. It also breaks the one promise in the flat's vision brief: members can rely on every balance being correct.

Here is the same moment as an interview in Speclr:

Speclr: Ana adds a 60.00 dinner, split three ways. Her share is 20.00, her remaining budget is 15.00. The money is already spent. Which wins, the budget or the record?

You: The record. Budgets warn, they never block.

Speclr: One more case before we write this down. Ben's share is 20.00 too, and it pushes him over his own budget, though he added nothing. Does Ben get a warning?

You: Yes. Each of them is told about their own budget, and nobody about anyone else's.

Two answers, and the rule writes itself. A budget never blocks an expense. When an expense pushes a member over budget, including through their share of someone else's expense, that member is notified. Nobody else is told.

Scenario: A shared expense pushes members over budget
  Given the flat has three members: Ana, Ben and Chris
  And Ana has a monthly budget of 100.00 and has spent 85.00
  And Ben has a monthly budget of 100.00 and has spent 85.00
  When Ana adds a shared expense of 60.00 split equally
  Then the expense is recorded
  And Ana's spent amount becomes 105.00
  And Ben's spent amount becomes 105.00
  And Ana is notified that she is over budget by 5.00
  And Ben is notified that he is over budget by 5.00
  And neither is told about the other's budget

Then the perspectives read it.

QA asks what happens when Ana corrects the dinner to 45.00 and Ben drops back to exactly his budget. Is his warning withdrawn? asks what happens when Ana corrects the dinner to 45.00 and Ben drops back to exactly his budget. Is his warning withdrawn?

Scenario: Correcting an expense withdraws a budget warning
  Given Ben was notified that he is over budget by 5.00
  When Ana corrects the dinner from 60.00 to 45.00
  Then Ben's spent amount becomes 100.00
  And Ben's over-budget notification is withdrawn

Security points out that a member's budget and remaining amount must not appear in anyone else's view. The "who owes whom" screen shows shares, never budgets. points out that a member's budget and remaining amount must not appear in anyone else's view. The "who owes whom" screen shows shares, never budgets.

Architecture reads the rule against the vision brief. The brief promises that members can rely on every balance being correct. In quality-model terms that is functional correctness: the degree to which a system delivers correct results with the needed precision (ISO/IEC 25010). A warning is only as correct as the number it reads, and the spec never says where "spent amount" comes from. The perspective proposes a single source: the sum of the recorded shares, calculated in whole cents. Without it, a rounded display value and a stored value drift apart, one cent at a time. reads the rule against the vision brief. The brief promises that members can rely on every balance being correct. In quality-model terms that is functional correctness: the degree to which a system delivers correct results with the needed precision (ISO/IEC 25010). A warning is only as correct as the number it reads, and the spec never says where "spent amount" comes from. The perspective proposes a single source: the sum of the recorded shares, calculated in whole cents. Without it, a rounded display value and a stored value drift apart, one cent at a time.

Scenario: Shares are calculated in whole cents and add up exactly
  Given the flat has three members: Ana, Ben and Chris
  When Ana adds a shared expense of 10.00 split equally
  Then the shares are 3.34 for Ana, 3.33 for Ben and 3.33 for Chris
  And the shares add up to 10.00

Each of these findings would have been a bug. Now they are sentences, written before the agent starts.

The spec has to arrive where the agent works

A spec in a browser tab helps nobody. Speclr generates AGENTS.md / CLAUDE.md from your requirements, together with the files it points to, and writes them into your repository as plain files, in the places agents already look:

AGENTS.md / CLAUDE.md          # how to work here, with a Speclr-managed block
docs/
  prd.md                       # vision, MVP scope, milestones, risks
  domain/
    rules.md                   # business rules with IDs (BR-021)
    actors.md
    data-fields.md
    glossary.md
  open-questions.md            # unresolved findings, accepted coexistence
features/
  budgets/
    us-014-budget-warning.md
    us-014-budget-warning.feature

Each location has one job.

AGENTS.md / CLAUDE.md is loaded at the start of every session, so a line belongs there only if it changes behavior on every task. Speclr writes a short block into it and leaves the rest of the file alone. Your stack, your build commands and your team conventions stay yours. In Cursor, the same content goes into your project rules.

<!-- speclr:begin — managed by Speclr, edit in Speclr -->
## Spec
- Product spec: docs/prd.md. Domain: docs/domain/. Stories and scenarios: features/.
- Before implementing a story, read its spec and its .feature file.
  Scenarios are the acceptance tests.
- If a scenario contradicts the code or another story, stop and ask.
  Don't change scenarios silently.
- Use the terms from docs/domain/glossary.md in code, tests and UI.

## Standards (from your org constitution)
- …

## Invariants
- Money is stored and calculated in integer cents.
- A member's budget is visible only to that member.
<!-- speclr:end -->

The Invariants are the project-wide constraints from the second section. The Standards come from your organization's constitution, which is coming soon.

docs/ holds what the whole product shares: the PRD with vision, MVP scope, milestones and risks, plus business rules, actors, data fields and a glossary. Rules carry IDs, so a story can point at BR-021 instead of restating it. open-questions.md lists what is still undecided and which conflicts you accepted on purpose.

features/ holds one folder per epic and two files per story. The story spec is self-contained: context, business rules, actors, data fields, non-functional requirements, scope limits and open questions. The scenarios exist once, in the .feature file next to it.

<!-- Generated by Speclr · edit in Speclr · exported 2026-10-02 -->
# US-014 — Budget warning for shared expenses

**Epic:** Budgets  |  **Milestone:** MVP  |  **Status:** Ready

## Context
As a flat member I want to be warned when an expense pushes me over my budget,
so that I can adjust before the month ends.

## Business rules
- BR-021  A budget never blocks recording an expense.
- BR-022  A member is notified when an expense pushes them over budget,
          including through their share of someone else's expense.
          Nobody else is notified.
- BR-023  The notification is withdrawn when a correction brings the member
          back within budget.
- BR-004  (project-wide) The spent amount is the sum of the recorded shares,
          calculated in whole cents.

## Actors
- ACT-001  Member: sees only their own budget.

## Data fields
- DF-007  budget.monthlyAmount: integer cents, ≥ 0

## Non-functional requirements
- NFR-002  Members can rely on every balance being correct
           (functional correctness, ISO/IEC 25010).

## Scenarios
See ./us-014-budget-warning.feature

## Out of scope
- Blocking expenses, budget history, notification channels beyond in-app.

## Open questions
- None

The export runs in one direction. Every generated file says where it came from and where to change it. Two places to edit would bring back the drift from the section on forty stories.

Open questions ship too. An agent that reads "Open: …" knows where the spec ends and where it has to ask instead of guess. That's the sentence a generated PRD seldom contains.

Starting a feature then takes one instruction:

Implement US-014. Read AGENTS.md first, then features/budgets/us-014-budget-warning.md and its .feature file. Make every scenario pass. If a scenario contradicts the code or another story, stop and ask.

The agent still writes the code. You made the decisions earlier, in sentences you can read.

Questions about writing a PRD for Claude Code and Cursor

Further Reading

Your next PRD, without the guessing

Take your next feature through the interview before you prompt. Speclr is free for 14 days.

Get started