Product Requirements
The discipline of defining what to build, why, and how it should behave — through documents that capture intent at increasing levels of precision, so nothing is left to guesswork.
What is it?
Product requirements is the discipline of turning a rough idea into a chain of increasingly precise documents. Each document answers a different question — from “what are we building?” down to “what exactly should this button do when clicked?”
Most software projects fail not because of bad code, but because of unclear intent. The gap between “I have an idea” and “the code does what I wanted” is enormous. Product requirements documents bridge that gap one step at a time, each step adding more precision and reducing more ambiguity.
The discipline matters even more in AI-assisted development. When you work with an AI coding agent, every gap in your requirements becomes a guess the agent makes. Some guesses are fine. Many are wrong. Well-written requirements eliminate guessing and make every session deterministic.
In plain terms
Product requirements are like a blueprint process for building a house. You don’t go from “I want a house” straight to laying bricks. First you say what kind of house (brief). Then you specify rooms, budget, and constraints (PRD). Then the architect draws exact plans (spec). Then the builder creates a schedule (plan). Each step makes the next step possible.
At a glance
The document chain — from idea to code (click to expand)
graph TD A["Rough idea"] --> B["PRD"] B --> C["Technical Spec"] C --> D["Implementation Plan"] D --> E["Tasks"] E --> F["Code"] style A fill:#6b7280,color:#fff style B fill:#4a9ede,color:#fff style C fill:#4a9ede,color:#fff style D fill:#4a9ede,color:#fff style E fill:#6b7280,color:#fff style F fill:#6b7280,color:#fffKey: Blue nodes are the core product requirements documents. Each arrow is a refinement — the same intent, expressed with more precision. You don’t skip steps; you refine until it’s precise enough that an AI agent or developer can implement without guessing.
How does it work?
Product requirements exist as a hierarchy. Each level adds precision and answers a different question.
1. The document hierarchy
| Document | Precision level | Core question |
|---|---|---|
| Brief / idea | Low | What’s the concept? |
| prd | Medium | What specifically, for whom, what’s “done”? |
| technical-specification | High | Exact inputs, outputs, contracts, edge cases? |
| architecture-decision-records | Permanent | Why this approach over alternatives? |
Think of it like...
A zoom lens on a camera. The brief is a wide-angle shot of the landscape. The PRD zooms in to a building. The spec zooms to a single room. The ADR explains why you chose that room layout over alternatives.
2. The PRD — what and why
The Product Requirements Document captures the problem you’re solving, who you’re solving it for, what “done” looks like, and — critically — what’s out of scope. It’s written in plain language anyone can understand.
Example PRD statement
“Users can browse democratic instruments filtered by government level. Success: 80% of test users find the right instrument within 3 clicks. Out of scope: user accounts, personalisation, voting.”
Concept to explore
See prd for the full anatomy of a PRD, with all seven sections explained.
3. The technical specification — how exactly
The technical-specification translates the PRD into implementable contracts. It defines inputs, outputs, error cases, and acceptance criteria in enough detail that a developer or AI agent can build it without ambiguity.
Example spec statement
“GET /api/instruments?level=federal returns a JSON array of instruments sorted alphabetically. Missing locale parameter returns 400. Empty result returns 200 with an empty array, not 404.”
Concept to explore
See technical-specification for how to write specs that AI agents can implement precisely.
4. Architecture Decision Records — why this way
ADRs capture the reasoning behind significant choices. They record what options were considered, what was chosen, and what the consequences are — so no one wastes time re-debating settled questions.
Example ADR title
“ADR-003: Use server-side rendering instead of a single-page app for better SEO and accessibility.”
Concept to explore
See architecture-decision-records for the full ADR format and when to write one.
5. When to create each document
- PRD — when you commit to building something, before any code
- Spec — when you start implementing a feature or endpoint
- ADR — when you make a decision with multiple viable alternatives
- Plan — when a feature has multiple steps with dependencies
The golden rule
If an AI agent (or a new team member) would have to guess at your intent, you need a document for it. The cost of writing a half-page PRD is always less than the cost of correcting wrong assumptions in code.
Why do we use it?
Four problems product requirements solve
1. Building the wrong thing. Without requirements, you build what feels right in the moment. With them, you build what was agreed — and you can verify the result against the document.
2. Scope creep. Features expand silently when boundaries aren’t explicit. The PRD’s “out of scope” section is the brake pedal.
3. Knowledge loss between sessions. AI agents don’t remember past conversations. Requirements documents persist across sessions, so every session starts with the same shared understanding.
4. Re-debating settled decisions. Without ADRs, the same question gets asked every few weeks. With them, past reasoning is preserved and can be referenced instantly.
When do we use it?
- When starting a new project or a major new feature
- When working with AI coding agents that need explicit intent
- When multiple people (or multiple sessions) contribute to the same codebase
- When the scope is ambitious or unclear and needs bounding
- When you want to avoid drift between what was intended and what gets built
Rule of thumb
If you can describe the entire task in one sentence and finish it in one sitting, you might not need formal requirements. For anything bigger, the document chain saves more time than it costs.
How can I think about it?
The film production pipeline
Making a film follows the same refinement chain.
- Idea: “A heist movie set in space”
- PRD (screenplay treatment): Who are the characters? What’s the story arc? What’s the budget? What’s NOT in this film?
- Spec (shooting script): Exact dialogue, camera angles, scene durations, lighting notes
- ADR (creative decisions): “We chose practical effects over CGI because the budget is limited and the director values tactile authenticity”
- Plan (production schedule): Shoot desert scenes first because the location permit expires in March
Nobody goes from “heist movie in space” straight to filming. Each document makes the next step possible.
The recipe hierarchy
Cooking a complex dinner party follows the same pattern.
- Idea: “Italian dinner for 8 people”
- PRD: Menu with courses, dietary restrictions, budget, explicitly NOT making dessert (buying it instead)
- Spec: Each recipe with exact quantities, temperatures, timing, and what “done” looks like for each dish
- ADR: “We’re using dried pasta, not fresh, because the time savings outweigh the quality difference for this crowd”
- Plan: Start the sauce at 4pm, boil water at 5:30, serve at 6pm
The menu (PRD) says what you’re cooking. The recipes (specs) say how exactly. The decisions (ADRs) say why this way.
Concepts to explore next
| Concept | What it covers | Status |
|---|---|---|
| prd | Defining what to build, for whom, and what’s out of scope | complete |
| technical-specification | Defining exact behaviour: inputs, outputs, error cases | complete |
| architecture-decision-records | Recording the “why” behind significant choices | complete |
| implementation-plan | Ordering tasks with dependencies and milestones | stub |
| task-breakdown | Splitting a plan into actionable, estimable units of work | stub |
| spec-driven-development | The methodology that uses specs as the source of truth | stub |
Some of these cards don't exist yet
They’ll be created as the knowledge system grows. A broken link is a placeholder for future learning, not an error.
Check your understanding
Test yourself (click to expand)
- Explain the document chain from idea to code. What does each step add?
- Name the four core product requirements documents and describe what question each one answers.
- Distinguish between a PRD and a technical specification — give an example of a sentence that belongs in each.
- Interpret this scenario: a developer builds a user login system, but the PRD explicitly listed “no user accounts” as out of scope. What went wrong in the process?
- Connect this concept: why does AI-assisted development make product requirements more important, not less?
Where this concept fits
Position in the knowledge graph
graph TD SD[Software Development] --> PR[Product Requirements] SD --> SA[Software Architecture] PR --> PRD[PRD] PR --> TS[Technical Specification] PR --> ADR[Architecture Decision Records] PRD --> US[User Stories] TS --> AC[Acceptance Criteria] style PR fill:#4a9ede,color:#fffRelated concepts:
- spec-driven-development — the methodology that uses requirements documents as the source of truth for all code
- software-architecture — requirements inform architecture; architecture decisions feed back into ADRs
- domain-driven-design — the domain vocabulary established in requirements should flow through to code and database design
Further reading
Resources
- Spec vs. PRD vs. User Story: When to Use What (Intent) — Clear comparison of the three core document types and when each is appropriate
- How to Write Product Requirements: 2026 Guide (Parallel) — Practical templates and examples for writing requirements developers understand
- How to Write a PRD in 2026 That AI Tools Can Follow (PRD Creator) — The 13-section PRD template for the AI coding era
- The Product Requirements Document Is Not Dead (Boundev) — Why PRDs matter more than ever, with an engineering perspective
- How to Write a Good Spec for AI Agents (Addy Osmani) — The definitive guide to writing specifications that AI agents can implement precisely