In the lifecycle of a long-running software system, the most dangerous technical debt is often not code, but the ‘lost context’ of past architectural decisions. As engineers rotate, teams dissolve, and priorities shift, the rationale behind specific design choices—such as selecting a particular database engine or implementing a specific concurrency model—frequently vanishes. This loss forces new team members to engage in ‘archaeological [engineering](/blog/blameless-postmortems-how-elite-engineering-teams-learn-from-incidents),’ deciphering intent from implementation rather than understanding the original constraints.

Architecture Decision Records (ADRs) provide a structured mechanism to codify these choices. By treating architectural decisions as first-class artifacts within the codebase, teams can create a durable, versioned history that persists long after the original stakeholders have moved on. This approach shifts the focus from merely recording what was built to explaining why it was the optimal choice under the constraints of the time.

The Mechanics of an ADR

An ADR is not a lengthy design document; it is a concise, markdown-formatted file stored directly in the repository alongside the source code. Its effectiveness lies in its brevity and its standard format, which forces the author to distill the decision into its essential components: context, decision, and consequences.

1. Title: A unique, descriptive identifier for the decision.
2. Status: Indicates the lifecycle state (e.g., Proposed, Accepted, Deprecated, Superseded).
3. Context: The problem statement and the forces at play, including technical requirements, business constraints, and non-functional trade-offs.
4. Decision: A clear statement of the chosen path.
5. Consequences: An honest assessment of the trade-offs, including both positive outcomes and negative side effects.

Treating Trade-offs as First-Class Citizens

The most critical section of an ADR is the ‘Consequences’ block. In software engineering, there are rarely perfect solutions, only trade-offs. A decision to use an event-driven architecture might solve for scalability but introduce significant operational complexity in debugging distributed traces. Recording these trade-offs explicitly prevents future teams from viewing these complexities as ‘bugs’ rather than intentional design choices.

The value of an ADR is not in the decision itself, but in the explicit acknowledgement of what was sacrificed to achieve it.

Integrating ADRs into the Workflow

For ADRs to be effective, they must be part of the development lifecycle. This means including them in the pull request process. If an architectural change is proposed, it should be accompanied by a draft ADR. This forces a discussion on the trade-offs before the code is merged, turning the architectural review into a collaborative documentation exercise.

# ADR 005: Adoption of gRPC for Inter-service Communication

## Status
Accepted

## Context
Our microservices currently communicate via REST over HTTP/1.1. As we scale, the overhead of JSON serialization and the latency of text-based protocols are impacting p99 response times.

## Decision
We will migrate internal service-to-service communication to gRPC using Protobuf.

## Consequences
- Positive: Significant reduction in payload size and improved latency.
- Negative: Increased complexity in debugging binary payloads and requirement for schema registry management.

Managing Decision Evolution

Systems evolve, and yesterday’s optimal decision often becomes today’s technical debt. ADRs handle this gracefully through the ‘Superseded’ status. When a decision is revisited, you do not delete the old record; you link the new ADR to the old one. This provides a clear audit trail of why the system evolved, preventing the ‘Chesterton’s Fence’ problem where a new engineer removes a safeguard without understanding why it was originally placed.

Common Pitfalls and Anti-patterns

• Over-documentation: Writing ADRs for trivial changes. ADRs should be reserved for decisions with lasting architectural impact.
• Storing outside the repo: Keeping ADRs in a wiki or external tool leads to them becoming disconnected from the code, eventually leading to obsolescence.
• Lack of maintenance: Failing to update the status of an ADR when a decision is superseded or abandoned.

Conclusion

Architecture Decision Records are a powerful tool for building resilient engineering organizations. By externalizing the ‘why’ of our systems, we reduce the cognitive load on future engineers and foster a culture of deliberate, transparent design. In an industry defined by rapid change, the ability to document the reasoning behind our systems is perhaps the most effective way to ensure the long-term health of our software architectures.