Architecture Decision Records: Decisions You Will Still Understand in Two Years
Why did we choose PostgreSQL back then and decide against the message bus? ADRs make the why durable as a versioned Markdown artifact – instead of letting it seep away in hallway talk.
Five sections are enough to make an architecture decision durable: Title, Status, Context, Decision, Consequences. Michael Nygard described this format in 2011 in his blog post “Documenting Architecture Decisions” and called it an Architecture Decision Record, ADR for short – a small, versioned text artifact that records exactly one decision together with its forces. One page of Markdown, nothing more.
Nygard states the motivation right in the first sentence: “One of the hardest things to track during the life of a project is the motivation behind certain decisions.” The what is in the code. The why is nowhere – or it’s buried in a Slack thread, a Confluence page nobody can find anymore, or in the head of someone who happens to be on vacation. The most expensive question in a project is therefore rarely “How do we build this?” but “Why did we actually build it this way back then?” A team takes over a system, runs into a strange decision – an unusual database, a homegrown cache, skipping the obvious message bus – and nobody can say whether it was intentional or an accident. The people who knew are long gone to the next project or the next company. What remains is code that executes a decision whose rationale has evaporated.
The outcome first: less archaeology, faster handovers#
Before I talk about format and tooling, I want to say what ADRs bring in practice – because that’s what this is about, not another documentation ritual. In the projects where I introduced ADRs, one thing in particular gets dramatically shorter: the time it takes a new team member to go from “I understand the code but not the logic behind it” to “I can take part in decisions here.” Onboarding turns from digging into reading up.
The second effect is subtler but more valuable. When a decision has to be written down, it also gets made more deliberately. While writing, you notice whether you really weighed alternatives or just took the first path that came along. The artifact doesn’t force more bureaucracy – it forces clarity. And clarity at the moment of decision is cheaper than any later reconstruction.
What matters to me here is the distinction Nygard makes himself: agile methods are not against documentation, they are against valueless documentation. The 80-page architecture handbook that’s outdated by the first commit is valueless. A one-page ADR that sits next to the code and travels with it through the Git history is not. ADRs are the lightweight compromise between “write nothing down” and “document everything to death.”
The format: five sections, one decision#
Nygard describes ADRs as “a format similar to an Alexandrian pattern” – a short text that describes a set of forces and records one decision in response to them. The format is deliberately minimal, and the brevity is not a shortcoming but the feature: small documents are more likely to be kept up to date than large ones.
This is what an ADR typically looks like for me. It lives as Markdown in the same repository as the code, under docs/adr/:
# 7. Use PostgreSQL as primary datastore
Date: 2021-03-12
## Status
Accepted <!-- proposed | accepted | superseded by ADR-0012 -->
## Context
The core service needs a transactional store. Expected load is
moderate (low thousands of writes per minute at peak). The team
has deep operational experience with PostgreSQL and none with
distributed NewSQL stores. Strong consistency is a hard requirement
for the billing path.
## Decision
We will use PostgreSQL as the primary datastore for the core service.
## Consequences
Positive: strong consistency, mature tooling, no learning curve for the team.
Negative: single-primary HA needs operational care; revisit this decision
if sustained write throughput exceeds ~5k writes/second.
The Context section is where the real value lies. It describes what Nygard calls the “balancing of forces” – the forces acting on the decision: expected load, team skills, consistency guarantees, cost. If you read this ADR two years from now, you don’t just see that PostgreSQL was chosen but under which assumptions. And – this is crucial – the Consequences section even names the condition under which the decision should be reevaluated. That’s not dogma; it’s a state of thinking, preserved.
One point here is often overlooked: the Context has to describe the world at the time of the decision, not the world of today. An ADR is a snapshot, not a living document. That leads directly to the most important principle.
Immutability: ADRs are never overwritten#
The most common mistake I see when teams try ADRs for the first time: they treat an ADR like a wiki page and update it when the decision changes. That destroys the whole point. An ADR is a log entry, not a state object.
The rule is: once an ADR has been accepted, its content is never changed again. If the decision changes, you write a new ADR that replaces the old one. The old one gets the status superseded and a reference to its successor. The numbering is sequential and never reused – 0001, 0002, 0003, even if 0002 is long outdated. What you get is a decision log: a complete history that shows which decision applied when and what replaced it.
docs/adr/ # sequential, zero-padded, never renumbered
0001-record-architecture-decisions.md
0002-use-markdown-for-adrs.md
0007-use-postgres-as-primary-datastore.md # Status: superseded by 0012
0012-switch-to-cockroachdb.md # Status: accepted
You can think of this lifecycle as a state diagram. An ADR moves from proposed to accepted – and at some point, maybe, to superseded, with the pointer referring to the following ADR:
stateDiagram-v2
[*] --> proposed
proposed --> accepted: PR merged
proposed --> rejected: not adopted
accepted --> superseded: replaced by newer ADR
superseded --> [*]: points to successor ADR
rejected --> [*]The charm of this is that the Git history and the ADR history run in parallel. Both live in the same repo, both travel through the same commits. When I check out an old commit, I see the ADRs that belonged to that state. The why travels through time with the code.
Hallway talk versus artifact#
To show what ADRs actually change, a simple contrast helps. On one side is the normal state of many teams: decisions are made in meetings, in chat threads, in passing at the coffee machine. They are real, they shape the architecture – but they can’t be found anywhere. On the other side is the versioned Markdown artifact that lives in the repo and is reviewed via the pull request.
flowchart LR
subgraph Flurfunk
A[Slack thread] --> X[lost knowledge]
B[whiteboard photo] --> X
C[hallway talk] --> X
D[someone's memory] --> X
end
subgraph Artefakt
E[ADR in docs/adr/] --> G[reviewed via PR]
G --> H[versioned with the code]
H --> I[readable in two years]
endThe difference is not that no decisions are made on the left. The same decisions are made. The difference is whether the rationale becomes an artifact or evaporates. And in the end, that’s a question of friction: as long as writing things down costs more than forgetting them, things get forgotten. ADRs work because they make writing down so cheap – one Markdown file, one commit, done – that it’s worth it.
Tooling: just enough not to get in the way#
You don’t need a tool for ADRs. A text file and Git are enough. Still, a bit of convention helps keep the numbering and the template consistent. Nat Pryce built adr-tools for this, a lean CLI you install via Homebrew:
# create a new, auto-numbered ADR from the standard template
$ adr new "Use PostgreSQL as primary datastore"
# -> docs/adr/0007-use-postgres-as-primary-datastore.md
# create an ADR that supersedes an earlier one
$ adr new -s 7 "Switch to CockroachDB"
# -> docs/adr/0012-switch-to-cockroachdb.md
# and sets ADR-0007 status to "superseded by 0012"
If you prefer a richer template, MADR – “Markdown Any Decision Records” – offers a more structured one that explicitly leaves room for the options that were weighed. To get started, though, I almost always recommend the bare five Nygard sections. You can refine later; it’s hard to introduce discipline after the fact.
The most effective lever isn’t a tool anyway but a process habit: an architecture-relevant change in a pull request only gets merged if the corresponding ADR is in the same PR. That makes the ADR part of the review. The decision isn’t just recorded but read by at least one other person at the same moment. The lonely “I just built something” becomes a deliberate, shared step.
By the way, that the format holds up is not a lone opinion. The ThoughtWorks Technology Radar placed “Lightweight Architecture Decision Records” in Adopt – the highest recommendation level – as early as November 2017. That’s no longer a novelty; it’s established practice.
Where ADRs tip over – the honest chapter#
ADRs don’t run themselves. They fail, and in three predictable ways.
The first failure mode: ADRs go stale anyway. If you don’t write them with discipline for every relevant decision, you get a history full of gaps. And a history full of gaps is more dangerous than none at all, because it pretends to be complete. If someone reads “these are our decisions” and the crucial one is missing, they draw wrong conclusions. They rely on a log that lies – not by saying something false, but by leaving something out. Discipline beats tooling, always. No CLI and no template replaces the simple habit of pausing briefly at the moment of decision and recording it.
The second failure mode: too big, too late. As soon as ADRs swell into design documents, the update rate drops, and Nygard’s whole point – brevity – is lost. Post-hoc ADRs are especially treacherous, that is, rationales you hand in weeks after the decision. They only rationalize instead of capturing the real forces. You then no longer write down why you decided but why the decision looks good in hindsight. That’s self-deception in Markdown – and it’s hard to spot, because a cleanly worded ADR looks convincing regardless of whether it captures the real forces or just builds a pretty facade in front of them.
The third failure mode: the wrong granularity. Without a defined trigger, one of two things happens. Either every trifle becomes an ADR, and the signal drowns in noise. Or nobody knows what “architecture-relevant” means, and nothing gets written at all. A rough threshold, agreed on early in the team, helps: an ADR is written when a decision is hard to reverse, affects several teams or deliberately rejects an obvious alternative. Everything else is a comment in the code, not an ADR. This threshold may stay fuzzy; more important than the exact line is that the team shares any common idea of it at all.
One more thought that lifts ADRs beyond pure documentation: if you take the condition in the Consequences section seriously – “revisit if write throughput exceeds 5k/s” – you can make it verifiable. In Building Evolutionary Architecture, Ford, Parsons and Kua call these fitness functions: automated checks that measure an architectural property. An ADR documents the decision; a Fitness Function watches over whether its assumption still holds. Together, they turn a dead document into a living guardian.
Conclusion#
ADRs don’t solve a technical problem. They solve a memory problem – and in the long run, memory problems are more expensive than technical ones because they accrue interest. Every undocumented decision turns into a small debt over time: at some point, someone has to laboriously reconstruct what could have been written down in five minutes.
The core is unspectacular and precisely for that reason durable: in my convention, an accepted text stays unchanged; a new decision replaces it with a reference to the old ADR. That way, context, decision and consequences stay versioned next to the code and reviewable via the pull request. This doesn’t need a new system, just the discipline to record the why while it’s still fresh.
The easiest start is the first ADR itself – the one that records that from now on, ADRs will be written. 0001-record-architecture-decisions.md. Everything else follows once the habit is in place. And in two years, someone will read it whom nobody on the team knows today.
Further reading#
- Michael Nygard, “Documenting Architecture Decisions” (Cognitect, 2011): https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html
- Martin Fowler, bliki “Architecture Decision Record”: https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
- ThoughtWorks Technology Radar, “Lightweight Architecture Decision Records” (Adopt, Nov 2017): https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
- adr.github.io – community collection on ADRs and tooling: https://adr.github.io/
Revised and translated from German with the help of AI.