staff-engineering · staff
Architecture Decision Records (ADRs)
Quick answer
An Architecture Decision Record (ADR) is a short, durable note for a significant technical choice: context, decision, options considered, and consequences. Staff engineers use ADRs to make decisions inspectable, shareable across teams, and reversible when needed—not to generate bureaucracy for every library bump.
Why this matters
- Oral decisions evaporate when people change teams.
- Staff leverage is decision quality at scale, not only personal code output.
- ADRs feed architecture reviews, RFCs, and incident retros.
- Reversibility and cost become explicit instead of “we always did it this way.”
Learning objectives
- Decide when an ADR is warranted vs a ticket comment.
- Write a useful ADR in under a page.
- Link ADRs to RFCs and implementation.
- Maintain an ADR log without tool worship.
- Use ADRs in interviews and design reviews.
Explain like I am 5
When the team picks a path in the forest, write a note: why this path, what other paths we saw, and what might go wrong—so nobody argues about it every week.
Mental model
flowchart TD
Problem[Problem + constraints] --> Options[Options 2-4]
Options --> Decide[Decision]
Decide --> ADR[ADR document]
ADR --> Build[Implement]
Build --> Learn[New evidence]
Learn --> Supersede[Superseding ADR]
| Section | Purpose |
|---|---|
| Status | Proposed / accepted / superseded / deprecated |
| Context | Forces that make the decision necessary |
| Decision | What we will do (one sentence first) |
| Options | Realistic alternatives, not strawmen |
| Consequences | Good, bad, neutral follow-ons |
| Links | RFC, tickets, diagrams, owners |
Core concepts
Significant decisions only
Write ADRs for choices that are costly to reverse, cross-team, or shape quality attributes (latency, cost, security, operability). Skip ADRs for pure implementation details that live fine in PRs.
Context over conclusion
Readers need the constraints that made the decision rational: SLOs, compliance, team skill, timeline, existing platforms. Without context, every decision looks arbitrary.
Options with integrity
List 2–4 real options. Include “do nothing” when relevant. Note trade-offs honestly—Staff credibility dies when options are fake.
Supersession, not silent rewrite
When reality changes, write a new ADR that supersedes the old one. Keep history; do not edit the past into a fiction.
Lightweight tooling
A docs/adr/0001-title.md folder in the monorepo beats an unused wiki. Number sequentially. Link from the service README.
Worked example
Context: Payments API must publish domain events; dual-write to Kafka from the app is failing under partial outages.
Options: (A) dual-write with retries, (B) transactional outbox, (C) CDC from primary DB.
Decision: Transactional outbox (B).
Consequences: Extra table + poller; stronger consistency with the write path; operational ownership of the publisher; deferred CDC complexity.
Ship ADR-0017, link the RFC, assign the poller SLO.
Trade-offs
| Heavy ADR process | No ADRs |
|---|---|
| Slow for small choices | Tribal knowledge only |
| Clear audit trail | Repeated debates |
| Good for regulated domains | Fast local decisions |
Staff default: ADRs for significant choices; chat for the rest.
Failure modes
| Mode | Mitigation |
|---|---|
| Novel-length ADRs | One page; link deep dives |
| Decision after code | Write before or with the first PR |
| Unowned ADRs | Named owner + review date |
| Status rot | Quarterly sweep of “proposed” |
| Tooling theater | Prefer markdown in-repo |
Interview mode
Skeleton: “I treat ADRs as the unit of architectural memory—context, options, decision, consequences—used for cross-team alignment and safe supersession, not as process for every rename.”
Knowledge check
Context, options considered, and consequences
Only the chosen technology name
Full source code of the implementation
Delete older decisions when new ones land
Related
By Shubham Jain