Architecture Decision Records (ADR)

Each decision gets its own short, numbered file. These files are permanent. When a decision changes, you write a new file. The old file is marked Superseded by ADR-N. This is the only method here with a built-in way to show a decision has been replaced.

Docs-as-code · since 2011 Native supersession semantics Status field maintained by hand Reconciling links needs a reasoning model

What it is

Michael Nygard created ADRs in 2011. An ADR is a short file about one important technical decision. It explains the context, the decision, its status, and what happened next. The files are numbered and never change. “If a decision is reversed, we will keep the old one around, but mark it as superseded. It’s still relevant to know that it was the decision, but is no longer the decision.” (adr.github.io). All the ADRs together form the project's decision log.

Setup

Create a docs/adr/ folder in your repository. Add a template for new ADRs. Review them in pull requests.
Write ADR-0001 to record the decision to use ADRs. Tools like adr-tools can do this for you.
Use optional tools to help. adr new "Use X" creates the next file. adr new -s 9 "Use Y" creates a replacement and marks ADR-9 as superseded. Log4brains can publish your ADRs as a searchable site.
Decide when a decision needs an ADR. Enforce this rule during code review so people actually write them.

Sample directory structure

docs/adr/
├─ 0001-record-architecture-decisions.md   # meta-ADR   (Status: Accepted)
├─ 0002-use-postgresql-for-primary-store.md # Status: Accepted
├─ 0003-use-rest-for-public-api.md          # Status: Superseded by ADR-0008
├─ 0005-use-jwt-for-service-auth.md         # Status: Deprecated
├─ 0008-adopt-graphql-for-public-api.md     # Accepted (supersedes ADR-0003)
├─ template.md                              # blank template new ADRs copy
└─ README.md                                # generated index / table of contents

Each file contains the Status, Context, Decision, and Consequences. The file's content never changes. But the status field can change. Someone must update the status by hand when a decision is replaced. This is often where the process fails.

Pros & cons

Strengths

Built-in way to replace decisions. It clearly shows "this replaced that." You keep the old record, mark it superseded, and never reuse its number. Git history alone can't easily show if a decision is still active.
A permanent, dated record. Each ADR shows what was decided and why, with all the context from that moment.
Helps new people get up to speed. New hires can learn the why behind a decision, not just the what. This stops them from removing things without understanding the original reason.
No special tools needed. ADRs are just plain Markdown files in your repository. You can review them in pull requests and read them easily.

Weaknesses

They get stale. People write ADRs but then never read them again. Sprint deadlines take priority, so the records become outdated.
They become "write-only." You end up with a pile of records that no one ever reads.
The status field is not updated. When a decision changes, no one marks the old ADR as Superseded. This makes the decision log inaccurate.
Just going through the motions. It can become a bureaucratic task. Often, one person writes them after the decision has already been made.
Used inconsistently. Some teams in a company might use ADRs while others don't.
Hard for AI agents. Following a chain of Superseded → ADR-N links requires real reasoning. Weaker AI models can't do this.

Common user feedback

We found the best feedback in a Hacker News thread with 300 comments about ADRs. The quotes below are copied exactly. We also saw vendors complain that "nobody updates the status," but we didn't use their words as evidence, since they sell a solution.

They go stale and unread while the sprint never stops. “…architecture documents that are seldom read before they become stale. But make sure you also get your story points done for this sprint.” (HN).
“Write-only.” “…many records (which become essentially write-only as nobody will trawl through) or too few (which leave gaps).” (HN).
The key problem for an AI agent: the content can't change, but the status can. “the content should be treated as immutable. The metadata… is mutable — things like status, related ADRs, superseding PRs.” (HN) — and as others noted, this is the step that people often forget.
It can feel like pointless bureaucracy. “This is bureaucracy for bureaucracy’s sake… we just need good commit messages.” (HN).
Vendor claims don't always match reality. Log4brains says an ADR “is immutable — only its status can change — which means your documentation is never out-of-date” (Log4brains). But this is only true if someone remembers to update the status. The feedback above shows this often doesn't happen.

How it did in our benchmark

In our test, old ADRs were marked Superseded by ADR-N and new ones were Accepted. We also provided an index of the newest ADRs first. The score shows how many of the 6 facts the model got right.

condition	Opus 4.8	GPT-5.4 (reasoning)	GPT-4.1 (non-reasoning)
perfect maintenance	6/6	6/6	0/6
under lag (superseding ADR never written)	~4.7/6	~4/6	~4/6

ADR is the only method with a built-in way to show a decision has been replaced. A strong reasoning model scored a perfect 6/6. It correctly followed the links from a Superseded ADR to the new one. But this requires real reasoning. A model without strong reasoning (GPT-4.1) scored 0/6, even when the ADRs were perfectly updated. It read the files but couldn't follow the chain of changes. In a more realistic test, the superseding ADR was never written. The old record still read Accepted, and the score dropped to ~4/6. The system is good, but it's only as current as the people maintaining it. See the full results →

Part of the methods reference for the stale-context benchmark. Quotes are copied exactly from Hacker News and the original post by Nygard. We have noted any sources from vendors.