Skip to content

Architecture Decision Record

Architecture decision record — instantiates Layer-Appropriate Capability Placement

Records why a complexity-adding placement choice was accepted — the criterion applied, the host-dependency it commits to, and the conditions that would reopen it — so the decision is revisited on evidence, not relitigated from memory.

An Architecture Decision Record (ADR) is a short, dated, immutable note capturing a single load-bearing choice: where a capability was placed, why that layer over the alternatives, and what would make us look again. In this archetype its specific job is to make a placement decision — "we let the host own this, we built it locally, we delegated across the contract" — legible after the people who made it have moved on. Its defining move is that it is a record, not a gate: it does not test, enforce, or publish anything, and it is never edited once accepted — a reversal is a new ADR that supersedes the old one. That immutability is what turns a chat-thread consensus into an auditable trail, so a team can tell the difference between a constraint that was reasoned through and one that merely accreted.

Example

A mobile team is under pressure to run background sync every fifteen minutes. The platform (iOS, Android) throttles background execution hard, so the tempting move is to build a local scheduler that keeps a wake-lock alive and works around the host's limits. Instead they open an ADR. Context: the OS deliberately governs background wake-ups for battery reasons. Decision: delegate scheduling to the host's supported facility (BackgroundTasks / WorkManager) and accept coarser, host-decided timing rather than reconstruct a scheduler the layer was never meant to own. Criterion recorded: scheduling is an OS-level concern; the app layer cannot express battery/thermal policy, so it belongs to the host. Dependency recorded: we now depend on host scheduling semantics that vary by OS version — the accepted host-dependency budget. Reopen when: a product requirement genuinely needs sub-minute timing, or the host facility's variance breaks an SLA.

Eighteen months later a new engineer proposes the local-scheduler workaround again. The ADR answers in one read: it was considered, here is the criterion, here is what would have to change. The decision is reopened only if the recorded trigger has actually fired — not because the reasoning was forgotten.

How it works

What distinguishes an ADR from a design doc is its narrow, repeatable shape and its immutability:

  • One decision per record. Context → decision → the criterion that justified it → consequences (including the host-dependency accepted) → alternatives rejected and why → the condition that reopens it.
  • Dated and immutable. Accepted records are never rewritten; a change of mind is a new ADR marked supersedes #N, preserving the reasoning trail rather than erasing it.
  • Rejected alternatives are first-class. The "why not the local build" is recorded as deliberately as the "why the host" — that rejected branch is the part future readers most need.
  • Carries its own expiry cue. Each record names the evidence that would make it wrong, so revisiting is triggered by events, not by someone happening to remember.

Tuning parameters

  • Significance threshold — how consequential a choice must be to warrant an ADR. Set it low and the log drowns in trivia; set it high and the decisions that quietly shape the system go unrecorded.
  • Reopen-trigger bindingness — whether the "revisit when…" clause is advisory prose or a wired alert. Tighter binding keeps records live; looser leaves them to rot into write-only history.
  • Supersession discipline — whether reversals must cite the record they replace. Strict citation preserves lineage; lax supersession fragments the trail.
  • Storage locality — in-repo next to the code versus a central register. In-repo keeps the record beside what it governs; central aids cross-team discovery. The trade is discoverability against drift.

When it helps, and when it misleads

Its strength is institutional memory with a spine: it stops the same placement fight from being relitigated every two years, and it makes a load-bearing host-dependency a chosen, dated commitment rather than a silent assumption nobody can trace. Because each record names what would reopen it, it also gives drift a tripwire.

Its classic misuse is being written after the decision to manufacture a paper trail — an ADR run backwards to justify a choice already shipped, rather than to reason one through.[1] The other failure mode is the write-only log: records accumulate, reopen-triggers are never wired to anything, and the archive becomes archaeology instead of a live constraint. The discipline that guards against both is to author the record at the decision point, force the rejected alternatives to be stated honestly, and treat the reopen-trigger as a real condition the system watches — not decorative prose.

How it implements the components

An ADR realizes the decision-memory slice of the archetype — it records a placement choice, it does not test or publish one:

  • layer_placement_criterion — the record captures which criterion was applied ("this is a host-level concern") and the verdict it produced, so the placement rule that governed the choice is preserved, not just the outcome.
  • host_dependency_budget — it names the host-dependency the choice commits to and the ceiling on it, turning an implicit reliance into a recorded, bounded cost.

It does not run the live placement test — that is Layer-Placement Fitness Check — nor fire the revisit it merely schedules, which belongs to Capability-Promotion Review. It records inventory and ownership rather than maintaining them; that directory is the Capability Catalog.

Notes

An ADR has no teeth of its own — it records a decision but enforces nothing. Its reopen-triggers only bite if a review actually watches for them, which is why it pairs with Capability-Promotion Review: the ADR remembers the condition, the review is where the condition is checked.

References

[1] The lightweight, one-decision-per-file ADR format was popularized by Michael Nygard; its whole value proposition is capturing the rationale and rejected alternatives at decision time, which is precisely what a retroactively written record cannot honestly reconstruct. ↩