Resources · 84

Architecture decisions: retain the rationale and know when to reconsider

Document consequential choices without turning every meeting into an oversized dossier.

· 4 min

Empty cyber intelligence operations room at night AI-generated editorial illustration

What this guide helps achieve

  • Bound the decision
  • Compare plausible options
  • Name the decision and consequences
  • Preserve historical context
  • Define useful review triggers

Quick check

  • Does every ticket need an ADR?
  • Can an accepted decision change?
  • Does a register guarantee a good choice?

Step-by-step method

  1. 01

    Bound the decision

    Choose a question with lasting effects, such as hosting, integration, storage or component boundaries. An ADR preserves the rationale of a significant architectural choice. Describe the actual problem and current constraints rather than retrofitting a commercial justification.

    Deliverable: decision question and scope.

  2. 02

    Compare plausible options

    Describe options genuinely considered, including keeping the current solution where viable. Apply common criteria for use, security, operation, included costs and exit. Separate measurements, documentation-derived claims and remaining assumptions.

    Deliverable: criteria and evidence table.

  3. 03

    Name the decision and consequences

    Record the chosen option, owner, date and status. Describe accepted effects, including debt, migration and limitations. Approval does not eliminate a known constraint. Link the choice to requirements met and checks still needed.

    Deliverable: accepted decision and explicit consequences.

  4. 04

    Preserve historical context

    A replaced decision should remain understandable. Link it to its successor instead of rewriting history. The ADR process distinguishes proposed, accepted, rejected and superseded decisions. Retain links to tickets and evidence the team can access.

    Deliverable: register with version relationships.

  5. 05

    Define useful review triggers

    Specify changes such as volumes exceeding the tested scope, provider unavailability, localization needs or costs outside assumptions. A trigger should initiate an updated comparison rather than automatic abandonment. Check whether a new service owner can explain the choice without consulting its original participants.

    Deliverable: review triggers and handover test.

Acceptance case to reproduce

Fictional example: these inputs describe no customer or observed result.

View case inputs
{
    "decision": "ADR-7",
    "status": "accepted",
    "assumption": {
        "requests_per_day": 1000
    },
    "current_requests_per_day": 100000
}

Expected decision

The load assumption changed by a factor of 100. Revisit ADR-7 and retain the historical decision.

Fictional variations to test

An ADR is accepted but only one of three services implements it.

Distinguish accepted decision from completed rollout. Track the remaining services with an owner, any exception and evidence of adoption.

The pilot requires p95 ≤ 200 ms; the test measures 350 ms.

The stated criterion is not met. Retain load, window and test result, then decide on revision rather than declaring success.

A temporary exception reaches its review date.

Mark it for reassessment. Silence does not automatically renew an exception; assign a dated decision with conditions and an owner.

Evidence to retain

  • ADR status and adoption by service.
  • Pilot criteria, procedure and measured result.
  • Owner, deadline and exception decision.

Verification procedure

  1. Record decision, alternatives and load assumptions.
  2. Compare a failed assumption with current conditions.
  3. Keep the old ADR and its replacement link. Date the changed assumption, name the review owner and specify evidence needed to decide whether the replacement fits the new context.

AWS Prescriptive Guidance — Architectural decision record process

Reusable worksheet

Complete with your authorised observations. These fields are a working template, not observed results.

FieldInformation to record
QuestionProblem, scope and constraints at decision time
OptionsCompared solutions and common criteria
ChoiceStatus, owner, reasons and consequences
ReviewTrigger and link to any replacement decision

Worked example

Illustrative situation

Fictional example: a team selects managed search because it cannot provide the required on-call coverage.

Decision and expected evidence

The register records this constraint, expected exports and review triggers for changed localization needs or costs.

Distinguish the mechanisms

MechanismPurposeCheck or limitation
Meeting minutesRetain discussionThe decision may be scattered
ADRRetain choice, reasons and consequencesDoes not replace specifications or tests
Implementation ticketTrack delivery workMay close without retaining the rationale

Management indicators

IndicatorWhat it measuresFirst action
Traceable choicesSignificant decisions with accessible context and consequencesAddress dependencies hardest to take over
Checked assumptionsDecisive assumptions tested or measuredRevise criteria where evidence is missing
HandoverChoices a new owner can explainImprove the register instead of adding meetings

Common pitfalls

  • The decision may be scattered
  • Does not replace specifications or tests
  • May close without retaining the rationale

Frequently asked questions

Does every ticket need an ADR?

No. Reserve it for significant choices whose consequences or reversibility justify retaining the rationale.

Can an accepted decision change?

Yes. Record the new decision, its context and its relationship to the replaced decision without deleting earlier reasons.

Does a register guarantee a good choice?

No. It makes criteria and assumptions open to review; evidence and testing quality remain decisive.

Further reading and tools

Editorial resources to extend the method.

Official references

References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.