Transparent Communication with Architecture Decision Records for Software Teams

ADRs capture a set of forces and the single decision that responds to them.

ADRs are brief documents that outline a team’s decision about the software architecture they are developing. They contain not only the decision itself but also its context and consequences.

It is important to note that the term “architecture” should not be taken or interpreted. Any team member who identifies such a decision should create an ADR.

ADR templates can make this process easier and ensure all relevant information is included.

The ADR owner is responsible for maintaining and communicating its content. They initially provide the ADR in a “proposed” state for review. The owner then arranges a team meeting to discuss and decide whether to accept, request rework, or reject the ADR.

If the decision is accepted or rejected, the ADR becomes immutable. If the team needs to update the decision, they must propose a new ADR. If accepted, the new ADR supersedes the previous one.

The decision is central, meaning specific forces may appear in many ADRs. Each ADR is numbered and has a short noun phrase title.

The Decision section outlines the response to these forces, which may be marked as “proposed” or “accepted.” If a later ADR changes or reverses a decision, it may be marked as “deprecated” or “superseded” on its replacement.

We aim to keep each ADR to one or two pages, with complete sentences organized into paragraphs.

Bullets are acceptable only for visual style, not to excuse sentence fragments. Each ADR should describe one significant decision for a specific project that will affect how the rest of the project runs. The consequences of each ADR will likely become the context for the next ADRs.

Teams should follow a process for adopting and reviewing ADRs, resulting in a log of approved, rejected, or superseded ADRs.