How do you record and govern architecturally significant decisions so they remain useful and revisitable years later?

## Why record at all The expensive loss is not the decision, it is the **reasoning**. Two years later a team meets a strange constraint, cannot find why it exists, and either cargo-cults it forever or removes it and reintroduces the original problem. Recording rationale is what makes an architecture revisitable instead of archaeological. ## Architecture Decision Records (ADRs) Popularised by Michael Nygard, an ADR is a short document, numbered sequentially, stored in the repository so it versions with the code: - **Title** — short and decision-shaped ("Use optimistic concurrency for order updates"). - **Status** — proposed / accepted / deprecated / superseded by ADR-0042. - **Context** — the forces: prioritised quality scenarios, constraints, current state, deadline pressure. This section ages best. - **Decision** — stated in active voice: "We will ...". - **Options considered and rejected**, each with why. A record with one option is a rationalisation. - **Consequences** — both directions: what becomes easier, what becomes harder, and explicitly **which quality attribute was sacrificed**. - **Assumptions and revisit triggers** — "valid while write volume stays below X", "revisit if we add a second region." Without this, nobody knows when the decision expired. **Immutability matters.** You do not edit an accepted ADR; you write a new one that supersedes it. The chain of superseded records is the architecture's reasoning history. ## Which decisions get a record Exactly the significant ones — the same filter as everywhere else: expensive to reverse, broad impact, quality-attribute sensitive. Recording everything produces an unread archive; recording nothing produces folklore. A practical trigger set: anything that changes a module boundary, a stored data shape, an external contract, a cross-cutting mechanism (auth, tenancy, error semantics), or the runtime topology. ## Governance models - **Central approval board**: consistent, but becomes a queue, distances deciders from consequences, and gets routed around under delivery pressure. - **Architecture advice process** (Andrew Harmel-Law): anyone may make a decision, but must first seek advice from everyone meaningfully affected and from people with relevant expertise; the decider keeps the decision and must record it. This scales with the organisation, keeps decisions near context, and preserves the knowledge flow a board would provide — but it depends absolutely on records being written and visible. - **Architecture guild / review forum**: periodic, opt-in discussion of the significant queue — useful for cross-team coherence without becoming a gate. ## Making records enforceable Documents drift from reality. Pair each durable constraint with an automated **fitness function**: - module and dependency rules that fail the build on a forbidden import - contract tests that fail when a published schema breaks compatibility - performance budgets asserted in CI or in load tests - chaos or failover exercises verifying an availability claim - policy and configuration checks for security rules The record states the intent and the reasoning; the fitness function keeps it true. ## Common failures - **Write-only archive**: records exist but nothing references them. Fix by linking from code and design docs, and by citing the relevant record in review discussions. - **Decision without consequences**: the most useful half is missing; nobody learns what it cost. - **Editing history**: mutating old records erases why the previous answer was reasonable, which is exactly what a future reader needs. - **No expiry thinking**: assumptions silently lapse (traffic 10x, a second region, a new regulation) and a once-sound non-risk becomes a risk with no trigger to notice. - **Gate theatre**: heavy approval for everything, so teams stop bringing decisions forward and significant choices are made invisibly.