Architecture Decision Record (ADR)

An architecture decision record captures why a system or organization is built the way it is. Each record covers a single decision, such as choosing a database, adopting an integration pattern or standardizing on a cloud provider. It explains the situation at the time, the options that were considered, what was decided and what the decision means for the future. Because each record is short, teams can write one in minutes and read one in less time.

The format was popularized by Michael Nygard in a 2011 article and has since been widely adopted by software and architecture teams. Its value becomes clear months or years later, when someone asks why a choice was made. Without a record, the reasoning is often lost, and teams either repeat old debates or reverse decisions without understanding their purpose. For enterprise architecture and IT finance, ADRs make the reasoning behind costly technology choices visible and easier to revisit when circumstances change.

Definition of Architecture Decision Record

An architecture decision record is a structured document describing an architecturally significant decision, meaning one that affects the structure, quality, cost or risk of a system or set of systems. A collection of ADRs forms a decision log for a system or organization.

ADRs are used by solution architects, enterprise architects and engineering teams, and they are often required by an architecture review board as part of its governance process. They are a standard part of solution architecture documentation in many organizations.

Typical Structure

The title names the decision briefly, and a status records whether it is proposed, accepted, superseded or deprecated.

The context describes the situation and forces that led to the decision, such as requirements, constraints, costs and risks.

The decision states clearly what was chosen. The options section, included in many templates, lists the alternatives considered and why they were not selected.

The consequences describe what follows from the decision, including benefits, drawbacks, costs and any new work it creates.

What Makes a Decision Worth Recording

Decisions that are hard to reverse, such as choosing a core platform or data store, are strong candidates for an ADR. These decisions often outlast the people who made them by many years.

Decisions with significant cost or risk, or that deviate from organizational standards, should also be recorded.

Decisions that affect several teams or systems benefit from a record, since many people will need to understand them. Routine choices with little lasting effect do not need one.

Importance of Architecture Decision Records in Enterprise Architecture

ADRs preserve knowledge. When team members leave or systems change hands, the reasoning behind important choices remains available.

They improve decision quality. Writing down the context, options and consequences encourages teams to think through trade-offs before committing. Reviewers can see what was considered and challenge assumptions while the decision can still be changed.

They also support governance and audit, providing a clear trail of how and why significant technology decisions were made. Regulated organizations often need to show that important technology decisions considered risk and compliance.

Linking Decisions to Costs

Many long-term technology costs are set by individual decisions, such as choosing a platform, licensing model or integration approach.

Recording the expected costs and benefits in the ADR, including total cost of ownership where relevant, makes it possible to compare expectations with actual results later.

When costs or conditions change, such as a vendor raising prices or a new service becoming available, ADRs show which decisions rested on the old assumptions and may need revisiting.

Exceptions to standards recorded as ADRs can carry review dates, so that temporary deviations are revisited rather than becoming permanent.

Common Challenges

Teams may skip ADRs under deadline pressure. Keeping the template short and making records part of normal design work helps. A record of a few paragraphs is far more useful than no record at all.

Records stored in hard-to-find places are rarely read. Keeping them alongside code or in a shared architecture repository improves their use. Search and consistent naming make a large decision log practical to use.

Records that are never updated can mislead. When a decision is reversed or replaced, the original ADR should be marked as superseded and linked to the new one.