Architecture Decision Records (ADR) Explained
On this page
Why architecture decisions get forgotten
Two years after a decision, a new engineer finds the system uses RabbitMQ for some events and Kafka for others, and proposes consolidating. Nobody remembers why there are two. Maybe there was a good reason, maybe not. The team either spends a week rediscovering it or changes it blindly and learns the hard way. An Architecture Decision Record (ADR) prevents both outcomes by writing the reasoning down when it's fresh. The format was popularized by Michael Nygard in 2011.
What an ADR contains: a template and example
One decision per record, short enough to read in five minutes:
# ADR 0014: Use PostgreSQL row-level security for tenant isolation
Status: Accepted (2026-10-02)
## Context
All tenants share one database. Every query filters by tenant_id in the data-access
layer, but one missed filter would expose another tenant's data. Customers' security
reviews ask how isolation is enforced.
## Options considered
1. Application filtering only (current).
2. Application filtering plus PostgreSQL row-level security (RLS).
3. A separate database per tenant.
## Decision
Option 2. RLS policies on every tenant table, with the tenant id set per transaction (SET LOCAL).
## Consequences
+ A missing WHERE clause can no longer leak data; a second, database-enforced layer.
+ Clear answer for security reviews.
- Every transaction must set the tenant id; a session-level setting would leak across pooled connections.
- Some admin and migration jobs need a role that bypasses RLS, which must be tightly controlled.
- Option 3 stays available for enterprise tenants who require it (see ADR 0021 if adopted).The consequences section is the most valuable part: it records the costs the team knowingly accepted, so nobody later mistakes them for accidents.
ADR best practices
- Store them in the repository next to the code (
docs/adr/0014-tenant-isolation-rls.md), reviewed in pull requests like code. - Number them and never reuse numbers.
- Don't rewrite history. When a decision changes, write a new ADR and mark the old one "Superseded by ADR 0031". The trail of reasoning is the point.
- Write one when a decision is hard to reverse, affects several teams, or the team debated it: a database, a messaging system, an authentication approach, a service boundary, a major library. Not for every small choice.
- Keep them short. A page or two. Tools such as
adr-toolsor Log4brains help, but a Markdown template is enough; MADR is a widely used one. - Start as Proposed. Open the ADR as a pull request with status
Proposed, let the affected teams comment, and merge it asAccepted. The review is where most of the value comes from. - Make important decisions checkable. Where a decision can be tested, add a test. If ADR 0009 says the domain project never references infrastructure, an architecture test with NetArchTest (Day 9) fails the build when someone breaks it. A decision enforced by CI stays true.
Other architecture docs worth keeping: C4 diagrams, runbooks, catalogs
Most architecture documents go stale because nobody owns them. Keep a small set, maintained alongside the code:
- A context and container diagram, for example in the C4 model (Simon Brown): the system in its environment, then its main deployable parts and how they talk. Diagrams as code (Structurizr, Mermaid, PlantUML) are easier to keep current.
- Service catalog entries: owner, purpose, dependencies, runbook, dashboards and SLOs for each service.
- Runbooks for incidents: what this alert means, how to diagnose, how to mitigate.
- API and event schemas, generated from code where possible (OpenAPI, AsyncAPI, a schema registry).
Check yourself
So future readers see what was considered and why each option lost. Without that, someone will re-propose the rejected option a year later without the original context, and the team either repeats the debate or makes the change and rediscovers the problems that ruled it out.
No. ADRs are a record of reasoning at the time. Write a new ADR that explains the new context and decision, mark the old one as superseded with a link to the new one, and leave its text intact so the history of why things changed is preserved.
An automated architecture test that runs in the build, for example with NetArchTest or ArchUnitNET, failing whenever the Domain project references infrastructure packages. Decisions written only in documents drift under deadline pressure; a failing test makes the rule impossible to break silently.
The consequences, because they record the known costs and trade-offs the team accepted, which explains behavior that might otherwise look like a mistake.