| name | writing-prd |
| description | Use when the user wants to "build", "add", "implement", or "design" a new feature; when a request is described in user-facing terms ("we want users to..."); when scope is fuzzy or stakeholders aren't aligned; before a technical plan is written. Skip for pure refactors, bug fixes, and tooling changes. |
Writing a PRD (Product Requirements Document)
A PRD answers WHAT we're building and WHY, before a plan answers HOW. It prevents wasted technical work on unclear or mis-scoped requirements.
When to write a PRD
- New user-facing feature
- Significant change to existing user behavior
- Cross-team feature with multiple stakeholders
- Scope or success metrics are unclear
Skip a PRD when: the change is internal-only (refactor, dependency upgrade, fix), or scope is one or two files with obvious user impact.
Output location
PRDs live in claudedocs/prds/ using the naming convention YYYY-MM-DD-short-name.md. A blank starter exists at claudedocs/prds/_template.md.
After the PRD is approved, a corresponding plan is written in claudedocs/plans/ and linked via the related frontmatter field.
Required sections
Every PRD must contain these sections in this order:
1. Problem
What is broken, missing, or painful today? One paragraph. Avoid jumping to solutions.
❌ "We need to add OAuth login."
✅ "New users abandon signup at 38% on the email-confirmation step. Magic-link reliability is the top cited reason in support tickets (n=42 last quarter)."
2. Users
Who has this problem? Be specific — "users" alone isn't enough. Name the persona, their context, and how often they hit the problem.
3. Success Criteria
How will we know this worked? Measurable outcomes preferred over qualitative ones.
✅ "Signup-to-active-user conversion improves from 62% to ≥75% within 30 days."
❌ "Users find it easier to sign up."
Each criterion should be checkable: a number, a yes/no, or a checklist item.
4. Scope
- In scope — bullet list of behaviors/screens/flows this PRD covers.
- Out of scope — explicit list of things deliberately NOT in this version. The out-of-scope list is often more valuable than the in-scope list because it prevents scope creep.
5. Risks & Open Questions
- Known unknowns (auth library compatibility, third-party SLA, etc.)
- Decisions that need stakeholder input before the plan can proceed
Frontmatter
---
title: Human-readable feature name
status: draft | approved | superseded
date: YYYY-MM-DD
related: [list of plan/decision/implementation paths once they exist]
---
status lifecycle:
draft — written, not yet approvedapproved — stakeholders agreed; ready for plan + implementationsuperseded — replaced by a newer PRD (link to it via related)
Process
- Discover — ask clarifying questions about problem, users, success metrics. Don't assume.
- Draft — write the PRD using the 5 required sections. Keep it short (1 page if possible).
- Review — surface open questions explicitly. Wait for human approval before changing status to
approved.
- Hand off to plan — create
claudedocs/plans/YYYY-MM-DD-short-name.md, link the PRD in its related frontmatter, and update claudedocs/INDEX.md.
Common mistakes
- Solutioning in the Problem section — describes the fix, not the user pain.
- Vague success criteria — "improve UX" cannot be verified at completion.
- Missing out-of-scope list — every PRD without one will grow during implementation.
- Skipping straight to the plan — a plan answers HOW; without a PRD, you may build the wrong thing efficiently.
Related
claudedocs/prds/_template.md — boilerplate to copy..claude/rules/documentation.md — documentation conventions and INDEX upkeep.- After approval, hand off to
claudedocs/plans/ (technical design).
