How to write a PRD that Claude Code or Cursor can build from

Why the PRD changed in 2026

For twenty years a PRD was an alignment document. Its reader was a person: an engineer who would ask questions in a meeting, push back on a bad requirement, and fill small gaps with judgement. A PRD could be vague because a human would resolve the vagueness.

A coding agent resolves vagueness by choosing the most statistically likely interpretation and building it, fast, without asking. That is the whole problem. Ambiguity that used to cost a ten-minute conversation now costs a wrong implementation, a review, a revert and a second run. Teams that ship with agents all day noticed the same thing in 2025: the quality of the output tracked the quality of the written spec more closely than the choice of model.

Two open-source projects made the shift visible. GitHub's Spec Kit, released in September 2025, structures agent work as a gated sequence: a constitution of project principles, a specification, a technical plan, a task list, and only then implementation. As of October 2026 the repository shows about 143,000 stars. Task Master, by Eyal Toledano, does something narrower: task-master parse-prd your-prd.txt turns a PRD into a dependency-ordered task list that Cursor, Windsurf or Claude Code work through; the repository shows about 28,000 stars as of October 2026. Both tools assume the PRD is the interface to the agent, not a memo to the team.

That is the shift in one sentence: the PRD stopped being a document people agree on and became the input an agent executes.

What an agent needs from a PRD

An agent needs four things, and most PRDs give it none of them cleanly.

Numbered, atomic requirements. One sentence per requirement, with a stable ID (R1, R2, R3). "The user can reset their password by email" is a requirement. "The user has a smooth account recovery experience" is not. IDs matter because the agent, the plan, the tasks and the tests will all refer to them.

An acceptance criterion the agent can test. For every requirement, write what a passing check looks like, in terms the agent can execute: an HTTP response, a database state, a rendered element, a CLI exit code. If you cannot phrase the check, the requirement is not finished.

Explicit non-goals. Agents over-build. Left alone, "add password reset" becomes a reset flow plus a rate limiter plus an audit log plus a settings page to configure them. A non-goals section ("No rate limiting in this iteration. No admin UI. No SMS.") is the single cheapest line you can add to a PRD, and it removes more wasted work than any other.

Constraints and the existing shape of the system. Which framework, which database, where the auth lives, which files not to touch, which conventions to follow. Spec Kit calls this the constitution. In Cursor it lives in rules files; in Claude Code it lives in CLAUDE.md; in Codex it lives in AGENTS.md. The PRD should reference these rather than repeat them.

Before and after: the same requirement, rewritten

The table below is drawn from our own PRDs. The left column is how we used to write; the right is what an agent can act on.

The right-hand column is longer per requirement and shorter overall, because the vague paragraphs that used to surround each line are gone.

The template, section by section

Here is the skeleton we use. It is Markdown because every agent reads Markdown, and because it diffs cleanly in Git. Inside a code block, section labels are shown in bold rather than as headings so the structure stays visible.

**Feature:** Password reset by email
**Owner:** (name)   **Status:** Draft | Frozen   **Baseline:** v1 (2026-10-28)

**Problem**
Users who forget their password email support. Support handled 41 such
emails in September 2026. There is no self-serve path.

**Goal**
A signed-out user can reset their own password in under two minutes
without contacting anyone.

**Requirements**
R1. A signed-out user can request a reset by entering their email.
    Passes: POST /auth/reset with a known email returns 200 and creates
    one password_reset row expiring in 30 minutes.
R2. An unknown email returns the same 200 response and creates nothing.
    Passes: POST /auth/reset with an unknown email returns 200; row count
    unchanged.
R3. The reset email contains one link that opens a form with new-password
    and confirm fields.
    Passes: the link in the captured test email resolves to /auth/reset/:token
    and renders both fields.
R4. Submitting a valid token and matching passwords updates the hash,
    deletes the token and signs the user in.
    Passes: the integration test reset_happy_path completes and the user
    reaches /home.
R5. Expired or used tokens show "This link has expired" and a button to
    request a new one.

**Non-goals**
No rate limiting in this iteration. No SMS. No admin UI. No change to the
sign-in form.

**Constraints**
Follow CLAUDE.md. Use the existing mailer (lib/mail). Do not add a
dependency. Tokens are 32 random bytes, hex-encoded.

**Open questions**
Q1. Should a reset also sign out other sessions? Decision owner: (name),
    due 2026-10-30. Until decided, do not implement.

**Out of scope for the agent**
Copywriting of the email body: a placeholder is fine.

A few notes on the choices.

• Status and baseline. "Frozen" with a version and date means the agent builds against this text and nothing newer. We freeze before the first run and bump the version when a requirement changes, so a later audit can compare what shipped with what was agreed.
• Passes lines. They are written next to the requirement, not in a separate test plan. The agent reads them as a test specification, and most will write the test first.
• Open questions with a decision owner. An open question without an owner is a gap the agent will fill. "Until decided, do not implement" is the instruction that prevents that.

