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.[n1] 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.
Also instantiates¶
Behavior-Preserving Refactoring — The placement facet uses the ADR to remember which layer should own a capability. Refactoring gives the ADR a different job: to memorialize a structure-only reorganization and, above all, to hold the line between changing internals and changing behavior. The dangerous move in refactoring is the silent waiver — a "cleanup" that quietly alters an error code, an audit event, or a timing assumption because no one explicitly decided to. An ADR authored at the decision point records the structural improvement sought, the internals in scope, and the standing rule that any intended behavior change must leave the refactor and go through its own path — turning "no behavior change intended" from an unverified assertion into a dated, auditable commitment.
structural_quality_target— the ADR states the improvement the restructuring is for (lower coupling, clearer ownership, safer extension), so cleanup is not endless aesthetic churn.internal_restructuring_scope— it names which internal structures may change, keeping a broad rewrite from being mislabeled a refactor.change_rationale_log— the immutable record captures the structural problem, the chosen transformation, and any newly discovered hidden contract, preserving the reasoning trail.behavior_change_escalation_path— it records the boundary that routes an intended behavior change into a separate feature or migration decision rather than smuggling it through structure-only review.
Complexity Budgeting — Complexity Budgeting treats every added feature, dependency, or layer as a spend against a scarce budget, and the ADR is its memory of a single such spend. The angle here is neither layer placement nor behavior preservation but cost accounting: a complexity-increasing choice was accepted, so the record captures what value justified it, what was rejected, and the condition under which the addition should be removed — making complexity a deliberate, revisitable purchase rather than silent accretion nobody can trace.
value_justification— the ADR records the benefit claimed for the added complexity or host-dependency, so "someone requested it" is replaced by a stated value.complexity_ledger— as a dated, immutable, one-decision entry it is the per-choice budget memory: accepted cost, owner, promised value, and review condition.exception_protocol— when a choice deliberately overruns the simplicity budget for a high-value reason, the ADR is where that overrun is made visible and reviewable rather than hidden.rollback_path— its reopen-trigger names the evidence or failure that would justify removing the addition, keeping the spend reversible.
Related¶
- Instantiates: Layer-Appropriate Capability Placement — the ADR is the archetype's durable record of why a capability landed at the layer it did.
- Consumes: Layer-Placement Fitness Check supplies the verdict an ADR memorializes when one was run.
- Sibling mechanisms: Capability-Promotion Review · Capability Catalog · Layer-Placement Fitness Check · Shadow-Platform Audit · Extension-Request Workflow · Platform Core / Extension Model
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: 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, making its operative form a durable account of actual events, decisions, or transitions whose value depends on history or provenance.
Independent corroboration: The frozen evidence defines Architecture Decision Record as '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', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Software architecture developed lightweight immutable ADRs recording context, decision, alternatives, consequences, and reopening conditions.
Related originating lineages:
- Engineering & Design — Configuration and design-decision records provide a broader precedent.
- Organizational & Management Science — Decision records preserve organizational rationale and ownership.
Review outcome: Independent reviewer agreement; high confidence.
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.
[n1] 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. ↩