#ADR-0000: Record architecture decisions

• Status: accepted
• Date: 2026-07-07

#Context

We make architecturally significant decisions — choices that are costly to reverse or that shape how the system is built — and the reasoning behind them gets lost. New engineers inherit the "what" without the "why," which leads to blind acceptance or blind reversal.

#Decision

We will keep a lightweight Architecture Decision Record for each significant decision, following Michael Nygard's format (Context / Decision / Consequences). Records are numbered, immutable, and live in docs/adr/; only their status changes. The practice is documented in the Architecture chapter.

#Consequences

The rationale behind decisions is preserved and reviewable in git alongside the code. Writing a short record is a small tax on each significant decision; trivial or easily-reversed choices don't need one.