Docs & Code Guide

Keep ADRs up to date: records are immutable, statuses are not

Keeping ADRs up to date does not mean editing them; an architecture decision record is a dated account of a choice, and rewriting it destroys the only thing it is for. What goes stale in an ADR log is the metadata: a record still marked accepted after the team decided otherwise, and an index that no longer tells a newcomer which decisions describe the present. Maintenance here is status transitions and one honest index, plus a current-state view kept separate from the history.

Try it free
6 min readFor teams with forty ADRs and no idea which ones still apply

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

180/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why you never edit an ADR

An ADR answers a question no other document can: what did we know, and what did we choose, at that moment. Its value is precisely that it does not track the present. The engineer who finds ADR 12 three years later needs the original context, the alternatives considered, and the trade-offs as they looked then, because that is what explains the system's shape. Edit the record to match today and you have destroyed the evidence while keeping the number.

So the update operation on an ADR log is never "fix the old record". It is "write a new record and change the old one's status". The content is append-only; the metadata is mutable. That split is what makes ADRs the easiest documentation to keep honest, and most teams still get it backwards by treating old ADRs as pages to revise.

Statuses are the sync surface

The canonical lifecycle is small: proposed, accepted, then eventually deprecated or superseded by a specific newer record. Staleness in an ADR log is exactly one thing: a status that no longer reflects the team's actual position. A record marked accepted whose decision was quietly reversed in a meeting is a lie with a timestamp, and it costs real money when a new team builds on it.

Two habits keep statuses true. First, supersession is part of deciding, not a cleanup chore: the pull request that adds the new ADR also flips the old one's status, in the same review. Second, the index gets a periodic pass, quarterly is plenty, asking one question per accepted record: is this still how we operate? Ten minutes with the log beats archaeology during an incident.

Tooling: adr-tools and log4brains

adr-tools is the minimal, battle-tested option: shell commands that create numbered Markdown records and handle supersession links on both sides in one step. log4brains adds a web UI and builds the log into a static site with statuses visible, which turns the index from a file you maintain into a page that renders itself.

# adr-tools
adr init doc/adr
adr new "Move invoice exports to the event bus"
adr new -s 12 "Replace the nightly batch with streaming"
#   creates the new record AND stamps ADR 12 "Superseded by" in one step
adr generate toc > doc/adr/README.md   # regenerate the index

# log4brains: the log as a browsable static site
npx log4brains init
log4brains adr new
log4brains build   # statuses and supersession links rendered per record

Pair the log with a current-state view

An ADR log answers why; it is deliberately bad at answering what is. A newcomer wanting the present system should not have to replay forty decisions and compute the result in their head. The pattern that works is pairing: the immutable log on one side, and a single regenerated current-state diagram on the other, linked from the top of the index.

That diagram is the half a machine can keep true. Generated in Datadef and shared public, it embeds by URL next to the ADR index and reflects edits within minutes; an AI agent connected to the Datadef MCP server can update it from the repository after merges, as a CI step or on request. Datadef does not watch the repo, and it has no role in the records themselves: the prose of each ADR is exactly the kind of human judgment that should never be generated. History stays hand-written and frozen; the present stays generated and current. The wider version of this split is the subject of keeping architecture docs in sync with code.

Limits of the metadata loop

Status discipline is unavoidably human: no tool knows a decision was reversed in a hallway conversation. The mechanics above make the flip cheap, adr-tools makes it one command, but someone still has to know it happened, which is why supersession belongs inside the deciding moment rather than after it. And the paired diagram needs a public project for live embeds; teams with confidential architecture keep the pairing but publish the current-state view as a re-exported image on a stated cadence. Who owns those two duties, statuses and the view, is a smaller version of the general question in documentation ownership models.

The one rule

Never edit an old ADR. Write a new one, flip the old status to superseded in the same pull request, and keep one regenerated current-state diagram linked from the index so history and reality never have to impersonate each other.

FAQ

How do I keep architecture decision records up to date?

You do not update the records; you update their metadata. ADRs are point-in-time documents and editing them destroys their value as history. When a decision changes, write a new ADR and flip the old one's status to superseded in the same pull request, then regenerate the index. Quarterly, scan all accepted records and ask whether each still reflects how the team operates.

What does superseded mean in an ADR?

That a later record replaced this decision. The superseded ADR is not deleted or edited: it keeps its original content as a historical account, gains a status line naming the newer record, and the newer record links back. Tools automate the two-sided link: adr new -s 12 creates the replacement and stamps ADR 12 as superseded in one command.

Should I ever edit an existing ADR?

Only for typos or broken links, never for meaning. The record documents what was known and decided at a specific time, which is what future readers need to understand why the system is shaped as it is. If reality changed, that is a new decision and therefore a new record with a supersession link, not a revision of the old one.

What tools help maintain an ADR log?

adr-tools provides shell commands for creating numbered records, superseding old ones with correct cross-links, and generating a table of contents. log4brains adds a local preview and builds the log into a static site where each record shows its status and supersession links. Both keep records as Markdown in the repository, so ADR changes travel through normal code review.

How do readers see the current architecture if ADRs are immutable?

Pair the log with one current-state diagram linked from the ADR index. The log explains why the system evolved; the diagram shows what exists now. The diagram is the regenerable half: kept in a tool like Datadef, embedded by URL so every copy follows edits within minutes, and updateable from the repository by an MCP-connected AI agent after merges.