Architecture Decision Records (ADRs)

9.6.1Definition

An Architecture Decision Record is a short, structured document capturing a single significant technical decision — the context, the options considered, the choice made, and the reasoning behind it — at the time it's made, rather than reconstructed from memory later.

9.6.2Why It Exists

Significant architecture decisions (7.10, 9.2, 9.3) are often revisited months or years later by people who weren't present for the original discussion, who then either repeat the same analysis from scratch or, worse, reverse a decision without understanding why it was made that way originally. ADRs exist to preserve that reasoning permanently and cheaply, at the moment it's freshest and clearest.

9.6.3Anatomy of an ADR

• Context — what problem or situation prompted this decision.
• Options considered — the realistic alternatives that were evaluated, not just the one chosen.
• Decision — what was actually chosen.
• Consequences — the known trade-offs accepted by making this choice.

9.6.4Common Mistakes

• No ADRs at all for significant decisions, leaving future teams to reverse-engineer reasoning from code and commit history alone (7.1).
• ADRs recorded well after the decision, when the original reasoning and rejected alternatives have already been partly forgotten.
• ADRs that record only the decision, not the alternatives considered, losing the context needed to judge whether circumstances have since changed enough to revisit it.

9.6.5Best Practices

• Write an ADR at the time a significant decision is made, not retroactively.
• Record the alternatives seriously considered, not just the final choice, to preserve the full reasoning.
• Store ADRs alongside the codebase (7.3) so they're discoverable by anyone working on the system later.