Six months after a design meeting, someone asks, “Why didn’t we use the other option?” An architecture decision record (ADR) is the team’s receipt: a short document capturing a significant choice, its context, alternatives, and rationale. It preserves the reasoning for future teammates and helps prevent the same debate from starting over. section 2.3
An ADR focuses on one significant decision, rather than providing a broad blueprint for an entire feature like a design document or request for comments. Keep it short and store it in the repository as a historical record. section 2.7
A practical ADR can include:
- A title, date, status, and participants. section 2.7.1
- The problem context, options considered, and criteria used to compare them. section 2.7.1
- The tradeoffs, chosen option, and reasons for the choice. section 2.7.1
- Risks, mitigations, and a trigger for reviewing the decision. section 2.7.1
Choosing session storage
A web app needs sessions so users do not have to log in on every page. The team compares application memory, Redis, and a database table against availability, latency, deployment simplicity, and cost. Memory is fast and simple but loses sessions on restart and cannot share them across servers. Redis offers low latency and shared sessions but adds a service to maintain. The database is durable and operationally simple but adds latency and load. The team chooses Redis, records the risk that an outage could log users out, and plans to revisit the choice after a multi-region deployment or more than 10,000 concurrent sessions. section 2.7.1
Not every choice needs an ADR. Look for decisions that significantly affect the system or would be onerous to change; choosing between a loop and a map function does not need one. Before changing an existing design, check for an ADR: the original constraints may explain it, even if those constraints no longer apply. section 2.7 section 3.5.2
The record can also make an accepted business risk explicit. For example, if leadership chooses to bypass automated verification to meet a deadline, document the context, the decision, and the risk accepted. section 13.9.4






