Every engineering organization runs on a library of answered questions, and most of them are oral. Why does the payment flow bypass the cache, because of the idempotency incident of two years ago. Why is the search on a separate cluster, because the main database locked during the reindex one Black Friday. Why does no one use the new framework's flagship feature, because the team that tried it rolled back after a week, for reasons a senior engineer remembers partially and a departing engineer remembers completely. The oral library fails exactly when it is needed, when the people who hold it have moved on and the next team is about to reopen the decision with nothing but the code's silence to inform them. Architecture decision records are the written library, small structured documents that capture a decision, its context and its consequences, and this article builds the practice, the record format, the workflow that keeps records alive, and the failure modes that turn the library into a mausoleum.
The record format, small enough to actually write
The ADR that gets written is small, one page, and the format that survived the practice is the one Michael Nygard's original memo described, a handful of sections with plain names. Title and status, the status vocabulary being the practice's lifecycle, proposed, accepted, superseded by another record, and the superseding link being the format's quiet genius, decisions age visibly rather than silently. Context, the forces in play, the constraints, the problem that made a decision necessary, written as the situation at decision time rather than as history. Decision, the choice and the active voice that made it, we will use Redis streams for the event transport. Consequences, both sides, what the choice buys and what it costs, the honest section that separates the record from the announcement:
# ADR-012: Event transport on Redis Streams
Status: Accepted (2026-03-14), supersedes ADR-004
Context: The in-process event bus couples services to one deployment.
Kafka is operational overhead for ~4k msg/s. Team knows Redis.
Decision: We will use Redis Streams with consumer groups
as the cross-service event transport.
Consequences: Delivery is at-least-once; consumers must be idempotent.
Ordering is per stream, designed per ADR-013.
We take on stream monitoring and consumer lag dashboards.
Kafka remains a future option if throughput grows 10x.The modern templates, MADR and the variants, add a considered options section, the alternatives with their one line verdicts, and the options section is the second most valuable part after the context, because the team reopening the decision years later needs to know what was weighed, not just what won.
The workflow, records as pull request artifacts
The record that lives in the repository beside the code has a different survival rate than the record in the wiki, and the difference is the review workflow. The ADR is a pull request, written before or during the implementation it describes, reviewed by the same people who review the code, merged with it, versioned with it, and the code review can point at the record, this pull request implements ADR-012, the same way it points at a ticket. The record inside the repository is found by the people who need it, the engineer reading the event transport code finds the ADR file in the same tree, and the repository's search is the library's catalog:
docs/adr/0012-event-transport-redis-streams.mdThe workflow has three rules that keep it alive. Every decision with consequences gets a record, the threshold being the conference rule, would this decision take ten minutes to explain in a meeting, and the record is the explanation written once. The record is written before the code rather than after, because the context section is honest only at decision time, written after it becomes the victor's history. And the superseding is a link, the new record that replaces an old one names it, the old one is edited to point forward, and the library's timeline stays readable, ADR-004 through ADR-012 is a story a new engineer can follow through the transport decision's evolution.
What earns a record and what does not
The threshold question deserves its own discipline because the practice dies of both extremes. The record for every library version bump dies of noise, and the library is a hundred records nobody distinguishes from the commits. The record only for the grand decisions dies of silence, the important middle, the decisions that shape daily work without making the architecture diagram, goes unrecorded, and the oral library regrows in the gap. The working threshold is the consequence test, the decision that a future engineer could not infer from the code, the choice among real alternatives where the road not taken had advocates, and the record exists to preserve the why that the diff cannot carry.
The categories that earn records most reliably are worth naming for the team that calibrates its threshold. The data ones, storage choices, schema conventions, the consistency tradeoffs, because they outlast the code that made them. The integration ones, protocols, transports, the contract patterns, because they cross team boundaries and the reviewers are the other teams. The constraint ones, compliance boundaries, the regions and the data residency, the banned dependencies, because the context is regulatory and the code never says so. And the refusal ones, the proposal that was considered and declined, which are the records that prevent the yearly re-litigation, the pattern search experiment that is re-proposed every new hire because nobody wrote down that it was tried and what happened.
One record that paid for the whole practice
The refusal record deserves the concrete story because it is the practice's highest yield volume. The proposal arrives, as it does every eighteen months, to consolidate the reporting queries onto the primary database, the new engineer has benchmarked it, the numbers are convincing, and the one hour meeting to discuss it is on the calendar. The meeting that actually happens takes four minutes, because the search for the proposal's keywords finds ADR-007, reporting reads moved to the replica cluster, its context section describing the checkout lock incident, its consequences naming the lag the team accepted, and its decision section describing exactly the consolidation being proposed with the sentence the incident wrote, the reindex that locked the primary and the revenue hour it cost. The new engineer reads the record, asks two questions about what changed since, and the discussion moves to whether any of the forces differ, which is the productive version of the conversation the organization would otherwise have had for the third time.
The record saved the organization an investigation, a benchmark cycle and a debate, and the number that matters is the multiple, the record cost one page in one pull request and has now prevented two full re-litigations, with the third prevented in the four minute meeting. The teams that track their record libraries report the refusals as the most read volumes, because the proposals keep arriving with each new cohort, and the library is the only institutional memory that does not depend on the senior engineer being at the meeting.
Records, comments and runbooks, the boundary between the three
The practice finds its place beside two other writing disciplines, and the boundary is worth drawing because the wrong tool dilutes all three. The code comment explains the local, the non-obvious line, the workaround's trigger, and it travels with the line it explains, which is its strength and its limit, the comment cannot hold the decision's scope. The ADR holds the scope, the system level choice with its context and its consequences, and it lives in the repository's docs tree rather than in the code, because its readers arrive with a question, not with a cursor position. The runbook explains the operational, the procedure for a human, and it lives in the on-call path because its reader is in an incident, and the ADR that drifts into procedure territory becomes unreadable for both audiences.
The boundaries in practice, the cache bypass comment on the payment route stays a comment, the transport decision with its alternatives and its idempotency consequence is the record, and the consumer lag escalation procedure is the runbook that the record links to. The three reference each other, the ADR's consequences link the runbooks it created, the runbook's header links the record that explains why the procedure exists, and the reader is never more than one link from the full story, which is the documentation system this whole practice is assembling.
Scaling the practice across multiple teams
The single team's library scales to the organization with one ownership rule, decisions are recorded by the team that makes them, in their repositories, and the cross team decisions, the ones with consequences that cross boundaries, get one record per decision in a shared location with review from the affected teams. The shared library, the organization's docs tree or its platform repository, holds the integration decisions, the transports, the contract patterns, the security boundaries, and the team libraries hold their internal ones, and the reader's search covers both because the format is the same and the file names carry the sequence.
The governance that keeps the multi team library honest is the same review workflow, the cross team record is a pull request with reviewers from the affected teams, and the record's acceptance is the teams' actual agreement rather than a committee's minutes. The organizations that run the practice at scale report the same evolution, the platform team curates the shared library's format and its index, the teams keep their own timelines, and the onboarding path is the index, the new engineer reads the platform records, then their team's, and the organization's decision history assembles itself in the reading order.
The failure modes, from mausoleum to theater
The practice's failure modes are recognizable in every organization that tried it. The mausoleum, the wiki folder of records written for the process audit, all marked accepted, none superseded because superseding requires editing, and the library's timeline ends at the quarter the initiative ended. The theater, the record written after the decision was made elsewhere, the context section describing forces nobody weighed, and the engineers learn the record is the announcement in a costume, and its authority drops to the announcement's level. The drift, the records that describe a system that no longer matches, accepted and accurate once, and the reader who trusts them is misled by the library's age, which the status vocabulary prevents only when superseding is a habit.
The three failure modes have the same root, the records are not part of the work, they are paperwork about the work, and the counter is the workflow section above, the record in the repository, in the pull request, in the review. The teams that succeed report the same small discipline, the ADR file appears in the same commit as the decision's first implementation, the reviewer reads both, and the library grows at the code's own pace, which is the only pace that survives.
The team rules for the written library
The practice compiles into rules that fit on the wall, and the list is short:
- Record decisions with the consequence test, real alternatives, non-obvious why, the rest is commit history;
- Write the record before or with the code, in the pull request, reviewed beside it;
- Keep the format small, context, decision, consequences, options, one page;
- Maintain the status vocabulary, and supersede by link rather than by silence;
- Record the refusals, the declined proposals are the library's most reread volumes;
- Read the library in onboarding, the new engineer's first week follows the timeline the records draw.
The organization's real architecture is the library of decisions it can still read, and the code is the library's compiled output. The team that writes its decisions down, at the moment they are made, in the place the code lives, inherits an asset that no amount of later documentation can reconstruct, the reasons in the context of the forces that shaped them, which is the only thing the next team actually needs from the past one.