Archietecture Decision Record (ADR)

An Architecture Decision Record (ADR) is a short document that describes a team decision that influences the software architecture they are building.

The result is a collection of approved, rejected or superseded ADRs in a decision log. It includes the decision but also its context and consequences.

Any team member who identifies a decision like that should create an ADR. Templates can simplify ADR creation and ensure it captures all the relevant information. The team member who completes an ADR is also its owner and is responsible for maintaining and communicating its content.

In the beginning, the ADR owner provides an ADR in the “proposed” state, which means it is ready for review. Then, the owner arranges a team meeting to review and decide if the ADR is accepted, requested for rework, or rejected. If the team finds that the ADR needs improvement, it preserves the “proposed” state, and the owner and other team members work on the refinements. Otherwise, the ADR status changes to “accepted” or “rejected,” and the ADR becomes immutable. If the team needs to update that decision, the team should propose a new ADR, and when this ADR is accepted, it supersedes the previous.

By embracing ADRs, a team can improve architectural decision-making and avoid repetitive discussions about the same topics.