ADR
ay-dee-AR
An Architecture Decision Record that documents a significant technical decision and its reasoning.
An ADR (Architecture Decision Record) is a short document that captures a single architectural decision. It records what was decided, why it was decided, what alternatives were considered, and what the consequences are. It is a snapshot of the team's thinking at a specific moment.
ADRs solve a common problem: six months from now, nobody remembers why the team chose PostgreSQL over MongoDB, or why the API uses REST instead of GraphQL. Without ADRs, new team members question existing decisions, relitigate settled arguments, or make changes that conflict with the original reasoning.
The format is deliberately simple. Title, status (proposed, accepted, deprecated), context (why this decision needed to be made), decision (what we chose), and consequences (what follows from this choice). Most ADRs fit on a single page. They live in the codebase, typically in a docs/adr directory, version-controlled alongside the code they describe.
Examples
A team chooses a frontend framework.
ADR-007: 'Use React for the web application.' Context: we need a frontend framework that supports server-side rendering and has a large hiring pool. Decision: React with Next.js. Alternatives considered: Vue/Nuxt (smaller community), Svelte/SvelteKit (harder to hire). Consequences: we accept the complexity of React's ecosystem and commit to Next.js App Router conventions.
A team decides on an authentication strategy.
ADR-012: 'Use Supabase Auth instead of building custom authentication.' Context: building auth from scratch will take 6 weeks and requires ongoing security maintenance. Decision: use Supabase Auth with JWT tokens. Alternatives considered: Auth0 (expensive at scale, $23K/year at projected usage), custom implementation (6 weeks + maintenance). Consequences: we are coupled to Supabase's auth roadmap.
A team deprecates a previous ADR.
ADR-023: 'Migrate from REST to GraphQL for mobile clients.' This supersedes ADR-005 ('Use REST for all APIs'). Context: mobile clients make 12 API calls per screen load due to REST's fixed response shapes. GraphQL lets mobile clients request exactly the data they need in a single call. The REST API remains for third-party integrations. Status: accepted.
In practice
ADR template (Nygard format)
ADR [NUMBER]: [Title] Date: [DATE] | Status: [Proposed/Accepted/Deprecated/Superseded] CONTEXT [What is the issue that we are seeing that is motivating this decision?] DECISION [What is the change that we are proposing and/or doing?] CONSEQUENCES [What becomes easier or more difficult to do because of this change?] --- Discussion participants: [Names] Supersedes: [ADR number, if applicable] Superseded by: [ADR number, if applicable]
Read more on the blog
Frequently asked questions
How is an ADR different from a design doc or RFC?
An ADR records a single decision. A design doc describes how to build something (which may involve many decisions). An RFC proposes a change for discussion. Think of it this way: an RFC is the discussion, a design doc is the blueprint, and an ADR is the permanent record of one specific choice. ADRs are typically shorter (one page) and more focused than design docs.
Should you update ADRs when decisions change?
No. Mark the old ADR as deprecated or superseded and create a new one. The old ADR is still valuable because it records the original reasoning and context. If ADR-005 chose REST and ADR-023 later chose GraphQL, both documents together tell the story of how the architecture evolved. Editing the original would erase that history.
Related terms
A technical document that describes how a system or feature will be built before implementation begins.
A Request for Comments document that proposes a technical change and invites structured feedback from the team.
The accumulated cost of shortcuts and deferred work in a codebase that slows future development.
The structure and organization of a database, defining tables, columns, types, and relationships.
Application programming interface: a defined way for software programs to communicate with each other.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.