Architecture decisions are rarely made in a vacuum. There are deadlines, budgets, team capabilities, legacy constraints, customer commitments, available technologies, and a level of risk the company is willing to accept at that moment.
Months later, much of that context is gone. People move on, the product grows, and yesterday's constraints are no longer obvious. What remains is the system and the question: “Why was it built this way?”
What problem are we solving?
An Architecture Decision Record, or ADR, is a short record of a meaningful architecture decision. It usually captures the problem, considered options, the chosen option, the reason for choosing it, and the consequences.
The point is not to document every class or configuration value. ADRs are useful for decisions that affect system boundaries, the cost of future change, operational risk, or dependence on a particular approach.
The key word is “why.” A diagram may show that the system uses several services. An ADR explains why the company chose those boundaries at that time and which alternatives it deliberately rejected.
What does the business get?
The business gets cheaper future decisions. When a migration, scale problem, or platform change appears a year later, the team does not need to reconstruct history from chat threads and the memory of two people.
This also reduces dependence on individuals. The departure of an architect or technical lead should not erase the reasons behind decisions the company has already paid to make.
ADRs help distinguish a permanent constraint from a temporary compromise. If a decision was made mainly to reach the market quickly, it can be revisited honestly later instead of being defended only because “that is how it works today.”
What does the team get?
The team gets shared context. A new engineer can understand not only how the system is structured, but how those boundaries evolved.
Repeated architecture debates become shorter. If an option was already discussed and rejected for a concrete reason, the team does not need to restart the same conversation every six months. If the reason is no longer valid, that is exactly when the ADR should be challenged.
Writing the decision also improves the decision itself. Explicitly listing alternatives and consequences often exposes weak assumptions before implementation begins.
What does the customer get?
Customers rarely see ADRs directly. They benefit from more consistent product evolution: fewer random rewrites, fewer decisions based on memory, and less risk that an important constraint disappears when the team changes.
This matters especially for long-lived integrations and products where new behavior must still respect older commitments.
What do we pay for it?
ADRs require the habit of writing. If every decision turns into a long document and an approval process, the practice will die quickly.
The opposite extreme is also harmful. Hundreds of records about trivial details create noise. The value comes from recording genuinely meaningful decisions and keeping their status clear: accepted, superseded, or rejected.
A record also loses value if new decisions never reference old ones. ADRs should describe the evolution of the system, not become a dead archive.
When are ADRs unnecessary?
A small, short-lived project with one developer and an obvious architecture may not need a formal decision log.
But the longer the product lives, the more teams participate, and the more expensive architecture changes become, the more valuable preserved context is.
What should we ask before adopting the practice?
- Which decisions truly affect the future cost of change?
- Could a new team member understand the reason for the choice a year from now?
- Which alternatives were considered and why were they rejected?
- What conditions would make us revisit the decision?
- How do we keep ADRs lightweight instead of turning them into bureaucracy?
In the end
Good architecture memory stores more than diagrams. It stores reasons.
ADRs help a company avoid paying twice for the same thinking and make it easier to see when an old compromise is no longer the right one.