Architecture decisions often outlive the people, constraints, and delivery pressures that produced them. An architecture decision record (ADR) preserves why a significant choice made sense at the time, so later teams can revisit it without mistaking an unexplained constraint for accidental complexity. Its purpose is not to freeze the design; it is to make assumptions, trade-offs, and consequences visible enough to challenge intelligently. section 4.4.4 section 1.2
An ADR is a lightweight record of a decision and its context. A Markdown file kept with the repository can be sufficient: the value lies in durable reasoning, not a specialized platform. It is especially useful where teams change, ownership moves, or a local technical choice has cross-cutting effects. section 4.4.4 section 1.2
A useful ADR makes the decision reviewable rather than personal by recording:
- The decision, its status, and the context that made it necessary. section 4.4.4
- Alternatives considered, along with the constraints or forces that shaped the choice. section 4.4.4
- Expected consequences and trade-offs, including security or total-cost implications when relevant. section 4.4.4
- A review trigger: conditions under which the decision should be revisited, superseded, or deprecated. section 4.4.4
Record commitment with a revisit condition
For an uncertain system, record decisions that are expensive to reverse—such as deployment shape, data ownership, or integration contracts—separately from choices that can wait. State why stability is needed now, then name evidence that would justify review, such as changed availability needs, compliance requirements, ownership, or coupling. This prevents premature certainty while keeping consequential commitments deliberate. section 3.3 section 4.4.4
ADRs complement rather than replace broader architecture documentation. Small teams may need only records and a few diagrams; organizations with regulation or wider coordination may also need formal views, traceability, ownership, and review discipline. The appropriate level is proportional to the decision’s consequences and operating context. section 4.4.4
Table 3.4 Open decision log for an uncertain greenfield system
|
Decision
area
|
Classification
|
Why
|
Revisit
trigger
|
|
Basic
deployment model
|
Decide now
|
Deployment
shape affects environments, release flow, observability, access control, and
team habits. Retrofitting it later can force changes across pipelines,
infrastructure, and support procedures.
|
Revisit if
availability needs, release frequency, compliance requirements, or team
ownership change significantly.
|
|
Code and
repository organization
|
Decide now
|
Poor
structure becomes expensive once features, tests, deployment scripts, and
ownership boundaries accumulate around it.
|
Revisit if
modules become too coupled, ownership splits across teams, or build/release
boundaries become painful.
|
|
Data
ownership boundaries
|
Decide now,
but keep boundaries coarse
|
Data
ownership affects persistence, integration contracts, reporting, migration,
and future decomposition. Wrong early ownership decisions are hard to unwind
after data starts flowing through the system.
|
Revisit
when domain boundaries become clearer, data duplication appears, reporting
needs change, or different teams need independent ownership.
|
|
Security
boundaries
|
Decide now
|
Identity,
permissions, secrets, network exposure, and access paths become dangerous and
expensive to retrofit once users and integrations depend on the system.
|
Revisit
when new consumers, environments, compliance needs, or external integrations
appear.
|
|
Observability
baseline
|
Decide now
|
Without
basic logs, metrics, traces, and correlation, the team cannot learn safely
from early delivery or diagnose failures when assumptions prove wrong.
|
Expand when
operational load increases, incidents become harder to diagnose, or more
teams depend on the system.
|
|
Full
service decomposition
|
Defer
|
Domain
boundaries are still unclear, and independent deployment is not yet needed.
Splitting too early would turn guesses into operational cost.
|
Revisit
when separate teams own different capabilities, scaling needs diverge, or
release coordination becomes a real bottleneck.
|
|
Generalized
integration framework
|
Defer
|
Only a few
integrations are confirmed. A framework built too early would encode imagined
variation rather than real patterns.
|
Revisit
when several integrations show repeated mapping, retry, security, monitoring,
or transformation needs.
|
|
Workflow
engine or rules platform
|
Prototype
or monitor
|
A rules
engine may be useful if workflows become dynamic, but for one unclear
workflow it adds complexity before the variation is proven.
|
Revisit
when business users need frequent rule changes, multiple workflows appear, or
hard-coded rules start slowing delivery.
|
|
Advanced
scaling strategy
|
Monitor
|
Expected
throughput and user numbers are uncertain. Designing for extreme scale too
early may waste effort and increase complexity.
|
Revisit
when load tests, production telemetry, or business growth show that current
capacity assumptions are no longer safe.
|
Use the open decision log to distinguish commitments that need stability now from decisions that should remain cheap to change, and attach concrete revisit triggers. section 3.3
An ADR remains useful only when it participates in a feedback loop. Incidents, recurring workarounds, delivery friction, observability, and architectural reviews can reveal that its assumptions no longer hold. The resulting response may be deferral, adaptation, or replacement; keeping the record visible and safe to update turns past reasoning into a current decision aid rather than ignored documentation. section 4.3 section 4.8
Write down consequential choices while their context is still clear. Make the trade-off explicit, assign no permanence beyond the evidence, and define what future signal would warrant reopening the decision. section 4.4.4 section 4.3






