Architecture decision records best practices treat ADRs as a working decision system, not a folder that proves a meeting happened. An ADR captures one architecturally significant choice, its context, alternatives, rationale, consequences, and status. The collection becomes valuable when teams can discover the current decision, see what it replaced, connect it to implementation, and revisit it when assumptions change.
The ADR community defines an architectural decision as a justified choice addressing a significant requirement and an ADR as the record of that decision and rationale. Its overview also distinguishes an individual record from the project’s decision log. That distinction matters: a good page template does not by itself create coherent status, ownership, search, or lifecycle governance across hundreds of decisions.
Define what triggers an ADR
Record a choice when it changes system structure, a key quality attribute, a difficult-to-reverse dependency, a cross-team contract, data ownership, security boundary, operating model, or material cost commitment. Do not require ADRs for every library patch or implementation detail. A practical trigger asks whether a future team could safely change the system without knowing why this option was selected over plausible alternatives.
Permit lightweight records for local reversible choices and deeper review for decisions with broad blast radius. The same workflow can support both if metadata carries impact and review class. Microsoft’s current Azure Well-Architected ADR guidance, updated in April 2026, recommends records for choices affecting structure, quality attributes, or reversibility and describes the log as append-only.
Design a concise record anatomy
| Field | Purpose | Quality check | Common failure |
|---|---|---|---|
| Title and decision ID | Provides stable identity | States the actual choice | Topic-only title such as database |
| Status and date | Shows lifecycle state | Uses controlled values and effective date | Accepted record silently edited |
| Context | Explains forces and constraints | Separates facts, assumptions, and uncertainty | Long system history with no decision pressure |
| Options | Makes alternatives inspectable | Includes plausible options and do-nothing case | Straw alternatives |
| Decision and rationale | States what is chosen and why | Connects criteria to evidence | Consensus asserted without tradeoffs |
| Consequences | Makes costs and follow-up visible | Includes positive, negative, and operational effects | Benefits only |
| Links and owner | Connects action and accountability | Names team plus implementation and supersession links | Person name with no durable team |
Keep the core record short enough to review. Link detailed benchmarks, threat models, diagrams, and prototypes as evidence, but preserve the decisive facts in the ADR so a broken link does not erase the rationale. Record confidence when evidence is incomplete and attach a review trigger such as traffic exceeding a threshold, a vendor capability changing, or a regulation taking effect.
Operate a proportionate decision workflow
Let any team member propose a record. Assign a decision owner, identify affected teams, set a review deadline, and choose reviewers by consequence: security for trust boundaries, data owners for write authority, platform teams for operating commitments, and finance for material recurring cost. Time-box discussion. An ADR should expose disagreement and authorize a direction, not wait for universal enthusiasm.
- Proposed: open for evidence and review; implementation must not imply acceptance.
- Accepted: authorized and effective, with owner and consequences acknowledged.
- Rejected: considered but not chosen; retained when rationale will prevent repeated debate.
- Deprecated: still present but discouraged while migration proceeds.
- Superseded: replaced by a linked newer record; historical content remains immutable.
- Cancelled: proposal withdrawn before acceptance, with a brief reason.
AWS Prescriptive Guidance on ADR best practices recommends distributed ownership, preserving history, regular review, central accessibility, and changing an old record to Superseded when a new one replaces it. Implement status changes as small reviewed commits so chronology and authority remain inspectable.
Connect decisions to delivery evidence
Store records close to workload documentation in version control when possible. Use immutable IDs in pull requests, issue trackers, service catalogs, runbooks, architecture tests, and dashboards. A code change implementing a decision should link the ADR; the ADR should link the first implementation and any required migration. This bidirectional connection reveals accepted decisions with no action and code that contradicts declared policy.
Use path ownership to route review for the decision log. GitHub documents how CODEOWNERS can request reviews for matching files and how branch protection can require code-owner approval. Avoid one architecture group owning every record path, because that centralizes throughput. Prefer workload or domain owners with specialist reviewers added by impact.
Detect contradictions and supersede cleanly
| Check | Method | Owner action | Evidence of completion |
|---|---|---|---|
| Duplicate active decisions | Search tags, scope, and affected component | Merge scope or clarify precedence | Cross-links and one current authority |
| Contradictory decisions | Compare constraints and declared interfaces | Create resolving ADR | Explicit supersession or bounded scopes |
| Accepted but unimplemented | Query records without delivery links after due date | Plan work or reverse decision | Merged change or new status |
| Expired assumption | Evaluate review trigger and evidence date | Revalidate or propose replacement | Outcome note or superseding ADR |
| Orphaned owner | Reconcile team identifiers with service catalog | Transfer accountability | Current owning team recorded |
| Legacy exception | Review consequence tasks and waivers | Remove, renew, or redesign | Closed task and verification |
Never rewrite an accepted record to make history look cleaner. Create a new ADR, link supersedes and superseded-by in both directions, state what changed in the context, and preserve the former consequences. If only an obvious typo changes, use repository history and avoid altering the decision meaning. A decision log is trustworthy because it shows learning, including reversals.
Review outcomes rather than document count
At a scheduled cadence, sample consequential ADRs and compare predicted consequences with operational evidence. Did the new database reduce the targeted bottleneck? Did the build standard improve patching while increasing startup time? Were migration costs underestimated? Add a dated outcome note or create a new decision when direction changes. Do not turn the accepted record into a rolling design document.
Measure retrieval success, time from proposal to decision, unowned records, decisions without implementation links, expired reviews, supersession integrity, and incidents where missing rationale delayed response. A rising ADR count is neither success nor failure. The system succeeds when teams find current authority quickly and use prior reasoning to make a better next decision.
Create an index generated from record metadata rather than a hand-maintained list. It should expose ID, title, status, effective date, owner, scope, tags, supersedes, and review trigger, and fail validation on duplicate IDs or broken links. Search terms should include domain and quality attributes, not only technology names. A future engineer is more likely to search data residency or recovery objective than the exact vendor chosen years earlier.
For decisions spanning repositories, keep one authoritative ADR and link local implementation notes to it. Copying the same decision into five repositories creates divergent status and rationale. If each service makes a genuinely local choice under a platform standard, give the platform decision a scope and let local ADRs cite it, record their context, and explain any authorized deviation.
Treat meeting minutes and ADRs differently. Minutes record discussion and attendance; an ADR states an authorized choice. Link minutes as evidence if needed, but do not force readers to infer the outcome from a transcript. Likewise, a request for comments can gather options while the final ADR records which option became effective. This separation keeps the decision surface concise without erasing deliberation.
During incident review, ask whether an ADR existed, was discoverable, reflected current implementation, and stated the relevant consequence. If not, improve the trigger, links, or review cadence. Do not mandate an ADR for every corrective action. Use the incident to identify the class of consequential decision whose rationale must remain available during future response.
Key takeaways
- Use ADRs for consequential, difficult-to-reverse choices, with review depth proportional to impact.
- Keep records concise but include context, alternatives, rationale, consequences, status, owner, and links.
- Treat the decision log as append-only; supersede rather than rewrite accepted history.
- Connect ADR IDs bidirectionally to code, tests, migrations, service ownership, and operations.
- Review whether decisions produced their intended outcomes and whether assumptions remain valid.
Frequently asked questions
Should ADRs live in a repository or a wiki?
Either can work if records are versioned, searchable, reviewable, and linked to delivery. Repository storage naturally supports pull-request review and code links; a wiki can improve access for non-developers. Avoid duplicate authoritative copies. Publish a rendered view from one source when both experiences are needed.
Should a brownfield system create ADRs retroactively?
Capture only decisions that still constrain current work and label the evidence as reconstructed. Do not invent certainty or recreate every historical choice. Prioritize data ownership, external dependencies, security boundaries, and operating commitments that teams repeatedly question.
Can an accepted ADR ever be edited?
Correct non-semantic errors with a visible change history, but do not alter the accepted decision or rationale in place. Material change requires a new record that supersedes the old one. Outcome observations can be appended as dated notes if policy permits.
Conclusion
An ADR program earns its keep when decisions remain current, connected, and challengeable. Define clear triggers, use a compact anatomy, distribute ownership, preserve status history, and link rationale to implementation and outcomes. That turns a collection of Markdown files into organizational memory that improves delivery instead of merely documenting it.