Architecture decision record

What it means

An architecture decision record, or ADR, preserves why a team chose a design, what alternatives it considered, and what consequences it accepts. ADRs reduce the need to reconstruct intent from code and make later reversals more deliberate. They work best when linked to the affected boundary and kept current enough to explain the decision.

Example

A team chooses asynchronous events for order processing because consumers can retry independently. The ADR records ordering limits, operational costs, and the reason a synchronous design was rejected.

Limitations

An ADR is not a substitute for implementation documentation, testing, or stakeholder alignment. Too many trivial records create noise, while stale records create false confidence. Mark superseded decisions clearly.

How to use the signal

Weave can connect architecture changes to the pull requests that implement them and to later rework. Store the ADR in the team’s documentation system and use Weave’s history to see how the decision affected delivery.