Stackbook Logo
decision-makingestablished · low operational burden

Design Record

Also known as: design-doc, architecture-design-record

Intent

Capture a significant design as a durable, reviewable document that records context, options, decision, and consequences.

Problem

Design reasoning lives in chat threads and people's heads. New engineers cannot tell why the system looks the way it does, and teams re-litigate settled choices or undo them unknowingly.

Forces

  • •Decisions must be made quickly but remembered for years
  • •Writing costs time that delivery pressure tries to cut
  • •Context decays faster than code
  • •Reviewers need a stable artifact to challenge before building

Solution

Overview

A design record is a small document that answers one question: why did we build it this way? It names the problem, the forces in play, the options weighed, the choice made, and what the team accepts as a result. Unlike a wiki page, it is immutable once accepted, so it reads as a trustworthy timeline of the system's reasoning.

How it works

Each record lives in the repository, numbered and reviewed in a pull request. A lightweight template keeps them short.

docs/design/0007-use-postgres-for-ledger.md
  Status:       accepted (supersedes 0003)
  Context:      ledger needs ACID, 2k writes/s peak
  Options:      Postgres | DynamoDB | event store
  Decision:     Postgres with logical replication
  Consequences: single-region write path; revisit at 10x load

When circumstances change, authors add a new record and mark the old one superseded. The index of statuses becomes a map of current decisions.

Pitfalls

  • Writing the record after implementation, which turns analysis into rationalization.
  • Omitting rejected options. Future readers need to know what was ruled out and why.
  • Letting records sprawl into design essays. One decision per record keeps them findable.
  • Treating status as decoration. If superseded records stay marked accepted, the archive misleads.
  • Skipping consequences. The costs you knowingly accept are the most valuable part to revisit later.

Key takeaways

  • Record decisions, not just designs, and keep each one small.
  • Store records with the code and review them like code.
  • Never rewrite history; supersede it.
  • List rejected alternatives and accepted downsides explicitly.

✓ When to Use

  • •A choice is expensive to reverse (datastore, protocol, tenancy model)
  • •Several teams are affected by the outcome
  • •You expect staff turnover or long-lived systems

✗ When Not to Use

  • •Trivial, easily reversible choices
  • •Pure exploration where the answer is not yet known
  • •When nobody will ever read or review the record

Pros

  • +Preserves rationale, not just outcome
  • +Shortens onboarding and audits
  • +Forces options to be stated explicitly

Cons

  • −Adds writing overhead per decision
  • −Records go stale if superseding is not enforced
  • −Can become ceremony without real review

Cost Profile

Infrastructure

Low: a folder in the repository

Operational

Low: review and status upkeep

Cognitive

Low: simple template

Failure Modes

  • Records written after the fact become justification, not reasoning

  • Superseded decisions remain marked accepted

  • Template bloat makes authors skip it

Real-World Examples

Alternatives

  • architecture-decision-records

Related Patterns

  • adr
  • architecture-decision-records
  • rfc-process
  • tradeoff-analysis

Competency Domains

requirements constraintseconomics evolution