Chapter 21 — Architectural Decisions

Core ideas

Anti-patterns to avoid: covering your assets (avoiding decisions for fear of being wrong), groundhog day (re-deciding the same thing because the why was never recorded), email-driven architecture (decisions get lost/unenforced).
Architecturally significant decisions: those affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
ADR — Architecture Decision Record: the core tool. Standard sections — Title, Status (proposed/accepted/superseded), Context, Decision (written assertively: “We will…”), Consequences (including the trade-offs and downsides), Compliance (how it’ll be governed, ideally a fitness function), Notes. ADRs operationalize the Second Law (“why over how”).

Lightweight documentation (ADRs) vs. heavyweight up-front docs. ADRs capture just the reasoning that outlives the decision.