Architecture Decision Records for real teams

Decisions need memory

Every system I have worked on carried decisions that nobody could explain anymore. Why does this service own that table? Why is authentication split across two components? Why did we reject the queue everyone now wants to introduce? The people who knew had left, the meeting notes were gone, and the chat thread was buried under two years of noise.

Architecture gets expensive exactly at this point. Not when the decision is made — when the context of the decision disappears. A team without decision memory re-litigates the same choices every few quarters, or worse, silently reverses them without knowing what constraint they are about to violate.

Good records do not replace judgment. They preserve enough context to make future judgment cheaper.

An Architecture Decision Record is the cheapest tool I know for this problem. It is a short document — one page, often less — that captures a single decision: what we chose, why, what we rejected, and what we accepted as the cost. The idea comes from Michael Nygard's 2011 essay, and it has survived because it is small enough to actually happen.

What goes wrong without records

The failure modes are predictable, and I have watched each of them play out in production organizations:

• Decision archaeology. A senior engineer spends two days reconstructing why a boundary exists before daring to change it. Multiply that by every significant change and you have a real tax on delivery.
• Silent reversal. A new team member "fixes" something that was a deliberate trade-off. The original constraint — a compliance requirement, a load characteristic, a vendor limitation — resurfaces as an incident.
• Meeting amnesia. The same architectural debate happens three times with three different outcomes, because nothing binds the previous conclusion to the codebase.
• Onboarding by folklore. New engineers learn the architecture from whoever happens to answer in chat, which means they learn a partial, sometimes wrong version of it.

None of these are documentation problems in the classic sense. A wiki full of stale architecture diagrams does not fix them. They are decision problems — and that is the scope an ADR should have, nothing more.

The useful shape

I keep ADRs deliberately small: context, decision, consequences, alternatives considered, and links to evidence. The goal is not ceremony. The goal is searchable team memory that survives personnel changes.

Status: accepted
Date: 2026-04-14
Context: services need tenant-aware authorization; a data leak between
         tenants is the highest-impact risk in the domain
Decision: enforce tenant checks in application services AND as
          database-level filters (defense in depth)
Alternatives: middleware-only checks (rejected: single point of failure),
              database-only RLS (rejected: opaque to code review)
Consequences: simpler review path, more explicit tests,
              less accidental data leakage, small per-query overhead

A few rules that keep the shape useful in practice:

• One decision per record. If you need "and" in the title, you probably need two records.
• Immutable once accepted. New information produces a new ADR that supersedes the old one — history stays intact.
• Alternatives get honest treatment. "We considered nothing else" is a signal, not a record.
• Consequences include the negative ones. A record that lists only benefits is marketing, not memory.

Writing ADRs people actually read

The common approach is to write ADRs like formal specifications: long, defensive, and complete. In my experience that guarantees they will not be read. What I actually do is write them like a message to a specific person — the engineer who, eighteen months from now, is staring at this boundary and wondering if it is safe to move.

That framing changes the writing. You stop documenting everything and start answering three questions: what constraint forced this decision, what would break if you reversed it, and what evidence we had at the time. If the future reader can answer "is this still true?" quickly, the record has done its job.

Length matters less than density. Some of the most useful records I have written are six sentences. The worst ones were three pages of hedging that committed to nothing.

A review rhythm that survives delivery

A record is useful only when it has a rhythm attached to it. The mistake I see most often: teams write ADRs during a documentation push, then never touch them again. Records without triggers rot exactly like code without tests.

I tie the rhythm to delivery events, not to the calendar. Calendar-based reviews get skipped under pressure; event-based reviews happen because the event forces the question anyway.

The pull request link is the highest-leverage habit in this table. It costs seconds, and it turns the ADR from a document into a living reference that reviewers actually encounter during normal work.

Tooling and placement

ADRs belong in the repository, next to the code they describe — docs/adr/ or docs/decisions/, plain Markdown, numbered sequentially. The reasoning is practical:

• They travel with the code through forks, migrations, and vendor changes. A wiki does not.
• They are searchable with the same tools engineers already use — grep, IDE search, code review UI.
• They can be reviewed like code. An ADR pull request is a design review with a written artifact at the end.
• Git history gives you authorship and dating for free.

Tooling beyond that is optional. adr-tools and similar CLIs are pleasant, but I have never seen an ADR practice fail because of missing tooling — and I have seen several fail because a heavyweight template made writing feel like filing taxes. Start with a Markdown file and a naming convention; add tools when the volume justifies them.

Anti-patterns that kill adoption

Most ADR initiatives do not fail loudly. They fade. These are the patterns I actively watch for:

• The retroactive archive. Someone documents forty historical decisions in one heroic sprint. The archive is impressive and immediately stale, and the team learns that ADRs are a project, not a habit.
• The approval gate. ADRs become a mandatory sign-off step with required reviewers and SLAs. Writing one now feels like bureaucracy, so engineers scope their work to avoid triggering it.
• The essay contest. Records grow past a page because thoroughness is mistaken for quality. Reading them becomes work; nobody does it.
• The private notebook. One architect writes excellent records that nobody else contributes to. When they leave, the practice leaves with them.

Production considerations

A few things that only show up after the practice has been running for a while:

• Superseding chains need hygiene. After a year you will have records that supersede records. Keep the links bidirectional — the old record points forward, the new one points back — or navigation degrades fast.
• Cross-repo decisions need a home. Decisions that span services (auth model, event schema conventions) belong in a platform-level repository, referenced from the affected services. Duplicating them guarantees drift.
• Incidents are your validation suite. The most honest question in any post-mortem is "which recorded assumption turned out to be false?" If the answer is never, either your system is remarkably stable or your records are too vague to be falsifiable.
• New joiners are your usability test. Ask engineers in their first month to read the ADR index and flag what they could not follow. Their confusion maps precisely to your missing context.

Summary

• ADRs solve a decision-memory problem, not a documentation problem — keep their scope that narrow.
• One page, one decision, honest alternatives, negative consequences included.
• Write for the engineer who will question this boundary in eighteen months.
• Tie reviews to delivery events — new boundaries, PRs, incidents, migrations — never to the calendar alone.
• Keep records in the repo as Markdown; add tooling only when volume demands it.
• Watch for ceremony: approval gates and essay-length records kill the practice quietly.