What are architecture decision records?
An architecture decision record (ADR) is a short document that captures a single technical decision: what was decided, why it was decided, what alternatives were considered, and what consequences follow from the choice. ADRs are the most underused documentation practice in software engineering. They take 15 to 30 minutes to write and save hours - sometimes weeks - of future debate, investigation, and accidental reversal.
The concept was formalized by Michael Nygard in a 2011 blog post and has since been adopted by teams at ThoughtWorks, GitHub, Spotify, and thousands of smaller organizations. The format is deliberately lightweight: a single page per decision, written in plain language, stored alongside the code it describes.
ADRs solve a specific problem that comments, commit messages, and tribal knowledge cannot: they preserve the reasoning behind a decision in a form that survives team turnover, memory fade, and organizational change. Code tells you what the system does. Tests tell you what the system should do. ADRs tell you why the system is shaped the way it is.
Why does recording decisions prevent rework?
Without decision records, teams fall into a destructive cycle: a new team member or new lead joins, looks at an existing system, does not understand why a particular approach was chosen, proposes a rewrite, and the team spends weeks rebuilding something that was originally designed the way it was for good reasons - reasons that were never written down.
A 2022 study by the IEEE found that 60% of architectural refactoring efforts in enterprise software partially or fully duplicated decisions that had been made and abandoned by previous teams. The decisions were not wrong the first time - they were simply forgotten, and the rationale was lost when the original decision-makers moved on.
The cost of undocumented decisions
| Scenario | Without ADR | With ADR |
|---|---|---|
| New developer asks "why PostgreSQL and not MongoDB?" | 30-minute conversation with a senior engineer (if available) | 5-minute read of ADR-003 |
| Team lead proposes switching from REST to GraphQL | Two-week spike to evaluate, unaware that this was evaluated and rejected 18 months ago | Reads ADR-012, sees the trade-offs, decides context has changed enough to revisit - or not |
| Production incident caused by an architectural constraint | Hours of debugging to understand why the system behaves a certain way | ADR explains the constraint and the reason for it; team focuses on the actual fix |
| Security audit asks why a particular auth approach was chosen | Scramble to reconstruct reasoning from old Slack threads | ADR-007 documents the threat model and decision rationale |
What format should an ADR follow?
The beauty of ADRs is their simplicity. The standard format has five sections, each answering one question. A good ADR fits on a single screen and takes no more than 30 minutes to write.
The five-section format
- Title. A short, descriptive name. Use a numbering scheme: ADR-001, ADR-002, etc. Include the date. Example: "ADR-014: Use server-sent events for real-time board sync (2026-05-19)."
- Context. What situation prompted this decision? What problem were you solving? What constraints existed? Be specific - "we needed real-time updates" is vague; "board changes must propagate to all connected clients within 500ms without requiring page refresh" is useful.
- Decision. What was decided? State it clearly in one to three sentences. "We will use server-sent events (SSE) via an in-process EventEmitter for real-time board synchronization."
- Alternatives considered. What other options were evaluated and why were they rejected? This is the most valuable section. Future readers will ask "why not WebSockets?" or "why not polling?" - answer those questions here. Be honest about trade-offs: "WebSockets would enable bidirectional communication but require a persistent connection manager and complicate load balancing. SSE is simpler, works through standard HTTP proxies, and our use case is server-to-client only."
- Consequences. What follows from this decision, both positive and negative? "Positive: simpler infrastructure, no WebSocket upgrade handling, works through CDNs. Negative: no client-to-server push over the same channel, limited to ~6 concurrent connections per domain in HTTP/1.1 browsers, in-process EventEmitter will not scale past a single server without adding Redis pub/sub."
Optional additions
Some teams add a Status field (Proposed, Accepted, Deprecated, Superseded) and a Superseded by link when a decision is later replaced. These are useful but not essential - start with the five core sections and add metadata only if you find you need it.
When should your team write an ADR?
Not every technical choice deserves an ADR. Choosing between two npm libraries for date formatting is not an architecture decision. Choosing between a monorepo and multi-repo structure is. The threshold is: would a thoughtful team member reasonably disagree with this choice, or would they need context to understand why it was made?
Decisions that warrant ADRs:
- Database selection, schema design philosophy, or migration strategy
- Authentication and authorization approach
- API style (REST vs GraphQL vs gRPC) and versioning strategy
- Monorepo vs multi-repo, monolith vs microservices
- Deployment platform and CI/CD architecture
- State management approach (server state vs client state, caching strategy)
- Real-time communication mechanism (SSE, WebSockets, polling)
- Coding conventions that affect how the whole team writes code
- Build tooling choices (bundler, compiler, framework version)
- Security-critical decisions (encryption, key management, access control model)
Decisions that do not need ADRs: library choices with obvious dominance (using React for a React app), configuration values, minor refactoring, or any decision that is trivially reversible.
How do you use a kanban board to track decisions?
Decisions have a workflow just like features do: they are proposed, discussed, decided, and sometimes superseded. Tracking this workflow on a board gives the team visibility into pending decisions and prevents the common failure mode where decisions stall because nobody drives them to resolution.
Decision board columns
- Proposed - a decision has been identified but not yet discussed. The card describes the problem and the options on the table. Anyone on the team can propose a decision by creating a card.
- Discussion - the team is actively evaluating alternatives. Use card comments for async discussion. Set a time limit: if a decision is in Discussion for more than two weeks, it needs a synchronous meeting or a designated decider to break the tie.
- Decided - the decision has been made and the ADR is written. The card links to the ADR document in the repo or wiki. Move cards here only after the ADR is published.
- Superseded - a previous decision has been replaced by a new one. The original card stays for history; a new card in the Decided column references it.
In Flux, use labels to categorize decisions: infrastructure, API design, frontend, security, data model. Assign each decision card to the person responsible for driving it to resolution - not necessarily the person who makes the final call, but the person who ensures the discussion happens and the ADR gets written.
Linking decisions to implementation
ADRs are most valuable when they are discoverable from the code they affect. Common linking strategies:
- ADRs in the repo. Store ADRs in a
docs/adr/directory alongside the code. When someone navigates the codebase, the decisions are right there. - Code comments referencing ADRs. In the code that implements a non-obvious decision, add a comment:
// See ADR-014 for why SSE instead of WebSockets. This connects the "what" (the code) to the "why" (the ADR). - PR descriptions referencing ADRs. When a PR implements a decision, reference the ADR in the PR description. This creates a traceable chain: decision, implementation, and review.
What are the common mistakes with ADRs?
ADRs are simple in concept but easy to get wrong in practice. These mistakes undermine the value of the practice:
- Writing ADRs that are too long. An ADR is not a design document. It should capture the decision and its reasoning, not the full technical specification. If your ADR exceeds two pages, extract the detailed analysis into a separate design doc and keep the ADR as a concise summary.
- Omitting the alternatives section. The "Alternatives considered" section is the most valuable part. Without it, future readers cannot evaluate whether the decision still makes sense in their changed context. Always document what you did not choose and why.
- Not writing ADRs for rejected proposals. If the team spent significant time evaluating an approach and decided against it, that rejection is worth recording. It prevents the next person from going through the same evaluation. Use a "Rejected" status on the card.
- Writing ADRs after the fact. The best time to write an ADR is during the decision-making process, not weeks later when the reasoning has faded. Make ADR creation part of the decision workflow: the card does not move to Decided until the document is written.
- Never superseding old ADRs. ADRs are not permanent. When context changes and a decision is revisited, write a new ADR that references and supersedes the old one. The old ADR remains as historical context - never delete it.
For the broader practice of building documentation into your team's workflow, see the documentation culture guide. To manage ADR creation alongside other engineering work, the engineering backlog template includes a column structure that accommodates both feature work and documentation tasks.