Skip to content

Catalog Past Architecture Decision Records So Teams Stop Re-Litigating Choices

Give new engineers and tech leads a lightweight, searchable ADR index explaining WHY past database, auth, queue, and vendor choices were made—and what supersedes them.

Copy the prompt and paste it into the AI assistant you already use.

How to keep an ADR catalog alive without turning engineers into bureaucrats

  1. 01

    Document 'Constraints at the Time' so future readers show empathy, not scorn

    Choices that look suboptimal at 50 engineers made total sense at 6 engineers with 90 days of runway; recording 'Decided Oct 2024: 2 backend devs, <500 rps' explains everything.

  2. 02

    Never overwrite old ADRs—mark `Superseded by ADR-019` instead

    Architecture logs work like accounting ledgers: preserving the chain from ADR-004 to ADR-019 prevents someone in 2027 from accidentally reverting back to the failed 2024 approach.

  3. 03

    Include an explicit 'When to Revisit This Decision' threshold

    Writing 'Re-evaluate single-region Postgres write primary once write volume exceeds 4,000 TPS or EU data-residency ARR tops $500k' tells teams exactly when a debate IS warranted.

  4. 04

    Cap routine ADRs to 300 words right next to the codebase or eng hub

    If writing an ADR takes 4 hours, nobody writes them; a crisp 15-minute markdown file in `/docs/adr/` reviewed inside the PR captures 95% of institutional memory.

Common questions

Does every minor library or sprint implementation detail need an ADR?

No—reserve ADRs for decisions that are expensive to reverse, affect multiple squads, introduce a new infrastructure/vendor dependency, or alter security/data models.

What is the difference between a 5-page RFC and a 1-page ADR?

An RFC (Request for Comments) is the exploratory discussion document used to debate options beforehand; the ADR is the concise, permanent 1-page receipt recording what was finally decided.

Should non-engineering teams like RevOps or Data Analytics also use Decision Records?

Absolutely—Data teams recording why `Attribution Model v2` was chosen and RevOps logging CRM object architecture choices save massive re-litigation across leadership changes.

Learn more

Related guides and background articles for this task