Architecture Decision Records

Preserve the decision and its context

An architecture decision record (ADR) captures a significant technical decision, the context that made it necessary, the options considered, the chosen option, and the consequences. The purpose is not to write a long essay or justify every implementation detail. It is to preserve the reasoning future engineers need when they encounter the decision without having attended the original meeting.

A useful ADR answers a small set of questions: what situation prompted a decision; what forces, constraints, and quality attributes mattered; which alternatives were credible; what was chosen and why; and what trade-offs or follow-up work the choice creates. Consequences include benefits and costs, migration steps, operational burden, security implications, and conditions that would justify revisiting the choice. A decision without consequences is usually missing the part that future maintainers need most.

Use a lightweight lifecycle

Write the record when a decision is made or as part of the design review that makes it. Keep the proposal short enough to review, but include enough evidence to compare options. A simple status can distinguish proposed, accepted, rejected, and superseded decisions. Once accepted, the ADR becomes a durable historical record; do not silently rewrite it when the system changes. Create a new record that supersedes it so readers can understand both the old and new rationale.

Store ADRs in version control near the system they describe. A numbered filename such as 0042-use-event-stream.md provides a stable identity and makes changes reviewable alongside code. Keep accepted and rejected records in the same sequence. Rejected alternatives explain why a team did not choose a seemingly obvious path, preventing the same debate from restarting without new evidence. Never delete a decision merely because it is no longer current; mark its successor and current status clearly.

Decide what deserves a record

An ADR is useful when a choice has meaningful long-term consequences, constrains future designs, crosses team ownership, or is difficult to reverse. Examples include a data store, service boundary, consistency strategy, authentication model, or migration approach. Routine implementation choices that are local and easy to change usually do not need an ADR. Recording everything creates paperwork and makes important decisions harder to find.

The unit of a record should be one coherent decision. If a document chooses a database, a deployment model, and an authentication provider, it is harder to supersede only one choice. If the options and consequences are inseparable, one record may be appropriate; otherwise split them and link related records. A decision log is an index of reasoning, not a replacement for detailed API contracts, threat models, runbooks, or operational guides.

Evidence and revisiting

Compare options against the forces that matter: latency, availability, data ownership, team skills, cost, security, operational capacity, and reversibility. Avoid presenting a favored option as inevitable. A lightweight table can show how options meet constraints, while prose explains the decision. Distinguish facts from assumptions, and identify what evidence would change the conclusion. When uncertainty is high, a time-boxed experiment may be the right next action rather than a permanent commitment.

Revisit an ADR when its assumptions change, a consequence becomes unacceptable, a new constraint appears, or a planned migration reaches its trigger. The record itself can state a review date or measurable condition. Do not reopen a sound decision merely because a new technology is popular; compare it against the original constraints and switching cost. This keeps the log useful as living organizational memory without pretending decisions are permanent laws.

Draft one decision at a time

Suppose an application needs asynchronous integration between order processing and inventory. The team could call the inventory API synchronously, publish an event to a managed broker, or use a database outbox with a relay. Start with the context: which workflow needs decoupling, what delivery guarantee is required, and what operational capacity exists? State constraints such as peak throughput, acceptable delay, idempotency, and the teams that own each system.

Record credible alternatives, including the option to keep the current approach. Compare them against those constraints. A broker may provide durable buffering but adds operational and schema-evolution work. A synchronous API is simpler but couples availability and latency. An outbox can preserve a local transaction boundary but requires relay monitoring and duplicate handling. Choose one option and make the reason explicit. Include consequences such as new dashboards, retry policy, ownership, rollout sequence, and failure behavior.

# ADR 0042: Publish inventory reservations asynchronously

## Status
Accepted

## Context
Order creation must not block on inventory service latency, but reservations must be durable and duplicate delivery must be safe.

## Decision
Write a reservation request to the transactional outbox and relay it to the broker.

## Consequences
- Order creation no longer depends on inventory availability at request time.
- The relay requires monitoring, retry limits, and dead-letter handling.
- Consumers must be idempotent and expose reservation status to support.

## Alternatives considered
- Synchronous inventory API call: simpler, but couples request latency and availability.
- Direct broker publish: lower latency, but can lose the event if the database commit fails.

