Architectural Decision Records (ADR): A Practical Framework for Effective Architecture Decisions

1. What Is an Architectural Decision?

Architectural decisions involve the structure of an application or system and often extend to technology selection when a technology directly influences architectural characteristics. A good architectural decision helps development teams make correct technical choices at critical junctures. Operationally, four activities are essential: gathering sufficient relevant information, justifying the decision, recording the decision, and communicating it effectively to stakeholders.

2. Architectural Decisions vs. Technical Decisions

Many architects classify decisions as either architectural or technical based on whether a specific technology is involved, but this distinction is not always accurate. If a technology choice is made because it directly supports an architectural characteristic, it remains an architectural decision.

Michael Nygard introduced the concept of architectural significance . An architecturally significant decision affects five areas:

Structure : Decisions that influence architectural patterns or styles. Example: sharing code across microservices impacts each service's bounded context and overall system structure.

Non-functional characteristics : Technology choices that affect important architectural qualities cross the boundary into architectural decisions.

Dependencies : Coupling points between components or services. Dependency decisions directly affect scalability, modularity, agility, testability, and reliability.

Interfaces : How services and components are accessed and orchestrated (gateways, integration hubs, service buses, adapters, API proxies). Interface decisions involve contracts, versioning, and deprecation policies, affecting all consumers.

Construction techniques : Platform, framework, tool, or process decisions that influence any architectural aspect.

3. Three Anti-Patterns

3.1. Covering Your Assets

Architects avoid or delay important decisions out of fear of making mistakes. Avoidance appears safe but shifts risk to the future.

Two effective countermeasures:

Wait until the last responsible moment. Decision cost and risk change inversely over time. Early on, information is scarce, cost is low but risk is high; delaying gathers information and reduces risk, but delay itself accumulates cost. The optimal moment is when the rate of cost increase just exceeds the rate of risk decrease. Beware of analysis paralysis — endless analysis without decision.

Collaborate closely with development teams. Architects cannot know every technical detail. Collaboration enables quick validation of feasibility, surfaces new insights, and reduces error risk. Example: an architect decided to cache product reference data in every service instance using read-only replicas owned by the Catalog service to reduce coupling. During implementation, developers discovered that memory quotas for some services would be exhausted by the cache. Close collaboration exposed the issue early, allowing timely adjustment; otherwise it might have surfaced only as a production incident.

3.2. Groundhog Day

Named after the 1993 film where the protagonist relives the same day repeatedly. In architecture, teams repeatedly discuss and question a decision without reaching consensus because the architect did not adequately justify it.

Justification has two indispensable layers:

Technical justification : Why the decision is technically sound. Example: decomposing a monolith into multiple services to decouple functional boundaries, reduce per-service resource consumption, and enable independent maintenance and deployment.

Business justification : Why the investment of money and time is worthwhile. For the same decomposition, business justification could be faster feature delivery, shorter time-to-market, or lower development and release costs.

Business value is the litmus test for whether an architectural decision should be made. If no business value exists, the architect should reconsider. The four most common business justifications are cost, time-to-market, user satisfaction, and strategic positioning; the choice depends on what the business truly cares about.

3.3. Email-Driven Architecture

After a decision is made and justified, a third anti-pattern emerges: decisions are communicated via email and then forgotten. Over time, people forget the decision or never knew it existed, so implementation deviates.

Email is a poor decision repository because:

Multiple versions of the decision exist across email threads, breaking version control.

Justification details are often truncated, leaving only the conclusion, forcing re-discussion later.

When a decision is revised, there is no guarantee all stakeholders receive the updated version.

Better practice: email should only state the decision's nature and context, with a link to a single system of record.

4. Architectural Decision Records (ADR)

An ADR is a short text file, typically in AsciiDoc or Markdown, describing a specific architectural decision. Michael Nygard introduced ADRs in a 2011 blog post; ThoughtWorks Technology Radar recommended them in 2017.

A standard ADR contains five core sections plus two recommended optional sections.

4.1. Title: Clear at a Glance

Title usually includes a sequential number and a brief description. Example: 42. Use of Asynchronous Messaging Between Order and Payment Services . Good titles are concise, unambiguous, and convey the decision's nature and context.

4.2. Status: The Decision's Lifecycle

Each ADR has three states:

Proposed : Written, awaiting approval from superiors or architecture governance body.

Accepted : Approved, ready for implementation.

Superseded : Replaced by another ADR. Only Accepted ADRs can be Superseded; Proposed ADRs are revised until Accepted.

Superseded preserves history: it records what was decided, why, what it changed to, and why. Cross-references are bidirectional. Example: ADR 42 originally mandated asynchronous messaging between Order and Payment services. Later, Payment service implementation changed, so REST was chosen instead, creating ADR 68. Statuses become:

