Decision records your successor will thank you for

Code shows what was built. It almost never shows why the other option was rejected. Six months later someone proposes the rejected option again, and the argument happens twice.

Context, options considered, decision, consequences. Keep it to a page. Date it. Give it a number. Never edit an accepted record; supersede it with a new one so the history stays honest.

# ADR-014 Tenancy enforced in the database
Status: accepted
Context: a query bug must never leak one tenant's rows to another.
Decision: row-level security on every table; the app never filters by tenant itself.
Consequences: slower local setup; migrations need a policy per table.

Next to the code, in the same repository, in plain text. Not in a wiki nobody opens. The record should be one click from the thing it decided.