The Anatomy of an Enduring Architectural Decision Record (ADR)

Every growing engineering team eventually confronts the same painful question during a critical outage or refactor: 'Why did we build it this way three years ago?' In most organizations, the answer is buried in an archived Slack channel, an unindexed meeting note, or worse, locked in the memory of an engineer who left eighteen months ago.

Architectural Decision Records (ADRs) are short, structured text documents that capture significant technical choices alongside their context and consequences. However, the majority of ADR rollouts quietly decay within six months. The failure mode is almost always over-formality.

The Minimum Viable Decision Record

An effective ADR requires only five concise sections. Keeping the format under two pages ensures that drafting a record takes less than twenty minutes during a standard pull request workflow:

2. **Context:** What technical, operational, or business constraint forced this decision? Crucially, note the options that were considered and rejected, rather than just the winner.

3. **Decision:** The exact architectural commitment made. Write this in direct, active voice ('We will route all inter-service events via NATS Core instead of Redis Streams').

4. **Consequences:** The honest trade-offs. Every sound architectural choice has downsides: increased memory footprint, operational overhead, or library constraints. Documenting negative consequences builds long-term trust in the document.

5. **Validation Method:** How will future engineers know if this decision is still holding? E.g., 'If our event throughput exceeds 45,000 msg/sec, this architecture must be re-evaluated under ADR review.'

Storing Decisions in the Repository Tree

The most critical rule of documentation hygiene is proximity. When ADRs are stored in external wikis or isolated intranets, they diverge from the code within weeks. Place your ADR directory directly inside your git repository at `docs/adr/` or `architecture/decisions/`.

By placing decisions in git, changes to architectural direction are reviewed via standard pull requests alongside code modifications. Git blame and commit histories automatically provide temporal context.

When we consult with engineering teams across Taiwan and East Asia, we often discover that retroactively recording the five most foundational past decisions provides immediate clarity for new hires. You do not need to document every trivial choice—document the choices that would cause a three-day debate if reopened.