An Architecture Decision Record (ADR) is a short document capturing a single architectural decision: what you decided, why, what alternatives you considered, what trade-offs you accepted.
Format:
` Title: ADR-007: Use Custom Metadata Types over Custom Settings for Configuration
Status: Accepted | Superseded by ADR-X | Deprecated
Context: We have ~30 configuration values needed across the org. Some change frequently; some only at deploy time. We need a strategy.
Decision: Use Custom Metadata Types for deploy-time config; Custom Settings (Hierarchy) only for runtime-mutable per-user settings.
Consequences:
- Pros: deployable, cached, packageable.
- Cons: read-only at runtime; admins can't change without a deploy.
- Trade-off accepted because most config is stable across environments.
Alternatives considered:
- Custom Settings only — rejected because data doesn't deploy.
- Custom Metadata only — rejected because some settings genuinely need runtime mutability.
- Custom object — rejected because no caching benefit.
Date: 2026-05-01 Author: Alex Architect `
Why ADRs matter:
- Future you / future team — 18 months later, "why did we do it this way?" gets answered.
- Onboarding — new architect catches up on history.
- Scope discipline — writing the ADR forces clear thinking.
- Conflict resolution — when the team disagrees, write the ADR; consider alternatives explicitly.
Storage: Confluence, GitHub, internal wiki. Numbered sequentially.
ADRs supersede each other rather than getting edited — preserves the historical reasoning.
Senior architects make ADR-writing a habit. Without it, architecture drifts; reasons for past decisions get lost. With it, the architecture is auditable.
Common pitfalls:
- Writing them retroactively — captures the decision but not the live reasoning.
- Never updating — Status: "Accepted" forever even when superseded.
- Too long — ADRs are 1-2 pages, not 20.
- Not searchable — buried in hard-to-find Confluence pages.
The discipline pays off measurably over years.