Architecture decision records
Why is it like this?
Two years from now, a new teammate notices Shard Garden saves gardens every 30 seconds, not after every move. Is that a bug?
Michael Nygard, a software architect, named the two bad choices a newcomer has: "Blindly accept the decision" or "Blindly change it." An architecture decision record (ADR) is a short note that records one decision and why it was made.
Five parts
Nygard's 2011 format has five parts:
- TitleA short name, like "ADR 7: Save gardens every 30 seconds".
- ContextThe facts at the time: costs, limits, deadlines.
- DecisionWhat we will do, in full sentences: "We will..."
- StatusProposed, accepted, deprecated or superseded.
- ConsequencesWhat happens because of it, the good and the bad.
Quick check
Which part of an ADR says what got worse because of the decision?
- Consequences
- Context
- Title
Show the answer
Consequences
Nygard says consequences list every result of the decision, including the negative ones, not just the benefits.
Where they live
ADRs live in the repo, next to the code, as Markdown files: doc/arch/adr-007.md. They are numbered in order, and a number is never reused. Each is one or two pages.
When the team changes its mind, the old ADR is not deleted. It is marked superseded and points to the new one, so the history stays readable.
Quick check
When a decision is reversed, the team deletes the old ADR so nobody is confused.
- True
- False
Show the answer
False
The old record is kept and marked superseded, pointing to the new one. Knowing why the team once chose differently is useful.
Fix the record
1# ADR 7: Save every 30 s2 3Status: Accepted4 5Context: Each save is one6database write. Saving7every move cost 4 times8our budget in a playtest.9 10Decision: Saving every1130 seconds is better.
Remy reviews this ADR. What is missing?
- A full "We will..." decision, and the Consequences part
- A number in the title
- The cost in the Context
Show the answer
A full "We will..." decision, and the Consequences part
Nygard wants the decision as a full sentence, "We will save each garden every 30 seconds", and a Consequences part, such as "a crash can lose up to 30 seconds of play".
Small and many
ADRs work because they are short. One design doc can lead to several ADRs, one per decision, each easy to find later by its number and title.
Remy asks Claude Opus 5.5 to draft ADR 8 from the design doc's discussion. Remy then checks that every fact in the Context is true before marking it accepted.
Next up: time
The documents say what Shard Garden is. The next question every publisher asks is how long it will take.
Bolt says: Next: estimates, and why even skilled guesses are wrong.
Fact-checked 12 October 2026
- Michael Nygard: Documenting Architecture Decisions cognitect.com