Architecture Decision Records (ADRs)

Scenario

Example organisation: a 40-engineer product organisation. A new hire asks why orders use event sourcing while everything else uses CRUD. Nobody remembers; the engineer who chose it left. The team spends two meetings debating whether to "undo" it — and then finds out it was required for an audit trail.

What you see on the team

• The same architectural debates every few months.
• Decisions that live only in Slack threads or in people's heads.
• New joiners afraid to change anything because they can't tell what's intentional.
• Reversals of past decisions that re-introduce problems the decision had solved.

The common mistake

Relying on memory, chat and long design docs to carry decisions. Design docs describe a project; they aren't updated and are hard to find years later.

Why it happens

Recording decisions feels like overhead at the moment they are made — everyone in the room knows the reason. The cost shows up later, for people who weren't in the room. Michael Nygard's original post, Documenting Architecture Decisions, proposed short records kept with the code precisely so the reasoning outlives the meeting.

The playbook

Keep ADRs in the repository (e.g. docs/adr/0007-event-sourcing-for-orders.md), numbered, never deleted. Use Nygard's minimal format:

# 7. Use event sourcing for orders

Status: Accepted (2026-03-02). Supersedes: none.

## Context
Audit requires a full history of every order change for 7 years.
CRUD updates overwrite state; reconstructing history from logs failed the last audit.

## Decision
Orders are stored as an append-only event stream; read models are projections.

## Consequences
+ Complete, queryable history for audit and support.
- More complex reads; projections must be rebuilt on schema changes.
- Only the orders service uses this pattern; others stay CRUD.

Write an ADR when a decision is hard to reverse or will surprise someone later: data stores, communication patterns, security models, major libraries, conventions.

Supersede, don't edit. When a decision changes, write a new ADR that supersedes the old one, so history stays readable. adr.github.io collects templates and tooling.

Make it part of the workflow: a design doc that's accepted produces an ADR; code review asks "does this need an ADR?" for architectural changes.

What to say

When a past decision is challenged:

"Let's check ADR 7 first — it says event sourcing was chosen for the audit requirement. If that requirement still holds, we keep it; if it's changed, let's write ADR 15 to supersede it."

Trade-offs

• Too many ADRs (one per library bump) become noise; reserve them for significant, lasting decisions.
• ADRs in the repo are close to the code but harder for non-engineers to find; link them from the team's docs page.
• Short format loses detail; link to the design doc for the long version.

Signals it's working

• Debates start with "what does the ADR say?".
• New joiners read the ADR log in their first week and ask better questions.
• Superseded ADRs show a clear evolution of the architecture.
• Fewer accidental reversals of intentional decisions.

Key points

• An ADR is a short record of context, decision and consequences, stored with the code.
• Write them for hard-to-reverse or surprising decisions, not every change.
• Never edit or delete — supersede with a new ADR.
• Tie ADRs into design reviews and code review so they actually get written.