Keeping architecture decision records (ADRs) up to date — does anyone actually succeed at this?

The trick is to make ADRs lightweight — one paragraph max, stored next to the code they affect. We put them in the repo as .adr files and link them in PR descriptions. When a decision changes, you add a superseded note to the old one and create a new ADR. No one maintains 47 ADRs — but 10-12 active ones are manageable.

We solved this by making ADR updates automatic — when a PR changes architecture, the CI checks if an ADR exists for the affected component. If not, it blocks the merge. This creates just-in-time documentation instead of expecting people to remember to update ADRs after the fact.

Unpopular opinion: maybe ADRs are not supposed to be kept up to date. They are a record of what you decided at a point in time, not a living document. If the decision changes, you write a new ADR that supersedes the old one. Trying to keep the original ADR current defeats the purpose — you lose the audit trail of how your thinking evolved. We treat ADRs like git commits: immutable, sequential, and linked to each other.