Architecture Decision Records: Making Decisions Explicit and Traceable

Every software system embeds hundreds of decisions. Most are invisible: implicit in the code, undocumented, and known only to the engineers who made them — who may have left the team years ago. When someone asks "why did we build it this way?", the honest answer is usually "we don't know anymore." Architecture Decision Records (ADRs) are the remedy.

What Makes a Good ADR

The canonical ADR template has five fields: Title, Status, Context, Decision, and Consequences. The most neglected field is Context: the constraints and forces in play when the decision was made. Without context, a decision looks arbitrary. With context, it's understandable — even if circumstances have since changed and the decision should be revisited.

We add two fields to the standard template: Alternatives Considered and Date of Next Review. Alternatives shows the decision was deliberate, not accidental. The review date forces re-evaluation of decisions that were correct for their time but may no longer be optimal.

ADRs in Git: The Only Workflow That Scales

ADRs stored in Git alongside the code they describe have several advantages over wiki-based alternatives: they're versioned, they appear in pull request reviews, they're searchable with standard tools, and they decay at the same rate as the code (a deleted service takes its ADRs with it). We use the adr-tools CLI or Backstage's ADR plugin for ADR lifecycle management.

The most important ADR practice is requiring new ADRs for significant changes in PRs. An architectural decision that's made without documentation is a decision that the next person will have to reverse-engineer from the code.