Skip to main content

ADR Templates and Decision Records

Why ADRs matter​

Architecture Decision Records (ADRs) preserve context, alternatives, and consequences so teams can scale decisions without tribal knowledge.

Use ADRs for irreversible or high-impact decisions: rendering model, state ownership, package boundaries, security posture, observability standards.

ADR template​

# ADR-00X: <Decision Title>

- Status: Proposed | Accepted | Superseded
- Date: YYYY-MM-DD
- Owners: <team/person>
- Scope: <apps/surfaces impacted>

## Context
What constraints, risks, and goals force this decision now?

## Decision
What exactly are we choosing?

## Alternatives considered
1. Option A
2. Option B
3. Option C

## Tradeoff analysis
- Benefits
- Costs
- Risks
- Reversibility

## Rollout plan
Phases, milestones, and rollback strategy.

## Success metrics
How we will know the decision is working.

## Follow-up tasks
Concrete implementation tasks with owners.

Example ADR 1 — Rendering strategy for SaaS app​

Context​

The product contains SEO-critical marketing pages and highly interactive authenticated dashboards. Current all-CSR approach causes slow first load and weak indexability.

Decision​

Adopt hybrid model:

  • Marketing routes: static/ISR + edge caching
  • Authenticated app: server-rendered shell + client interaction islands

Alternatives​

  • Full CSR
  • Full SSR for all routes

Tradeoffs​

  • Hybrid increases architectural complexity but optimizes both SEO and interaction quality.

Metrics​

  • Marketing LCP p75 <= 2.5s
  • Dashboard INP p75 <= 200ms
  • Organic traffic growth on marketing pages

Example ADR 2 — State ownership model​

Context​

State logic duplicated across feature teams creates inconsistency and debugging overhead.

Decision​

Three-tier state ownership:

  • Server state in query/cache layer
  • UI session state local to feature modules
  • Cross-cutting app state in bounded global stores

Risks​

  • Misclassification of state boundaries.

Controls​

  • State decision checklist in PR template.
  • Linting rule to prevent direct global-store sprawl.

Example ADR 3 — Design system release policy​

Context​

Uncoordinated component changes cause regressions across multiple product surfaces.

Decision​

Versioned design-system packages with:

  • semantic versioning,
  • visual regression gates,
  • accessibility contract checks,
  • deprecation window and migration guides.

Success criteria​

  • 50% reduction in UI regression incidents over 2 quarters.

ADR review checklist​

  • Decision scope is explicit.
  • At least 2 alternatives are considered.
  • Tradeoffs include operational and business impacts.
  • Rollout + rollback are both documented.
  • Metrics and review date are defined.

Review prompts​

  • Does the ADR state the user, business, or operational risk?
  • Are rejected alternatives real options rather than strawmen?
  • Is the decision reversible, and is the reversal path named?
  • What production signal proves the decision is holding?

Source lens​

Use these templates with completed ADR examples, capstone solution packs, and Part I decision-making chapters.