The most dangerous kind of technical decision is one that everyone has forgotten the reasoning behind. Six months after a major architecture choice, a new engineer asks “why did we do it this way?” and nobody can answer confidently. That’s when bad refactors happen. Architectural Decision Records (ADRs) fix this problem.
What an ADR is
An ADR is a short document — typically one page — that captures a significant architectural decision: the context that led to it, the options that were considered, the decision made, and the tradeoffs accepted. It’s not a design document. It’s not a spec. It’s a record of a decision that was hard enough to deserve explanation.
The format I use
# ADR-0012: Use CloudFront + S3 for static content delivery
## Status
Accepted — 2023-04-15
## Context
AEM publish tier experiencing latency spikes during campaign peaks.
Origin infrastructure scaling is expensive and reactive.
Need predictable performance for global automotive audience.
## Decision
Adopt hybrid static + CDN delivery:
- AEM replication agent pushes static HTML to S3 on activation
- CloudFront serves static content from S3 edge nodes
- Lambda@Edge handles dynamic personalisation (lang/region/model)
- Cache-miss path falls through to AEM Dispatcher as before
## Alternatives Considered
1. Horizontal publish scaling — rejected: treats symptom, not cause
2. Full static generation (Gatsby/Next) — rejected: too expensive to rebuild AEM authoring workflows
3. Varnish cache in front of Dispatcher — rejected: adds infrastructure complexity without CDN reach
## Consequences
+ 25% page load improvement on cached paths
+ 60% reduction in origin hits during peak
+ Predictable AWS costs via S3 lifecycle policies
- Cache invalidation complexity: custom replication agent required
- 30–90s eventual consistency window on content updates
- Additional complexity for local development (S3 mock required)Why this matters at Staff level
At Staff Engineer and above, you’re not just making decisions — you’re enabling your team to make good decisions without you in the room. ADRs are the artefact that lets that happen. When a junior engineer is debating whether to change the caching strategy, they can read ADR-0012 and understand exactly what tradeoffs were considered and why the current approach was chosen.
In FAANG-style engineering cultures, this kind of documentation is a first-class deliverable. It’s how you demonstrate that your thinking is rigorous, that you considered alternatives, and that you can communicate architectural reasoning to stakeholders at any level.
Where to store ADRs
Keep them in the repository, in a /docs/decisions/ directory, numbered sequentially. They should be version-controlled alongside the code they describe. Never store them in Confluence or Notion alone — they’ll get buried, and you’ll lose the connection between the decision and the code that implements it.
An ADR that says “Accepted” and is six months old is not a mistake — it’s evidence that your team thinks carefully. An ADR that gets superseded by ADR-0023 is even better evidence: it means your team revisits decisions when context changes rather than treating past choices as sacred.
Start writing ADRs for your next significant decision. One page. Fifteen minutes. It will save hours of confusion six months from now.