ADR · Architecture Decision Record
An ADR — Architecture Decision Record — is a short document that records one important technical decision and, just as importantly, WHY it was made. Months later, when someone asks 'why on earth did we build it this way?', the answer is already written down.
Each ADR is small and follows the same shape: the Context (the situation that forced a choice), the Decision (what we chose), the Rationale (why), the Alternatives we considered, and the Consequences (what we gain and what we now live with).
You keep them as plain markdown files in the project, numbered in order (0001, 0002…), so the team's reasoning grows into a readable history rather than vanishing into someone's memory.
# 0001 · Use PostgreSQL for the primary datastore ## Status Accepted — 2026-06-09 ## Context <What situation forces a decision? Constraints, forces at play.> ## Decision <The choice we are making, stated plainly.> ## Rationale <Why this option, in one or two honest sentences.> ## Alternatives considered - <Option B> — why not - <Option C> — why not ## Consequences <What gets easier, what gets harder, what we now live with.>
A minimal ADR template — copy it into docs/adr/0001-title.md and fill the angle-brackets.
Keep them immutable: don't edit an old ADR — if a decision changes, write a new one that supersedes it. The trail of changed minds is the point.