PRD vs Design Docs vs SPEC: Distinguishing the Three Core Docs in Feature Planning

PRD: Defining What and Why, Not How

PRD (Product Requirements Document) captures the product perspective, answering what to build and why it matters. It must never prescribe implementation details; instead it describes observable behavior and success criteria. The toolchain’s /prd command generates a nine‑section PRD (Overview, Goals, User Stories, Functional Requirements, Non‑Goals, Design Considerations, Technical Considerations, Success Metrics, Open Issues) and enforces two strict rules: each user story receives a unique US‑001 identifier and an acceptance standard that is observable, testable, or verifiable, and each functional requirement receives a FR‑N identifier describing a single behavior without using “and”. This discipline keeps PRD a neutral contract for product, design, development, and testing teams.

Design Document: Explaining Why a Particular Solution Was Chosen

A design document sits between PRD and SPEC, answering which solution and why . Inspired by Google’s design‑doc culture, it records high‑level implementation strategy, key design decisions, and the trade‑offs considered. Its skeleton mirrors Go’s proposal format: Abstract, Background, Design, Rationale, Compatibility, Implementation. The Rationale section must list at least one discarded alternative and the reason for its rejection (e.g., “We didn’t pick X because Y”). Background must use real‑world pain‑point code, Compatibility must openly acknowledge breaking changes, and Implementation must be backed by data and automation. Real‑world samples include Rust’s RFC process (forking rust-lang/rfcs, filling 0000-template.md, PR‑based discussion, final comment period) and Go’s proposal workflow (issues in golang/go or golang/proposal, weekly review group, explicit compatibility analysis).

SPEC: Detailing How to Build

SPEC (technical specification) translates the “what” of PRD into a concrete implementation contract for engineers or AI agents. It answers how and contains eleven sections: Summary, Architecture, Data Model, API Design, Business Logic, Error Handling, Security, Performance, Test Strategy, Implementation Plan, Open Issues & Risks. Each PRD user story maps to a SPEC chapter, each functional requirement maps to an API endpoint or business rule, and each acceptance criterion maps to at least one test case. SPEC forbids “TBD” or “TODO”; any missing detail must be moved to the “Open Issues” section. The twin command /code-to-spec can reverse‑engineer a SPEC from existing code, which is especially useful when an undocumented codebase must be handed to multiple AI agents.

Comparative Overview

All three documents share three core beliefs: plan before you code , ensure alignment , and embed anti‑ambiguity constraints . Their differences are summarized below:

Question answered : PRD – what/why; Design Doc – which/why; SPEC – how.

Perspective : PRD – user/product; Design Doc – decision‑maker/team; SPEC – implementer/agent.

Primary readers : PRD – product, design, dev, test; Design Doc – anyone needing a shared direction; SPEC – engineers or agents writing code.

Focus : PRD – requirements & acceptance; Design Doc – trade‑offs & alternatives; SPEC – architecture, API, data model, error handling.

Attitude to implementation : PRD deliberately avoids it; Design Doc debates it without detailing fields; SPEC specifies it down to executable detail.

Core section : PRD – Acceptance Standards; Design Doc – Rationale; SPEC – PRD‑to‑Test‑Case mapping.

Optionality : PRD is almost always required; Design Doc is written when real trade‑offs or breaking changes exist; SPEC is reserved for complex features or large‑scale agent‑driven work.

When to Skip

PRD is nearly always needed to agree on “what”. SPEC is optional for simple features that lack architectural decisions. Design docs are “on‑demand”: write them only when multiple viable solutions exist, when changes are destructive, or when a team needs pre‑implementation consensus.

Pipeline from Idea to Code

/prd  →  /to-design  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
   │           │                │            │
  需求(what)   决策与取舍          实现契约(how)   编码
               (why/which)

The output of each step becomes the input of the next, gradually lowering abstraction from “what” to “how”. If a change is straightforward, teams can jump from PRD directly to SPEC; otherwise, inserting a design doc prevents unvetted technical decisions from reaching code.

Terminology Confusion

Different organizations use the terms inconsistently. Joel Spolsky’s “functional spec” aligns with this article’s PRD, while his “technical spec” aligns with SPEC. Some teams treat functional and technical specifications as synonyms, while others split them. The key is to ensure the three questions—what, which, how—are each answered without mixing them.

Author’s Practical Guidance

When requirements are clear, focus on PRD; add SPEC only if migration or redesign introduces new interfaces or data structures.

If a change presents genuine alternatives or breaks existing behavior, write a design doc to record “we didn’t pick X because Y”.

For large‑scale parallel agent work, generate a SPEC so every agent follows the same field‑level contract.

Conclusion

PRD aligns the team on “what” to build, design docs justify “why” a particular path was chosen, and SPEC provides the precise “how” for implementation. Separating these concerns prevents miscommunication, reduces rework, and creates durable artifacts for humans and AI agents alike.

References

Joel Spolsky, Painless Functional Specifications – Part 2: What’s a Spec? (2000)

Joel Spolsky, Painless Functional Specifications – Part 1: Why Bother? (2000)

Malte Ubl, Design Docs at Google

The Rust RFC Book & rust-lang/rfcs Go Proposal Process & golang/proposal Productboard, “PRD vs Product Spec: Key Differences & When to Use Each”

Medium, “Decoding the Dichotomy: PRD vs TRD”

Wikipedia, “Product requirements document”