An architectural decision record (ADR) is a document that describes a choice the team makes about a significant aspect of the software architecture theyβre building. Each ADR describes the technical decision, its context, and its consequences. ADRs often describe cross cutting concerns which will impact the project as a whole.
The ADR process outputs a collection of architectural decision records. This collection creates the decision log. The decision log provides the project context as well as detailed implementation and design information. Project members skim the headlines of each ADR to get an overview of the project context. They read the ADRs to dive deep into project implementations and design choices.
When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR.