What ADRs actually are
An Architecture Decision Record is a short document that captures: what decision was made, what options were considered, why this option was chosen, and what trade-offs were accepted.
That is all. The format is secondary. The discipline is what matters.
Most ADR adoption fails because teams treat them as documentation — something to write after the decision has been made, so there is a record. That makes them low-value artifacts that nobody writes and nobody reads.
The use that actually compounds is different: write the ADR before the decision finalizes, as a communication tool for the people who need to understand the reasoning.
Why the timing matters
An ADR written after a decision captures what happened. An ADR written before a decision closes surfaces disagreements, unexamined assumptions, and missing context while there is still time to act on them.
The discipline of writing down the options and the reasoning — before the decision is made — forces a clarity that verbal discussion rarely achieves. It also creates a natural review surface. When the document exists, people who were not in the decision conversation can read it and add perspective.
Teams that use ADRs well typically have a lightweight process:
- When a decision is approaching, the person driving it writes a draft ADR in 30-60 minutes
- The draft is shared with the relevant people and sits open for 2-3 days
- Comments, alternatives, and objections are added inline
- The decision is made with the context in front of everyone
- The ADR is updated to reflect the decision, including a note on dissent if it exists
Step 5 is often skipped. Including the dissenting view is the part that makes ADRs useful years later, when someone is re-evaluating the decision and needs to understand not just what was chosen but why the alternatives were not.
The three questions every ADR should answer
Most ADR templates have too many fields. What matters is:
What decision are we making? One sentence, specific. Not “how should we handle authentication” — “should we use AWS Cognito or build our own JWT middleware for the authentication service.”
What did we consider? List the real alternatives that were evaluated. If only one option was evaluated, note that and explain why.
Why this choice? What made this option better than the alternatives for this context, with these constraints, at this point in time? The constraint specificity matters. A decision that was right at 5,000 users may not be right at 500,000. Recording the context makes the decision revisable later.
Where ADRs fail
The two most common failure modes:
Nobody reads them. ADRs that live in a documentation system nobody visits are expensive artifacts. The fix is access — the ADR should live close to the code it describes, discoverable by anyone who touches that code. A /decisions folder in the repository is better than a Confluence page.
They capture decisions that do not matter. Teams that write ADRs for every library choice dilute the signal. An ADR is warranted when the decision is consequential, not reversible in a day, or involves a meaningful trade-off. Which logging library to use does not usually meet that bar.
The compound value
The value of a mature ADR collection is not any individual record. It is the trail.
When a new engineer joins, they can read the decision records for the systems they are working on and understand not just what exists but why it exists. When an existing engineer proposes changing a system, they can read the ADR for the system and understand what was tried before and what was rejected and why.
This is the knowledge transfer problem that most organizations solve by keeping specific people around. ADRs solve it by encoding the reasoning in a form that outlasts the person who held it.