How to Write an Architecture Decision Record Engineers Actually Read

Architecture Decision Records exist to solve a recurring and expensive problem: six months after a significant technical decision was made, nobody remembers why it was made, the person who made it has left, and the team is either relitigating it or making a downstream decision that conflicts with it. ADRs are the solution. The problem is that most ADRs are either never written or written in a format that nobody reads.

"An ADR that nobody reads is worse than no ADR. It creates false confidence that decisions are documented while the actual institutional knowledge lives only in the heads of engineers who were in the room. The test of an ADR is not whether it was written — it is whether someone six months later can understand why the decision was made without asking anyone."

— Michael Nygard, Author of Release It! and architect at Cognitect, on architectural documentation practices (2022)

The minimal ADR format that works

The classic ADR format from Michael Nygard is short and effective: Status (proposed, accepted, deprecated, superseded), Context (what is the problem we were solving and what were the constraints), Decision (what we decided to do), and Consequences (what becomes easier and what becomes harder as a result).

The Consequences section is the most important and most neglected. Every architectural decision involves tradeoffs. If your ADR does not document what you gave up, it is incomplete. A future engineer reading an ADR about why you chose eventual consistency needs to know that you accepted degraded read latency for distributed consistency, or they will spend time optimizing for something you explicitly decided to deprioritize.

Context vs decision: the most common confusion

The context section explains the situation that made a decision necessary. It should be readable by someone who was not in the room. What system properties were you trying to achieve? What constraints existed? What alternatives were considered and discarded before reaching the decision point? A common mistake is conflating context with decision rationale. The context section should explain the problem space; the decision section should explain the chosen solution and the primary reasons for choosing it over alternatives.

When to write one vs skip it

Write an ADR for decisions that are hard to reverse, affect multiple teams or system boundaries, involve explicit tradeoffs you want to document, or are likely to be revisited. Adding a new dependency, choosing a database, defining a public API schema, adopting a new architectural pattern: these warrant ADRs. Skip the ADR for implementation choices within a single component, for decisions that are easily reversible, and for conventions that belong in a coding standards document.

Where they live and how they stay relevant

ADRs belong in the repository, not in Confluence or Notion. Documentation that lives outside the code drifts. ADRs stored as numbered markdown files in a docs/decisions directory are versioned alongside the code, searchable, and visible in code review when a change relates to an existing decision.

ADRs should be updated when they are superseded, not deleted. Mark the status as "superseded by ADR-0042" and leave the original in place. Future engineers need to understand the sequence of decisions to understand the current state. Review existing ADRs as part of your architecture review process once a quarter and flag any that may need revisiting based on changed constraints, new options, or system evolution.

📊By the numbers