What is an architecture decision record (ADR)?

An architecture decision record, ADR, is a short document that records a single significant architectural decision in a project's life: why it was made, which alternatives were on the table, and what consequences it carries over time. The format, introduced by Michael Nygard in the November 2011 post "Documenting Architecture Decisions", has four fixed sections: context (the situation that made the choice necessary), decision (what was decided, stated actively), consequences (what changes as a result, including what is given up), and often a status field (proposed, accepted, or superseded by a later ADR). Each ADR is a short, numbered, immutable file: if the decision changes, the old record is not rewritten but a new one is written that supersedes it, so the sequence stays a readable history rather than a living document someone has to keep current.

Why it matters when inheriting a system

The value of an ADR is rarely visible at the moment it is written, and almost always visible two or three years later, when whoever wrote it is no longer at the company. During technical due diligence on a project taken over from a previous vendor, or during an internal audit of a legacy system, the recurring question is "why was it built this way": why that database and not another, why that integration pattern, why that boundary between services. Without an ADR, the answer exists only in the memory of people who are often no longer reachable: it is the bus factor applied to architectural knowledge, the risk that critical knowledge about a system depends on so few people that their departure makes it disappear. A set of ADRs turns that fragile memory into an artifact that survives turnover, and it is often the first thing an outside engineer looks for when assessing whether an inherited architecture is still justified or needs to be rebuilt.

An enterprise example

An Italian manufacturing company needs to decide whether to extend its order-management system with a new traceability module, which requires heavy writes to a relational database that is already under load. The current team does not know why, five years earlier, that relational database was chosen instead of a document-oriented store, which fits the module's data more naturally. Two hypotheses are plausible: it was a real technical constraint, for instance the need for ACID transactions across orders and payments, or it was a convenience choice by the team at the time, no longer binding today. Without an ADR that settles it, the company has only two options, both costly: redo the analysis from scratch, paying in time and outside consulting for a decision already made once, or extend on top of a constraint that may no longer exist, piling technical debt on a foundation nobody can justify anymore. An original ADR would have made the choice verifiable in an afternoon instead of weeks.

Why it matters for decision-makers

An architecture decision record costs little to write, one page, at the moment the decision is fresh and the person making it holds the full context in their head; it costs enormously to reconstruct later, once that context is scattered among people who have left or forgotten it. For anyone evaluating the acquisition of a project, or signing off on a build vs buy decision on an existing system, the presence or absence of ADRs is a direct signal of how much hidden technical debt is being bought along with the code. It is also a matter of code ownership: a team that writes ADRs spreads architectural knowledge instead of concentrating it in one or two people, which is exactly what lowers the bus factor on a system that must keep evolving even after whoever designed it changes roles or leaves.