An Architecture Decision Record (ADR) is a short, dated document that captures one significant technical decision: the context that forced a choice, the options considered, the decision made, and the consequences that follow. Kept together in the repository, a series of ADRs forms a chronological log of why a system is shaped the way it is.
The practice exists because the most expensive thing to lose about a codebase is not how it works but why it was built that way. Code shows the what; it rarely explains the trade-off that was weighed, the alternative that was rejected, or the constraint that made an obvious approach unworkable. Without that reasoning recorded, a later engineer — or an AI agent — is liable to "fix" something that was a deliberate decision and reintroduce the problem it was avoiding.
An ADR is most useful when it is anchored to the code it governs and surfaced before someone changes that area, so the decision is read at the moment it is about to be overridden rather than discovered afterward in a post-mortem. A decision recorded but never delivered to the person about to undo it is reasoning that may as well not exist.