The artefact engineers fill in to record an architectural decision — recognising that the ADR's title precision, status lifecycle, context articulation, decision specificity, consequence enumeration (intended outcomes and accepted trade-offs), and reference anchoring are what determine whether the document accumulates as institutional memory the team can navigate years later or as historical noise that doesn't help anyone.
This page is about the template — the specific structured document an engineer fills in when recording an architectural decision: what fields the document has, what each field is for, what good content in each field looks like, and how the document evolves through its lifecycle. The discipline of how ADRs work as governance instruments — when ADRs are required, who reviews them, how they integrate with the team's decision-making process, what authority they carry — lives in governance/ at section level. Same family, different operational concern: this page owns the artefact; governance owns the meta-discipline.
A primitive ADR is what gets written when "we should document this decision somewhere": a free-form paragraph in a wiki, an email thread that nobody can find later, a code comment, a Slack message. The decision was made; some record exists; the team that needs to understand the rationale six months later can't, because the record is unstructured, uncategorised, and unfindable. The decision becomes folklore, then gets forgotten, then gets re-litigated when someone proposes the alternative the team had originally rejected for reasons nobody now remembers.
A production ADR is a designed document with structured fields. Its title captures the decision precisely (not "database choice" but "Adopt PostgreSQL with logical replication for the order-management transaction store") so that the title alone is sufficient to retrieve the right ADR years later. Its status is tracked through a documented lifecycle: Proposed → Accepted → Deprecated → Superseded; the status is not metadata but a primary field, and lifecycle transitions are themselves recorded with date and reason. Its context articulates the forces in play — the constraints, requirements, trade-off space, and current state that made this decision necessary — so a reader years later can understand why the decision was needed at all. Its decision states what was chosen in active voice and at sufficient specificity to be verifiable ("we will use X with configuration Y" not "X seems good"). Its consequences enumerate both the intended outcomes the decision was supposed to produce and the accepted trade-offs (what becomes harder, what risks were knowingly taken, what alternatives were foreclosed). Its references anchor the decision in evidence: what alternatives were evaluated, what was prototyped, what research informed the choice. Each field has a defined purpose; what fills each field is calibrated to that purpose.
The architectural shift is not "we have ADRs." It is: the ADR is a designed document whose title precision, status lifecycle, context articulation, decision specificity, consequence enumeration, and reference anchoring determine whether the team's accumulated decisions form a navigable institutional memory or an undifferentiated archive of past meetings — and treating ADRs as free-form prose produces a corpus that doesn't help future decisions.
The ADR's title is the highest-leverage field in the document. It's what appears in the index, in the search results, in the cross-reference; it's what a reader uses to decide whether to open the document. A title like "Database choice" tells future readers nothing about what was decided or why this ADR is the right one to read. A title like "Adopt PostgreSQL with logical replication for the order-management transaction store" tells future readers (a) what was decided, (b) which subsystem the decision concerns, and (c) what specific configuration was adopted. The architectural discipline is to write titles that are self-contained statements of the decision — verb-phrased, specific, and contextualised. The rule is operational: a reader should be able to determine from the title alone whether this is the ADR they're looking for, without opening the document.
Pick five recent ADRs from your organisation. Reading only the titles, can you determine what each decided? If multiple titles are vague nouns ("Caching", "Authentication", "Logging") rather than specific decisions, the corpus has lost the searchability that titles are supposed to provide — and finding the right ADR among many requires opening each one.
Documenting Architecture Decisions (Nygard) is the seminal articulation of ADR practice; title discipline is treated alongside the other structural elements. MADR — Markdown ADRs provides a standardised template format including title conventions.
A primitive ADR has no status field — it exists or it doesn't, and the reader has to infer whether the decision is still current. A production ADR carries its status as a primary field, with the status drawn from a small documented vocabulary: Proposed (the decision is under review and not yet binding); Accepted (the decision is binding; the team is implementing or has implemented it); Deprecated (the decision is no longer the team's preferred approach but no replacement has been chosen); Superseded by ADR-NNN (the decision has been replaced by a specific newer decision; the link is in the status itself). Lifecycle transitions are recorded with date and reason — the document accumulates its own history. The discipline pays compound returns: a reader looking at any ADR can immediately see whether the decision still applies, whether it's been replaced, and what replaced it.
Pick the oldest ADR in your organisation. What's its status, and how was that status established — by an explicit transition with date and reason, or implicitly because the document hasn't been touched in years? If the status isn't explicit, readers can't tell whether the decision still applies, and the corpus stops being a current reference and starts being an archaeological record.
ADR Tools (npryce) operationalises lifecycle management at command-line level, with adr supersede as a primary operation. MADR — Markdown ADRs provides the canonical status vocabulary used across most ADR practice.
The decision section says what was chosen; the context section says why the decision was needed at all. A reader years later approaching the ADR has lost the surrounding situation: the constraints that applied at the time, the requirements that drove the choice, the trade-off space the team was navigating, the state of the system that made this decision relevant. Without context, the decision looks arbitrary — and the temptation is to second-guess it ("why didn't they just use X?") because the considerations that ruled X out are no longer visible. The architectural discipline is to write context that captures the forces: requirements, constraints, current state, alternatives considered, and the trade-off space those alternatives spanned. Context isn't autobiography; it's the situational frame that makes the decision intelligible to a reader who wasn't there.
Pick a recent ADR in your organisation. Reading only its context section, can you understand why this decision was needed? Could you defend the chosen option against an alternative without already knowing the answer? If the context reads as a narrative of what was done rather than as a frame for the decision, the document is documentation but not reasoning — and a future reader will have to reconstruct the reasoning themselves.
Y Statements (Zalando) treats context articulation as a primary discipline, with the canonical "In the context of [scope], facing [concern], we decided for [option] and against [alternatives] to achieve [quality], accepting [downside]." Building Evolutionary Architectures (Ford et al.) covers context-driven architectural decision-making at framework level.
A decision sentence that reads "X seems like the right approach" or "we should consider X" hasn't actually decided anything — it's still ruminating. A decision sentence that reads "We will use X" with sufficient specifics is a decision a future reader can verify against the system: did the team actually use X? Did they configure it as stated? The architectural discipline is active voice and verifiable specificity: "We will" / "We are adopting" / "We have chosen" rather than "It would be good to" / "The team should consider"; specifics that name the actual technology, the actual configuration, the actual scope ("for new microservices in the orders bounded context, effective on the next release") rather than gestures at intent ("we'll use modern messaging").
Pick a recent Accepted ADR. Quote its decision sentence. Is it active voice? Is it specific enough that you could verify whether the system follows the decision? If the answer is "we decided to consider adopting X" or similar hedging, the document is not yet binding — and what's been recorded is a discussion, not a decision.
Documenting Architecture Decisions (Nygard) treats the active-voice discipline as central to ADR practice. Y Statements (Zalando) makes the active-voice requirement explicit in its template grammar.
A decision section that lists only the benefits is incomplete — it elides the costs the team accepted in making the choice. A consequences section that says only "this will improve performance" hides the trade-offs the future reader might inherit. The architectural discipline is to enumerate both sides: the intended outcomes the decision was made to produce (what becomes possible, what's fixed, what improves) AND the accepted trade-offs (what becomes harder, what alternatives were foreclosed, what risks were knowingly taken, what costs the team is paying for the chosen approach). Future readers benefit doubly: they see why the decision was good, and they see what it cost — which is the information they need to know whether the trade-offs the original team accepted still apply.
Pick a recent ADR. Are the consequences both-sided — intended benefits AND accepted trade-offs — or only the benefits? If only the benefits are listed, the document is selling the decision rather than recording it. The next time the team revisits this ADR (because something the trade-offs implied has now become a problem), the trade-offs will have to be reconstructed from memory.
Y Statements (Zalando) explicitly requires both-sided consequence statements ("achieving [quality], accepting [downside]") in its grammar. Building Evolutionary Architectures (Ford et al.) treats trade-off acknowledgement as central to architectural discipline.
A decision presented without supporting references is a decision presented as opinion. A decision anchored in references — links to the alternatives that were evaluated, the prototype results that informed the choice, the research papers or vendor documentation consulted, the prior ADRs whose decisions this builds on — is a decision presented as the conclusion of an investigation. The architectural discipline is reference anchoring: every ADR ends with explicit links to (a) the alternatives that were considered (with brief notes on why each was rejected); (b) any prototyping or benchmarking results that informed the choice; (c) the canonical sources for the chosen approach (vendor docs, research papers, established practice references); (d) related prior ADRs and the cross-references between them. The references make the ADR's reasoning checkable — a future reader can re-examine the evidence and decide whether the original conclusion still holds.
Pick a recent ADR. Does its references section list the alternatives considered (with rejection reasons), prototyping results, canonical sources, and related ADRs? If references are sparse or absent, the decision is presented without its supporting evidence — and a future reader has to take the chosen conclusion on the original team's authority rather than examining the evidence themselves.
ADR Examples (joelparkerhenderson) is a curated collection of ADR examples; reference-anchoring discipline varies across them, with the highest-quality examples following the discipline above. Diátaxis Documentation Framework provides the broader documentation philosophy that underpins reference-anchoring (technical documents are checkable artefacts, not authoritative pronouncements).
The diagram below shows the canonical ADR lifecycle as a state machine: a Proposed ADR is under review and not yet binding; transitions to Accepted when the team commits to the decision; may transition to Deprecated when the team no longer prefers the approach but no replacement is identified; transitions to Superseded by a specific newer ADR when a replacement is chosen. Each transition records date and reason; the document accumulates its own history.
Titles like "Caching" or "Database choice" tell future readers nothing about what was decided. Searching the corpus produces ambiguous results; opening each ADR to find the right one is the only way.
Verb-phrased decisions, specific to the subsystem, with distinguishing detail. The title alone should be sufficient to determine if this is the ADR the reader needs.
A reader encounters an old ADR. Is it still binding? Was it replaced? Was the decision quietly walked back? The document doesn't say.
Status as a primary field with a documented vocabulary (Proposed / Accepted / Deprecated / Superseded). Lifecycle transitions recorded with date and reason. Bidirectional cross-references between superseded and superseding ADRs.
The ADR records what was decided but not why the decision was needed. Future readers second-guess the choice because the considerations that ruled out alternatives aren't visible.
Context section captures requirements, constraints, current state, and the trade-off space of alternatives. The decision is intelligible to a reader who wasn't in the original discussion.
"It would be good to use X" / "We should consider X" / "The team is evaluating X." The decision section reads like discussion, not commitment. The status says Accepted, but nothing was actually decided.
Active voice and verifiable specificity. "We will use X with configuration Y, applying to scope Z, effective from V." If hedging language is necessary, the ADR should be in Proposed status, not Accepted.
The consequences section lists what the decision will achieve. The trade-offs the team accepted aren't documented. When the trade-offs surface later as problems, the team has to reconstruct what was knowingly accepted versus what was overlooked.
Two-sided consequences: Intended Outcomes and Accepted Trade-offs. Trade-offs explicit and named; risks knowingly taken acknowledged; operational implications forecasted.
"Adopt X with Y for Z" rather than "X" or "Database choice." A reader can determine from the title alone whether this is the ADR they need.
Proposed / Accepted / Deprecated / Superseded by ADR-NNN. Status is visible immediately, not buried in metadata.
Each status change appends to the document's history. The ADR's full lifecycle is visible without external state.
Superseded ADRs link forward to their successors; successors link back to what they replaced. The corpus is navigable by following these links.
A reader who wasn't in the original discussion can understand why the decision was needed and what considerations applied.
"We will adopt X with Y, applying to Z, effective from V." Specifics are calibrated to the decision's stakes. Hedging language signals the decision isn't yet made.
Trade-offs explicit and named, not euphemistic. Risks knowingly taken acknowledged. Operational implications forecasted.
Not "we considered X, Y, Z" but per-alternative rejection rationale. Future readers can re-examine why alternatives were ruled out.
Spike branches, benchmark results, vendor documentation, research papers. The decision's evidence base is recoverable.
The template is itself an ADR or governance artefact. New ADRs follow the same structure. The corpus is consistent across time and authors.
Other substantive pages in the library that link here: