What makes an architecture decision record valuable two years later, and which parts do teams consistently omit?

What the future reader actually needs

Someone encountering the decision two years later is asking one of two questions: "why is it like this?" or "can I change it?"

Both are answered by the context and the constraints at the time, not by the decision itself — which is usually evident from the code. The decision is the least valuable part of an ADR and receives the most space.

The parts consistently omitted

• The alternatives that were rejected, and why. Without this, the future reader cannot tell whether an option was considered and rejected for a good reason or simply never occurred to anyone — and that distinction determines whether it is safe to revisit. This is the single most valuable section and the most frequently missing.
• The constraints that were operative at the time: the team's size and skills, the deadline, the existing systems, the budget, what the organisation knew. Most decisions that look wrong later were correct under constraints that have since disappeared, and without the record the successor concludes their predecessors were foolish.
• The assumptions, especially the load, scale and usage assumptions. These are what should be checked first when revisiting, and they are frequently the only thing that has actually changed.
• What would make this the wrong decision — the trigger conditions for revisiting. An ADR with a stated trigger converts a decision into a monitorable position, which is a substantial improvement over a snapshot.
• The consequences accepted, including the negative ones, which is what stops the same trade-off being re-argued repeatedly.
• Who decided and who was consulted, so the future reader knows whom to ask.

What to leave out

• Extended background available elsewhere.
• Implementation detail, which changes and makes the record stale.
• Advocacy. An ADR arguing for its own decision is less useful than one stating the trade honestly — and a decision recorded with its downsides is more credible and more revisable.

The properties that make them survive

• Short. One or two pages. A long ADR is not written, and a very long one is not read.
• Immutable, with superseding rather than editing. The history of decisions is itself informative, and editing destroys it.
• Stored with the code, versioned alongside it, so it is found by someone working in that area rather than requiring them to know it exists.
• Written at the moment of decision, since the context is unrecoverable a month later — the reasoning that felt obvious is exactly what is forgotten.
• Numbered and indexed, so they can be referenced.
• Written for significant decisions only. An ADR for every choice produces a corpus nobody reads, and the test is whether the decision is expensive to reverse or affects more than one team.

The reframing

An ADR is not documentation of the architecture; it is documentation of the reasoning. The architecture is visible in the system. The reasoning exists only in people's heads and leaves when they do — which is the entire justification for the practice, and the reason a record without its alternatives and constraints is almost worthless.