Template preview · Software
Architecture decision record
Make a technical decision and its trade-offs durable.
A concise ADR for a reversible or consequential engineering choice.
Sample purpose
Make a technical decision and its trade-offs durable.
Audience: Staff engineer, Engineering manager- Structure
- 4 sections
- Criteria
- 12
- Sources
- 8
- Watches
- 4
- Default approach
- Review first
Set the purpose first. Then change every section, criterion, and agent setting before anything runs.
Fictional sample
Structure and criteria
Sample content shows the shape of a useful document. Copying it is optional.
01 Review firstContext
Describe the technical pressure that requires a decision.
Criteria
- Names the system boundary (preference service), not the whole product
- Names at least one hard constraint, such as a two-week delivery window or cross-device sync
- Describes the current state clearly enough to show why it fails
Sources
- Architecture decision records (Google Cloud) docs.cloud.google.comADR structure and how to frame context.
- Relay Harbor preference service docs (fictional) api.relayharbor.exampleScale, delivery window and the browser storage limit.
Sample content
Relay Harbor stores notification preferences in browser settings, which do not follow a user across devices. The service needs a durable account-level preference with a two-week delivery window.
02 Review firstOptions considered
Compare credible alternatives against the constraints.
Criteria
- Lists at least two options that could meet the context constraints
- Compares them on the same axes used in context
- Each cost or benefit is concrete (e.g. cookie capped near 4 KB)
Sources
- RFC 6265 HTTP state management rfc-editor.orgCookie size and persistence limits that bound the cookie option.
- DB-Engines ranking db-engines.comComparison of storage approaches.
Watches
- Follows Context
Sample content
Option Benefit Cost Account database record Cross-device consistency Migration and API work Encrypted cookie Fast delivery Size and device limits 03 Review firstDecision
State the chosen direction and ownership.
Criteria
- Names the chosen option explicitly
- Rationale cites constraints from context and trade-offs from options
- Names the decision owner and status (proposed, accepted, superseded)
Sources
- ADR examples adr.github.ioHow teams record status and ownership.
- Relay Harbor decision register (fictional) api.relayharbor.exampleApproval state and traceability.
Watches
- Follows Context
- Follows Options considered
Sample content
Decision: use an account database record, owned by fictional platform lead Jia, because it preserves preference consistency across devices.
04 ManualConsequences and follow-up
Make implementation risks and revisit triggers visible.
Criteria
- Names at least one negative consequence the team accepted
- Each follow-up has an owner and a date or signal
- The revisit trigger is observable (p95 read latency above 150 ms)
Sources
- Prometheus metric naming prometheus.ioNaming for latency and backlog metrics used as triggers.
- Relay Harbor preference runbook (fictional) api.relayharbor.exampleCurrent dashboards and alert thresholds.
Watches
- Follows Decision
Sample content
- ☑ Add migration rollback test
- ☑ Review API latency after 30 days
- ☑ Revisit if p95 preference read exceeds 150 ms