Architecture Decision Records have been a known practice in software engineering since Michael Nygard described them in 2011. The format is simple: a short document capturing the context, the decision made, and the consequences. Simple enough that teams adopt it. Not quite simple enough that teams stick to it.
ADRs are often presented as a solved problem. They're not. The gap between "team has an ADR template" and "team consistently produces useful decision records" is where most documentation initiatives quietly fail. Understanding why ADRs break down in practice — and what alternatives have emerged — is more useful than the template itself.
The classic ADR format and where it breaks down
The canonical ADR structure, typically stored as numbered Markdown files in a /docs/decisions/ directory, looks like:
- Title — ADR-0042: Use event sourcing for order state
- Status — Proposed / Accepted / Deprecated / Superseded
- Context — what problem this was solving and what constraints existed
- Decision — what was decided
- Consequences — what becomes easier, harder, or different as a result
This structure is sound. The failure modes are operational, not structural:
Write-time friction. ADRs are written after the decision is made, as a documentation step. That step competes with shipping. For teams with active sprint cycles and no explicit time allocated to decision documentation, ADRs become backlog items that never get prioritized.
Disconnection from the decision moment. The discussion that produced the decision happened in Slack, a Notion doc, a Loom recording, or a combination. The ADR is a summary. A significant portion of the original context — the specific alternatives that were considered, the arguments that moved people, the edge cases that were explicitly deferred — doesn't survive the summarization. Someone reading the ADR six months later gets the conclusion, not the reasoning.
No search layer. ADRs in a /docs/decisions/ directory are discoverable by filename and manual navigation. Engineers asking questions like "what database choices did we make and why?" are not well-served by a directory listing of 80 numbered Markdown files.
Lightweight decision logs: the Notion page pattern
Teams frustrated with the ADR friction often migrate to a Notion database — typically a table with columns for Decision, Date, Owner, Status, and Tags. This is lower friction to write. It's also lower structure, which creates problems over time.
The Notion decision table degrades through a predictable lifecycle. Initial enthusiasm produces detailed entries with full context. Over time, entries get shorter. The "Context" field starts arriving as a single sentence. Tags become inconsistent. Cross-references to related decisions don't happen because Notion's relational links require manual setup.
The Notion pattern is worth using, especially for early-stage teams. We're not arguing against it. The point is: it requires ongoing maintenance discipline that most teams can't sustain at velocity. The decision log becomes a reflection of team energy rather than a complete record of team decisions.
Scenario: the ADR audit at a growing infrastructure team
A backend platform team at a growing infrastructure SaaS company adopted ADRs early and maintained them diligently for their first year. By the end of year two, they had 73 ADRs covering major architectural decisions. When a new staff engineer joined and reviewed the directory, she found three categories of quality:
- ADRs 1–30: written during the period when the founding team had time and energy for careful documentation. Full context, alternatives documented, consequences detailed. Genuinely useful.
- ADRs 31–55: written during a high-growth period. Context fields sparse or absent. Decisions documented but reasoning largely absent. Partially useful.
- ADRs 56–73: written during sprint crunch periods. Some are single-paragraph summaries with no alternatives documented. Some are placeholders ("to be completed"). Several decisions that occurred during this period have no ADR at all.
The ADR directory exists. It has a non-trivial completeness problem that nobody noticed until someone audited it. The decisions weren't less important in periods 2 and 3 — they were often more important, as the architecture was handling higher scale. They were just less documented.
What patterns actually hold over time
The decision log patterns with the best long-term durability share two properties: low write-time friction and strong connection to the decision context. These goals are somewhat in tension, but the following approaches get the balance better than standard ADRs:
Decision signals in native async surfaces. Rather than requiring engineers to write documentation in a separate tool, effective patterns capture decisions in the tool where the decision happened. A Slack thread that resolves a significant architectural question gets tagged or bookmarked with a structured label. A Notion document's "Decision" section gets linked to an index. The write step happens at the moment of decision, not after. This significantly improves capture rate.
Mandatory alternatives section. The alternatives section is the hardest part to write and the most valuable part to read. Teams that make alternatives documentation non-optional — even a brief "we considered X and Y; X won because Z" — produce decision records that remain useful far longer than records with only the conclusion. The alternatives section is where the context that would change your mind lives.
Status tracking with explicit supersession links. An ADR marked "Accepted" from two years ago might represent a decision that was reversed last month in a thread. Without a status update and a link to the superseding decision, it's actively misleading. The superseded status plus a link to the new decision is the minimum viable update. Teams that treat decision records as immutable once written create a documentation layer that gradually diverges from reality.
Retrieval by question, not by number. The ADR numbering convention is useful for versioning and reference. It's not useful for discovery. An engineer asking "why did we pick gRPC?" is not going to browse through numbered files. Decision logs need a question-based retrieval path — either via search tooling that can map natural language questions to relevant records, or via a tagging taxonomy expressive enough to group related decisions by concern rather than by date.
ADRs as living records, not filing artifacts
The most useful framing for decision logs isn't "documentation we produce." It's "institutional memory infrastructure we maintain." That distinction changes what happens when a decision needs updating. In a filing model, you create ADR-0074 that supersedes ADR-0042. In a living record model, you update ADR-0042's status, add the new decision, and link the original context to the changed context so the full arc of the decision is visible.
Both approaches are valid; they serve different retrieval patterns. The filing model is better for audit trails. The living record model is better for onboarding and for understanding the current state without reading the full decision history.
What's worse than either approach is inconsistency — teams that sometimes create superseding records and sometimes update existing ones, producing a decision corpus where you can't tell whether any given record represents current practice or historical artifact.
Taxonomy: what decisions actually warrant an ADR
One reason ADR practices degrade is ambiguity about scope. Teams that try to document every decision produce too much noise. Teams that document only "major" decisions produce too many gaps, because "major" is defined inconsistently and tends to expand over time as the team forgets what seemed major at the time.
A more operationalizable criterion: document any decision where the cost of a new engineer misunderstanding the intent exceeds 30 minutes of explanation. That covers:
- Technology selection with non-obvious rationale (why this library over the standard alternative, what we tried first)
- Service boundary definitions and the constraints they imply for future evolution
- Performance or reliability tradeoffs explicitly accepted (the decision to tolerate eventual consistency in X in exchange for Y)
- Security posture choices that constrain implementation options (why we don't use JWTs in a particular flow)
- Explicitly rejected options that engineers will likely propose again
This criterion deliberately excludes: tactical implementation choices with obvious rationale, configuration decisions with standard defaults, decisions that are trivially reversible. The ADR system is for decisions where the context matters — where getting the context wrong has real consequences.
The format matters less than the consistency. A team with imperfect ADRs maintained consistently will have better decision retrieval than a team with perfect ADRs maintained sporadically. Infrastructure decisions don't need perfect documentation. They need documentation that exists and can be found when someone needs it — three months from now, when the engineer who made the call is heads-down on something else.