PRDs and Design Docs

Purpose

This note clarifies what a Product Requirements Document (PRD) is, what a Design Document is, and when to use each in a project. It also outlines how both document types relate to Architecture Decision Records (ADRs) and provides a lightweight workflow and templates you can adapt inside the repository.

Product Requirements Document (PRD)

A PRD captures the what and why of a feature from the product or user‑value perspective.

  • Audience: Anyone concerned with the problem, user outcomes, or business goals (including future collaborators).
  • Focus: User needs, scope, success metrics, and high‑level constraints.
  • Typical Sections:
    1. Objective / Problem Statement
    2. Target Users & Use Cases
    3. Success Metrics & KPIs
    4. Scope and Out‑of‑Scope Items
    5. Non‑Functional Requirements (performance, security, compliance)
    6. Acceptance Criteria
    7. References (links to design docs, issues, research)

Design Document

A Design Document (DD) describes the how—the technical approach for implementing a feature or system.

  • Audience: Engineers and reviewers who need to understand implementation details.
  • Focus: Architecture, data flows, APIs, trade‑offs, testing, and rollout plans.
  • Typical Sections:
    1. Architecture Overview (with diagrams)
    2. Data Model & Schemas
    3. API / Interface Definitions
    4. Alternatives Considered & Trade‑offs
    5. Testing & Validation Strategy
    6. Rollout / Migration Plan
    7. Open Questions & Risks
    8. References (links to ADRs, code spikes, benchmarks)

Key Differences at a Glance

Aspect PRD Design Document
Primary Question What are we building and why? How are we going to build it?
Perspective User / product Engineering
Length Short narrative + bullet lists Medium‑length technical write‑up
Outcome Align on problem and success criteria Align on technical approach and trade‑offs
Changes Over Time Rare (only if product scope shifts) May evolve as implementation details change

Relationship to ADRs

  • ADRs capture single, high‑impact architectural decisions and their rationale.
  • A PRD can reference one or more Design Docs for implementation details.
  • A Design Doc should reference any ADRs that influenced its architecture choices.
  1. Start with a PRD when a new feature idea surfaces and you need clarity on objectives and success metrics.
  2. Draft a Design Doc once the PRD is accepted (or for solo work, once you are satisfied with the PRD content).
  3. Create ADRs only when an irreversible or hard‑to‑reverse architectural choice arises during design.
  4. Keep all docs in Git:
    • docs/prd/ for PRDs
    • docs/design/ for Design Docs
    • docs/adrs/ for ADRs
  5. Review docs via Pull Requests, just like code.

AI Assistance: Consider using Four Modes of AI-Assisted Coding to match your documentation phase with the appropriate AI assistance approach—from throwaway brainstorming to surgical refinements.

Templates

  • PRD Template
    docs/prd/YYYY‑MM‑Feature‑Name.md
# Title

**Date:** YYYY‑MM‑DD  
**Status:** Draft | Accepted

## Objective
...
## Users & Use Cases
...
## Success Metrics
...
## Scope / Out of Scope
...
## Acceptance Criteria
...
## References
...
  • Design Doc Template
    docs/design/YYYY‑MM‑Feature‑Name.md
# Title

**Date:** YYYY‑MM‑DD  
**Status:** Draft | In Review | Accepted | Implemented

## Product Requirements (link to PRD)
...
## Architecture Overview
...
## Data Model
...
## Alternatives Considered
...
## Testing & Rollout
...
## Open Questions
...
## References
...

Tip: For small solo features you can combine PRD and Design sections in one file, but split them when the audience or complexity grows.