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