What is an Architecture Decision Record — and why your team needs them.
Short answer
An Architecture Decision Record (ADR) is a short document that captures an important architectural decision: what was decided, why, and what alternatives were considered. ADRs are stored alongside the code in version control and build a searchable log of why the system is built the way it is. Introduced by Michael Nygard in 2011, they're now standard practice in engineering teams that care about long-term maintainability.
ADRs solve a specific and painful problem: six months from now, no one remembers why the system works the way it does. The developer who made the decision is gone, or forgot, or the context has been lost. The next developer to touch that part of the system makes a "fix" that breaks the design intent — because they didn't know the design intent.
The standard ADR format (Michael Nygard's original). Each ADR is a single short file — typically Markdown — stored in a directory like docs/decisions/.
- Title. ADR number and a short noun phrase: "ADR 0042: Use Postgres as the primary datastore."
- Status. Proposed / Accepted / Deprecated / Superseded (by ADR 0057). Status is tracked over time — an ADR can be superseded without being deleted, preserving the history.
- Context. The situation, constraints, and forces at play when the decision was made. This is the "why now" and "why this matters" section. Be honest about the constraints — time pressure, team skill, existing infrastructure.
- Decision. The decision itself, written in active voice. "We will use Postgres as the primary datastore."
- Consequences. What becomes easier because of this decision? What becomes harder? What new constraints does this create? Consequences can be positive, negative, or neutral — list all of them.
Why ADRs work. They're stored in the repository, so they travel with the code. They're versioned, so you can see what was decided and when. They're short (1–2 pages), so people actually write and read them. They don't require approval workflows — a team can adopt them tomorrow with zero tooling.
What goes in an ADR. Any decision with meaningful long-term consequences for the system: choice of database, authentication strategy, deployment architecture, API versioning scheme, choice between microservices and monolith. Not every code change — ADRs are for decisions where the rationale matters more than the code.
Tools and storage. Most teams store ADRs in a docs/decisions/ or docs/adr/ directory in the repo. adr-tools (a CLI by Nat Pryce) automates ADR creation and numbering. Some teams use Notion, Confluence, or a wiki — but the repo is strongly preferred because ADRs need to live where the code lives.
When architectural decisions are first discussed at a whiteboard, snap the board with BoardSnap. The AI reads the decision options, constraints, and tradeoffs written on the board and produces a first-draft ADR structure — ready to be polished and committed.
Frequently asked
Who invented Architecture Decision Records?
Michael Nygard introduced the ADR format in a 2011 blog post, "Documenting Architecture Decisions." The format was designed to be lightweight enough that engineers would actually write and maintain ADRs — in contrast to heavyweight architecture documentation that teams produce once and never update.
Where should ADRs be stored?
In the repository, alongside the code — typically in a docs/decisions/ or docs/adr/ directory. Storing them in an external wiki or document system breaks the connection between the decision and the code it applies to. Version control also means you can see who wrote each ADR and when, and diff changes over time.
Do ADRs need to be approved?
No — and that's intentional. ADRs are lightweight documentation, not governance process. Some teams request a brief review before changing an ADR's status from Proposed to Accepted, but the goal is to minimize friction so that the documentation habit sticks. A team waiting 2 weeks for ADR approval won't write ADRs.
See it work in ten seconds.
BoardSnap is free on the App Store. Snap a board — get a summary and action plan.