Architecture Decision Records

A short, durable document for each significant architecture decision that records its context, the decision made, the alternatives considered, and the consequences. ADRs are usually kept in version control alongside the code and are immutable: a superseded decision gets a new record, not an edit to the old one.

Why it Matters

The reasoning behind an architecture is the first thing lost as people move on, and without it teams relitigate settled questions or "fix" deliberate choices back into bugs. Capturing the why, the book's Second Law, makes decisions reviewable, teachable, and reversible with full knowledge of what they cost.

Signals

• "Why is it built this way?" with no one left who knows.
• The same architectural debate recurring every few months.
• Decisions living only in chat logs or one person's memory.

Benefits

Preserved rationale, faster onboarding, a defensible record of tradeoffs, and a way to revisit decisions deliberately when context changes.

Risks

Ceremony for trivial decisions; records written once and never consulted; editing history instead of superseding, which loses the trail of how thinking changed.

Tensions

Enough documentation to preserve rationale versus the overhead of writing and maintaining it; capturing only the decisions significant enough to be worth the cost is itself a judgment.

Examples

A record explaining why a system chose eventual consistency over strong consistency, what was given up, and when to revisit; a superseding record noting an earlier decision was reversed and why.