Architecture Decision Records

Important technical decisions often outlive the meeting, ticket, and people who made them. The implementation shows what exists. It rarely preserves the constraints, alternatives, and trade-offs that shaped the choice.

An architecture decision record, or ADR, is a short document about one significant decision. It states the context, the decision, its status, and its consequences. A collection of ADRs forms a decision log.

The point is not paperwork. The point is durable reasoning. A future teammate should be able to see why the team chose a direction and whether the original context still applies.

The mental model: a decision with memory

Treat an ADR as a durable link between a problem and its outcome:

context and forces
        |
        v
considered options -> decision -> consequences
                         |
                         v
                implementation evidence
                         |
                         v
              keep, revise, or supersede

The decision is central. Context explains the conditions around it. Consequences describe the new conditions created by it. Later evidence tells you whether the choice still fits.

This structure prevents two expensive reactions to old decisions. You do not have to accept a choice without understanding it. You also do not have to reverse it without knowing what requirement it protected.

Decide what deserves an ADR

Not every choice is architectural. Record a choice when it materially affects the system or constrains later work.

The original ADR guidance identifies five useful areas:

Structure — major decomposition or architecture patterns.
Quality attributes — security, availability, performance, fault tolerance, and other system qualities.
Dependencies — coupling among components, services, or external systems.
Interfaces — APIs, events, schemas, and published contracts.
Construction techniques — consequential frameworks, tools, and engineering processes.

Reversal cost is another useful test. A local naming choice is cheap to change. A data ownership boundary, authentication model, or public API can shape years of work.

Skip the ADR when a choice is trivial, local, or easy to reverse. Recording every implementation detail buries the decisions people need to find.

Use one record for one decision

An ADR describes one significant decision for one context. This keeps each record focused and lets later records refer to it precisely.

A decision such as “Use PostgreSQL for transactional account data” can stand alone. “Choose the entire application architecture” hides many decisions about data, deployment, boundaries, interfaces, and operations. Split that bundle into records that can change independently.

The resulting decision log becomes a map of architectural reasoning. The title list gives a quick orientation. Each record provides the detail behind one choice.

Start with a small core template

Michael Nygard's original format uses five parts.

Title

Name the choice with a short phrase. A specific title makes the decision log scannable.

Use asynchronous events for order status changes

Status

State where the record sits in its lifecycle. Common values include proposed, accepted, rejected, deprecated, and superseded.

Status names are a team convention. Define them once. Use them consistently.

Context

Describe the forces at play before the decision. Include the requirements, constraints, risks, and tensions that make the choice necessary.

Keep the language factual. Do not write the context so the preferred option appears inevitable. A reader should understand the problem before seeing the answer.

Decision

State the chosen response in active, unambiguous language. Define its scope. A reader should know what the team will do and where the decision applies.

We will publish order status changes as versioned domain events.

Consequences

Describe the context after the decision takes effect. Include benefits, costs, risks, and follow-up work. A consequence can be positive, negative, or neutral. Omitting an inconvenient cost removes the trade-off that made the record useful.

Add detail only when it improves the decision

The core template is enough for many teams. A richer template can expose reasoning that otherwise stays hidden.

Markdown Architectural Decision Records, or MADR, adds structured sections for decision drivers, considered options, the decision outcome, consequences, confirmation, and detailed pros and cons. It also supports metadata such as decision makers and consulted or informed people.

Use those fields when they answer real review questions:

Decision drivers identify the criteria that separate the options.
Considered options show the credible alternatives.
Pros and cons make the comparison inspectable.
Confirmation defines how you will check implementation or compliance.
Related decisions connect dependencies and superseding records.

Do not fill every optional field because a template contains it. Template weight should match decision weight.

Run a visible lifecycle

An ADR is both a record and a stateful work item.

identify -> propose -> review -> accept or reject -> implement -> confirm
                                      |
                                      v
                                later evidence
                                      |
                                      v
                                  supersede

Identify a significant question and an owner.
Draft the context before the answer hardens.
Record credible options and their trade-offs.
Mark the ADR as proposed and invite affected people to review it.
Rework, accept, or reject it according to the team's decision process.
Connect the accepted decision to implementation and review evidence.
Supersede it with a new ADR when later context requires a different choice.

AWS guidance recommends preserving accepted ADRs. If a decision changes, create a new record and link it to the superseded record. The old record remains useful because it explains the system's history.

Do not silently rewrite an accepted ADR to make history look clean. Update minor errors according to your team policy, but represent a changed decision as a new decision.

Separate the record from the approval process

An ADR format does not decide who holds authority. One team may use consensus. Another may assign the decision to a service owner. A regulated environment may require formal approval.

Define the process around the record:

Who may propose an ADR?
Who owns the decision?
Who must be consulted?
Who accepts or rejects it?
Which status transitions are allowed?
Which evidence confirms implementation?
Which events trigger review?

AWS guidance allows any team member to create an ADR while assigning clear ownership for maintenance and communication. The principle is broader than one workflow: make participation and authority explicit.

Put the decision log where people work

The original format places lightweight text files in the project repository. Thoughtworks also recommends source control so decisions can change with the code. AWS guidance presents both a Git repository and a wiki as common central locations.

Choose based on the people who must read and change the records.

Location	Strength	Risk to manage
Repository	Versioning, review beside code, stable links	Non-developers may have less access
Wiki	Broad access and familiar editing	Decisions can drift away from implementation
The medium matters less than three properties: the log is central, accessible, and versioned. Link it from the project's main documentation. Make titles and statuses searchable.

Write for the future reader

A useful ADR gives a future teammate enough information to evaluate the choice without replaying the original meeting.

Make context testable

Replace vague claims with specific forces.

Weak:  The new design must scale.
Better: Checkout must continue accepting orders during the agreed peak load.

Record assumptions as assumptions. Link measurements, policies, prototypes, or incidents when they shaped the decision.

Compare credible options

An option exists only if the team could reasonably choose it. Include “do nothing” when retaining the current state is realistic. Apply the same drivers to every option.

State the decision precisely

Name the selected option, scope, owner, and important boundaries. Avoid language that leaves adoption optional after acceptance.

Preserve all significant consequences

List gains and costs. Include migration work, operational burden, new dependencies, security effects, and limits on future choices when they apply.

Define confirmation

An accepted record does not enforce itself. Link the decision to code review checks, architecture tests, configuration policy, operational evidence, or another suitable control.

Know the limits

An ADR preserves reasoning. It does not prove that the reasoning is correct.

The record captures what the team knew at a point in time. Requirements can change. Evidence can break an assumption. A dependency can become unsuitable. Supersession is normal maintenance, not an admission that recording the first decision failed.

An ADR also does not fix non-compliant code. AWS guidance treats that as separate work. Teams still need implementation tasks, reviews, tests, and remediation plans.

Finally, a decision log can fail through neglect. Too many low-value records create noise. Missing links hide replacement decisions. Inaccessible storage removes the audience. Unowned records become stale. Keep the process small enough to sustain.

A practical adoption sequence

Select one template and define status meanings.
Choose a central, versioned location.
Record one current, consequential decision.
Review the context, options, decision, and all known consequences.
Accept or reject it through the team's existing authority model.
Link the accepted ADR from related code and documentation.
Add confirmation through review, tests, policy, or operational evidence.
Build the decision log one significant choice at a time.
Supersede records instead of rewriting changed decisions.
Periodically check ownership, links, status, and continuing relevance.