Architecture Decision Records in 2026: ADRs That Stick

Architecture Decision Records are the most-recommended, least-maintained engineering artifact in modern software practice. Every consultancy, every staff engineer writing a tech blog, every senior architect at a sufficiently-large company recommends them. The reality at most organizations: a folder with 12 ADRs from 2021, three from 2022, none after that. The intent was good; the discipline never persisted. By 2026 the patterns that distinguish surviving ADR practices from abandoned ones are clearer.

This post walks through what actually works.

Why most ADR practices fail#

The typical pattern: a senior engineer reads Michael Nygard’s 2011 post or watches a conference talk, introduces ADRs to the team, writes the first few, and momentum dies within months. The failure modes are consistent.

ADRs are written for an imagined future reader who never shows up. Engineers spend hours crafting beautiful ADRs that no one reads. The cost-benefit calculation breaks down — the writer pays the cost, future readers theoretically benefit, but the future readers rarely actually consult the ADR when making decisions.

ADRs become disconnected from the code. The ADR says one thing; the code does another. When the divergence is discovered, no one updates the ADR. Over time the ADRs become misleading rather than helpful.

The format itself is over-engineered. Templates with 12 sections discourage writing. Engineers default to brief comments in PRs instead.

There’s no review process. ADRs get written, merged, and forgotten. There’s no checkpoint where someone validates that the decision was sound and the rationale captured what mattered.

The patterns that produce surviving ADR practices#

The teams that maintain ADRs successfully share specific patterns.

Short, opinionated format. The successful ADRs are typically under 500 words. They state the decision, the alternatives considered, and the consequences. They skip the elaborate template sections that don’t add value for their specific context.

Co-located with code. ADRs live in the repository they describe, not in a separate wiki. They’re versioned with the code they document. Changes to the architecture require changes to the ADR in the same PR.

Required for substantial changes. The team has a clear definition of what requires an ADR — typically anything that affects multiple teams, anything that changes a public interface, anything that introduces a new technology, anything that’s hard to reverse. This list is short and specific.

Reviewed like code. ADRs go through PR review with the same rigor as code. Senior engineers read them; questions get asked; the decision is sharpened by the review.

Linked to the work. Every substantial PR that implements a decision links back to the ADR. Code comments reference ADRs for context. The ADR becomes part of the navigable graph of the codebase rather than a separate document.

Updated when superseded. When a decision is replaced, the original ADR is updated with a clear “superseded by ADR-NNN” link. The history is preserved; the current state is clear.

The template that works#

Through multiple client engagements, we’ve converged on a minimal template:

• Status (proposed, accepted, deprecated, superseded by ADR-NNN)
• Context (2-3 sentences on what problem we’re solving)
• Decision (1-2 sentences on what we decided)
• Alternatives (the options considered and why rejected)
• Consequences (what becomes easier, harder, or impossible)

That’s it. No “stakeholders” section, no “implementation notes,” no “rollout plan.” Those belong in other documents.

The tools#

Most teams don’t need dedicated ADR tooling. A docs/adr/ folder with numbered markdown files works. Some teams use Log4brains for richer browsing; others use Backstage’s ADR plugin. The tool matters less than the discipline.

When ADRs aren’t worth it#

For small teams (under 10 engineers), single-product startups, or short-lived prototypes, ADRs are usually over-engineering. The communication overhead exceeds the benefit. Standups, design docs, and Slack threads do the same work with less ceremony.

ADRs earn their place when teams scale, when context loss starts to hurt, when the same decision gets re-litigated annually because no one remembers why the original choice was made.

Where pdpspectra fits#

Our architecture practice builds documentation discipline into client engagements. ADRs are part of how we hand off long-running work — every substantial decision recorded, every alternative considered, every consequence captured. The team owns the practice after we leave.

Related reading: the platform engineering post, the technical debt triage post, and the engineering knowledge transfer post.

---

ADRs work when the format respects the writer. Talk to our team about your documentation practice.