architecture-decision-records

An architecture decision record (ADR) captures what was decided, why, and the consequences for future maintainers. You should write an ADR when a technical decision is hard or expensive to reverse, such as choosing service boundaries or deployment topology.

To document system design trade-offs, use a standardized ADR template covering Context, Decision, Consequences, and Alternatives. This structure emphasizes negative and operational trade-offs alongside real alternatives to ensure future maintainers understand the accepted compromises.

An RFC represents a discussion proposal, whereas an ADR documents a decided outcome. ADRs capture the final architectural decision and its consequences after the RFC discussion phase concludes, distinguishing exploration from committed system design choices.

You do not update an architecture decision record in place. Instead, use supersession chains to link a new ADR that overrides the previous one, enforcing correct lifecycle handling and preserving the original context for future reference.

Technical decisions that should be documented using an ADR template include service boundaries, message bus choices, data model approaches, and deployment topology. These high-impact architectural forks require durable records to prevent recurring confusion.

You do not need specific tools to start writing architecture decision records. The process relies on a standardized template covering Context, Decision, Consequences, and Alternatives, which can be applied to standard software documentation workflows.