Architecture Decision Records
Document architectural decisions as lightweight ADRs to preserve context, enable async decision-making, and build organizational memory.
Architecture Decision Records (ADRs) are short documents that capture significant architectural decisions-including the context and consequences. They answer "why is the code like this?" for engineers who join years later, preventing rediscovery of rejected paths.
Every significant architectural decision should have an ADR. Write them before you build-an ADR that's written during or after implementation captures the decision but not the alternatives. Lightweight > comprehensive: a two-paragraph ADR beats no ADR.
Workflow
- Identify decisions that need an ADRNot every decision needs documentation; capturing the wrong things creates noise.
- Write the ADR before the decision is finalPre-decision ADRs capture genuine alternatives and enable async review; post-decision ADRs rationalize choices.
- Track ADR lifecycle and supersessionOutdated ADRs that still say "Accepted" mislead engineers into following decisions that no longer apply.
- Link ADRs to code and documentationDisconnected ADRs are undiscoverable; linked ADRs get found when the code is being read.
- Build team ADR cultureADRs only provide value if the team uses them consistently.
Output Format
ADR file in `docs/decisions/`, status tracked, supersession linked, code comments referencing ADR numbers, ADR index in README.
Examples
ADR filename: `docs/decisions/0042-use-postgresql-for-audit-log.md`MADR status section: "## Status
Accepted
## Supersedes
ADR-0031 (Use MySQL for all storage)"Code link comment: `// Connection pooling disabled here per ADR-0039 (avoid connection exhaustion under burst load)`Edge Cases & Gotchas
- Team resists ADRs as overhead: start with one ADR per sprint; demonstrate value by surfacing an old ADR that prevented re-litigating a decision
- ADRs for cross-team decisions: store in a shared repository or wiki; link from both codebases; include representatives from all affected teams as reviewers
- ADRs in monorepos: service-level ADRs in service subdirectory; cross-cutting ADRs at repo root
When to Break These Rules
- Throwaway prototypes and experiments don't need ADRs-add them when the experiment graduates to production.
Reference Files
MADR (Markdown Any Decision Record): https://adr.github.io/madr/Michael Nygard ADR origin post: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisionsADR Tools CLI: https://github.com/npryce/adr-tools