How to write one in an afternoon

1. Write the problem in three sentences with one real number. If you do not have the number, go and get it. "Support handled 41 reset emails in September" beats "users struggle with recovery".
2. List requirements as single sentences, then number them. Aim for 5 to 15. If you pass 20, the feature is two features; split the PRD.
3. Write a passes line under every requirement. If you cannot, either the requirement is not atomic or you do not yet know what done looks like. Both are worth finding before the agent does.
4. Write the non-goals before anyone reads the requirements. Ask: what would an eager engineer add here that we do not want? Write those down.
5. Point at the constraints file rather than restating it. Keep CLAUDE.md, AGENTS.md or your Cursor rules as the single source for conventions.
6. Freeze it. Mark the status, set the version, and put it where the agent can read it: a file in the repository, or a page the agent can fetch through an MCP server.
7. Run the agent on R1 only. Review that output before letting it run the rest. The first requirement tells you whether the PRD is readable by the agent at all.

Where the PRD lives, and how the agent reads it

A PRD in a Google Doc is invisible to Claude Code. The options that work:

• A file in the repository. docs/prd/password-reset.md, referenced from CLAUDE.md or AGENTS.md. Simplest, version-controlled, and every agent can read it. Spec Kit and Task Master both assume this.
• A page the agent fetches through MCP. If your team writes PRDs in a workspace tool rather than the repository, an MCP server lets the agent read the page directly. Atrix exposes its pages, issues and cycles through an MCP server with 85 tools and OAuth 2.1; it is listed in the Official MCP Registry and on Glama. The practical effect is that a coding agent can read the frozen PRD page, create the planned issues, and update them as it finishes, without copying text between tools. The limit to state plainly: the agent reads and writes workspace objects, it does not run your code or your tests.
• Both. We keep the canonical PRD as a page, and the agent copies the frozen version into the repository at the start of a run so the commit records exactly what it built from.

For the Cursor and Codex sides specifically, the Cursor integration and the Codex integration describe the setup: one OAuth connection, then the agent sees the PRD, the backlog and the current cycle as tools.

What to leave out

Everything that a human needs and an agent does not:

• Personas and user research. Keep them in a linked page; the agent needs the requirement, not the persona.
• Competitive analysis. Same.
• Mockups, unless the requirement is visual. If it is, a screenshot the agent can see beats three paragraphs describing it.
• Timelines. The agent does not plan sprints; your cycle does.

The classic PRD still exists; it just stops being the document the agent reads. If you want the longer form for stakeholders, our AI PRD template covers that version, and the PRD template on the site is the hosted copy you can duplicate.

FAQ

Is a PRD for an AI coding agent the same as a spec in spec-driven development?

Close to it. Spec-driven development, as Spec Kit frames it, separates the specification (what and why) from the plan (how, with which stack) and the tasks (the ordered work). The PRD described here is the specification layer. The plan and tasks are generated from it, by the agent or by a tool like Task Master.

How long should a PRD for Claude Code or Cursor be?

Short enough to fit in the agent's context next to the code it is touching. In practice 400 to 1,200 words, with 5 to 15 numbered requirements. If it is longer, split the feature.

Do I still need user stories?

Not in the "As a user, I want" form. The agent needs the requirement and the acceptance criterion; the story wrapper adds words without adding testable content. Keep stories if your team uses them for planning, but put the numbered requirements first.

What goes in CLAUDE.md or AGENTS.md versus the PRD?

Conventions go in the rules file: stack, folder layout, test commands, style, files not to touch. The PRD is per feature and references the rules file. Repeating conventions in every PRD leads to drift between them.

Should the agent write the PRD?

It can draft one from a brief, and the draft is often a good checklist of what you have not decided. Atrix's agent does this in a Develop run: brief in, requirements, architecture and planned issues out, 100 runs a month on Builder. But the freeze, the non-goals and the decisions on open questions are yours. An agent will not know what you do not want built.

How do I know whether the agent built what the PRD said?

Diff the result against the frozen baseline, requirement by requirement, using the passes lines. Atrix's requirements audit does this comparison against the frozen page; it checks coverage and drift of requirements, not the code itself. For the code, run the tests the passes lines imply, and review the auth and payment paths by hand.

Next step

Copy the PRD template, write R1 with its passes line, and run your agent on that one requirement before you write R2. If your PRDs live outside the repository, the MCP server is how Claude Code, Cursor and Codex read them.

Sources

GitHub Spec Kit repository, star count read on 27 October 2026; Spec-driven development with AI: get started with a new open source toolkit, GitHub Blog, September 2025; Task Master repository, star count read on 27 October 2026.