Why this matters
Superseding preserves decision history and enables accurate audits.
Do not rewrite accepted ADRs. When reversing or replacing a decision, create a new ADR with Status: accepted and add 'Supersedes: NNNN' while marking the old ADR as 'Status: superseded by NNNN'.
Superseding preserves decision history and enables accurate audits.
Side-by-side examples engineers can pattern-match during review.
Edit 0003-choose-mysql.md to say 'We chose Postgres' (history lost).# docs/adr/0012-switch-to-postgres.md
Status: accepted
Supersedes: 0003
# docs/adr/0003-choose-mysql.md
Status: superseded by 0012Supersedes: 0003Edited prior ADR content to new decisionFrom the same buckets as this rule.
For changes that affect architecture, data models, external APIs, security posture, deployment topology, or cost (>10%), create an ADR in docs/adr/ using the standard template (Context, Decision, Consequences) and link the PR and issue IDs.