Architecture Decision Records and Product Requirements Documents

Neil Ernst & his AI buddy

2025-09-16

Introduction

  • Software projects require both technical decisions and requirements clarity.
  • Today we’ll cover:
    • Architecture Decision Records (ADRs)
    • Product Requirements Documents (PRDs)

Why Decisions Matter

  • Software architecture is full of trade-offs.
  • Decisions are often made under time pressure and incomplete knowledge
  • Risk: future teams forget why a choice was made.

Architecture Decision Records (ADRs)

  • Concept by Michael Nygard (2011).
  • Lightweight way to capture architectural decisions.
  • Each decision = one small text file, max 1-2 pages printed. No overuse of bullets.
  • Stored alongside code in version control.
  • Otherwise, people forget, don’t check, don’t update (eg PDF documents, manuals, powerpoint).

Motivating ADRs

  • Avoids “tribal knowledge” loss.
  • Improves onboarding for new developers.
  • Encourages explicit decision-making.
  • Provides rationale when revisiting past choices.

ADR Format (Nygard)

  1. Title
    Short, descriptive (e.g., “Use PostgreSQL for persistence”).

  2. Context
    The forces, requirements, constraints. Often in tension. Here you can list the tradeoffs (“performance vs maintainability”)

  3. Decision
    In active voice, what was decided - “we will…”

  4. Status One of “proposed”, “accepted”, “superseded”, “deprecated”.

  5. Consequences
    Positive and negative results of the choice.

ADR Example

(too short!)

Title: Use REST for service communication
Status: Accepted
Context: Need interoperability across services, many clients.
Decision: Use REST over HTTP with JSON.
Consequences:
- ✅ Widely supported
- ✅ Easy client integration
- ❌ More verbose than binary protocols
- ❌ Performance overhead

ADR Usage in Practice

  • Each ADR in a file: adr/0001-use-rest.md
  • Sequential numbering for easy reference.
  • Linked when one decision replaces another.
  • Reviewed during design and code reviews.

Transition to Requirements

Requirements

  • ADRs capture technical decisions.
  • But what about what the product should do?
  • That’s where Product Requirements Documents (PRDs) come in.

Product Requirements Documents (PRDs)

  • A PRD defines what the product must achieve.
  • Written for:
    • Engineers
    • Designers
    • Product managers
    • Stakeholders

Why PRDs Matter

  • Prevents ambiguity in product goals.
  • Aligns engineering with business objectives.
  • Serves as a contract of intent between stakeholders.

Typical PRD Structure

  1. Overview – what is being built.
  2. Objectives & Goals – why it matters.
  3. User Stories / Use Cases – who benefits.
  4. Functional Requirements – what it must do.
  5. Quality Attribute Requirements – performance, security, etc.
  6. Milestones & Deliverables – timeline.

PRD Example (Excerpt)

Overview:
We are building a mobile app for avalanche risk assessment.

Objectives:
- Enable offline use in backcountry.
- Provide a risk matrix for decision-making.

Functional Requirements:
- User inputs slope angle, shape, traps.
- System fetches avalanche forecast when online.
- Display final risk as Green/Yellow/Red.

ADRs vs PRDs

ADRs PRDs
Technical choices Product goals
Small, lightweight files Larger guiding document
Context–Decision–Consequences Goals–Requirements–Use cases
Maintained by dev team Cross-functional ownership

Wrap-up

  • ADRs: capture architectural decisions, context, and rationale.
  • PRDs: define what the product must achieve and why.
  • Together: ensure projects are both technically sound and aligned with goals.

Discussion

  • Have you ever worked on a project where decisions weren’t documented?
  • How might ADRs or PRDs have helped?