This example is intentionally compact. A real decision should name the relevant systems and ownership, explain any assumptions, and link to the design or experiment that supports the choice. Do not add a decision table simply to create a formal appearance; use it when it clarifies how options compare against constraints.

Review and accept

Circulate the draft to the people who own affected systems and operations. Ask whether the context is accurate, whether a credible alternative is missing, and whether the consequences are operationally complete. A review is not a popularity vote. The decision owner should make the call, record unresolved risks, and identify any action that must happen before rollout. If the record is proposed, keep that status visible so readers do not mistake a draft for an approved standard.

Once accepted, commit the ADR with a stable number and link it from relevant architecture documentation or code where the decision is enforced. If implementation discovers a material assumption was wrong, update the status and create a superseding record rather than editing the history to imply the team always knew the outcome. A new ADR can reference the earlier one and explain what changed: traffic evidence, regulation, team ownership, or a failed operational assumption.

Exercise the retrieval path

Ask a new team member to find why the application uses the selected integration pattern. Can they find the record from the repository, understand its status, and see which consequences are still active? If not, improve the index and links. A decision log has little value if it is technically complete but practically undiscoverable.

Add a link from the service architecture page and from the operational runbook for the relay. The ADR explains why the architecture was chosen; the runbook explains how to operate it. Keep responsibilities separate while making navigation between artifacts easy. Where automated checks can enforce the decision, link those checks so the rationale and implementation remain connected.

Finally, define a trigger for review, such as sustained event volume exceeding the broker tier or a change in delivery guarantees. A trigger turns revisiting into an evidence-based activity instead of an annual paperwork exercise. If the trigger is never reached and assumptions remain valid, the ADR continues to explain the current design without needing cosmetic updates.

Keep the record concise but decision-complete

An ADR is too thin when it says only what was selected; it is too heavy when it reproduces every meeting note and implementation detail. The record should preserve the context, constraints, alternatives, rationale, and consequences that someone needs to understand the choice later. Link to deeper design artifacts rather than embedding their entire contents. A concise record is easier to review and more likely to be maintained.

Avoid writing the alternatives as straw options. A useful record explains why a credible alternative was rejected under the current constraints, not why an obviously unsuitable choice is inferior. Include a no-change option when it is realistic. State assumptions and uncertainty explicitly. If a prototype or benchmark influenced the decision, link to the evidence and describe its limits, such as synthetic traffic or an incomplete failure test.

Preserve history without freezing the architecture

Accepted decisions are historical facts about what the team chose at a point in time, not immutable policy. When a decision is superseded, retain the old record and create a new one that explains the changed context. Mark the earlier status, link forward, and keep identifiers stable. Rewriting the old rationale destroys the evidence future teams need to understand migrations and avoid repeating experiments.

Rejected decisions are useful memory too. They explain why the team did not adopt an alternative and under what assumptions. If those assumptions change, the alternative can be reconsidered with new evidence. Avoid deleting rejected records because a tool or vendor is no longer fashionable; archive them through status and indexing instead.

Governance without bureaucracy

Not every code change needs an ADR. Use a decision threshold based on impact, reversibility, cross-team reach, risk, and cost of changing later. A local variable name does not need a record. A data ownership boundary or a decision to make a system eventually consistent may. Teams can allow a lightweight template and local ownership while requiring broader review for high-blast-radius choices.

Version control is usually a good home because it provides review, history, and a durable location beside implementation. A wiki can work if it is reliable and discoverable, but avoid scattering decisions across meeting minutes, chat, and personal documents. Assign an owner for the index and link records from the architecture overview. Automation can verify numbering or required sections, but it should not enforce prose style at the expense of useful reasoning.

Interview framing

In an interview, explain ADRs as a mechanism for preserving decision context, not as a design approval ceremony. Describe the minimum sections, how alternatives are compared, and why consequences matter. Explain why superseded decisions remain in the log and how a new record captures changed assumptions. Then identify a choice that would not justify an ADR, showing that the process is proportional.

A strong answer includes how the decision connects to implementation and operations: source control makes it reviewable, links make it discoverable, and review triggers keep it relevant. It also distinguishes an ADR from a runbook, API contract, or detailed design. The record says why a durable choice was made; other documents describe how to build or operate the resulting system. This distinction keeps documentation useful rather than duplicative.