ADR 42: Status: Superseded by 68

ADR 68: Status: Accepted, supersedes 42

This eliminates repeated "why not messaging?" questions. An optional RFC (Request For Comments) state can be added with a deadline (e.g., Status: Request For Comments, Deadline 09 JAN 2026 ) to gather feedback before finalizing. The Status field also forces architects to clarify which decisions need higher approval — common thresholds: cost, cross-team impact, security. Teams should document these thresholds (e.g., decisions over $5,000 require architecture review board approval).

4.3. Context: Decision Drivers

Context describes the forces driving the decision — the situation that necessitates it — and briefly lists considered alternatives. Example: The Order service must pass information to the Payment service to pay for an order currently being placed. This could be done using REST or asynchronous messaging. If alternatives warrant deep analysis, add a separate Alternatives section.

4.4. Decision: Write in Imperative Mood

Nygard strongly recommends affirmative, imperative language. Good: We will use asynchronous messaging between services. Bad: I think asynchronous messaging between services would be the best choice. The former is a decision; the latter is an opinion. The Decision section's power lies in recording why — understanding why is far more important than understanding how it works.

4.5. Consequences: Trade-off Analysis

Every decision has positive and negative impacts. Consequences forces the architect to document the full impact and honestly assess whether negatives outweigh benefits. This is the ideal place for trade-off analysis. Example: choosing asynchronous fire-and-forget messaging for comment publishing reduced response time from 3100 ms to 25 ms, but raised concerns about complex error handling (e.g., profanity in comments). The team had already discussed and agreed: "Accept more complex error handling to guarantee response speed." Recording this in Consequences allows future reference to settle disputes.

4.6. Compliance: Measurement and Governance

Compliance is not a standard section but highly recommended. It describes how the decision is measured and governed: manual code review or automated fitness functions . Example: in a traditional layered architecture, a decision that all shared objects used by the business layer must reside in a shared services layer can be enforced automatically. A fitness function might look like:

@Test
public void shared_services_should_reside_in_services_layer() {
    classes().that().areAnnotatedWith(SharedService.class)
           .should().resideInAPackage("..services..")
           .check(myClasses);
}

This requires annotating shared classes with @SharedService — a governance cost that automatically guards boundaries on every change.

4.7. Notes: Metadata

Notes is also non-standard but recommended. Common metadata: Original author, Approval date, Approved by, Superseded date, Last modified date, Modified by, Last modification. Even with Git, these fields provide quick context for anyone reading the ADR.

5. Where to Store ADRs

Each architectural decision should have its own file or wiki page. Many architects colocate ADRs with source code in the same Git repo for versioning, but this has drawbacks for large organizations:

Stakeholders who need to see decisions may lack source repo access.

Application repos are not suitable for cross-application decisions (integration, enterprise-wide, or common decisions).

Recommended: a dedicated ADR Git repo, wiki, or shared directory structure. Example structure:

common : Decisions applying to all applications (e.g., all framework classes must carry @Framework annotation).

application : Subdirectories per application/system for app-specific decisions.

integration : ADRs concerning communication between applications, systems, or services.

enterprise : Enterprise-wide decisions affecting all systems (e.g., database access only by the owning system, preventing cross-system shared databases).

Naming conventions are flexible as long as the organization is consistent.

6. ADR Is More Than Documentation

6.1. ADR Is More Reliable Than Architecture Documentation

Software architecture documentation lacks a universal standard. ADR's sections naturally form a complete architecture document: Context describes background and alternatives, Decision records the rationale, Consequences adds trade-off analysis. Together they are deeper and more actionable than any diagram.

6.2. Using ADRs to Define Standards

Standards imposed without justification are resisted. Encoding standards as ADRs turns rigid rules into living rules with reasoning. Context explains why the organization adopts the standard; Decision states the standard and its necessity. Benefits: (1) the standard withstands scrutiny — if an architect cannot write an ADR justifying it, the standard probably shouldn't exist; (2) developers comply willingly because they understand the why. Consequences also tests standard validity by forcing architects to record impacts and assess worthiness.

6.3. ADRs Work for Existing Systems Too

Skeptics ask: what about legacy systems where decisions are already made? ADRs are still valuable — they help architects and developers understand why decisions were made and whether they remain valid . Approach: start with the most critical architectural decisions, write ADRs, then question their continued correctness. Example: why do a group of services share a database? What was the original rationale? Should data be split? This process often reveals that original decision-makers have left and reasons are lost. The architect must then research alternatives, analyze trade-offs, and validate or overturn the decision. Whether validated or overturned, writing ADRs builds a valuable "brain trust" and can uncover inefficiencies and design flaws.

Reference: Fundamentals of Software Architecture, 2nd Edition, Chapter 21