Six months after a decision is made, nobody remembers why. The person who made it has changed teams, the Slack thread is unsearchable, and the next engineer either re-litigates the choice or quietly works around it. An architecture decision record exists to stop that.
What is an architecture decision record?
An architecture decision record (ADR) is a short document capturing a single architecturally significant decision: the context that forced it, the option chosen, and the consequences accepted. It lives in the repository alongside the code it governs, is numbered sequentially, and is never edited after acceptance — only superseded.
The format was introduced by Michael Nygard in 2011 and has become the default convention for lightweight architecture documentation. The core insight is that reasoning decays faster than code, so the reasoning is what you write down.
What goes in an ADR?
Five sections, fitting on one screen. If an ADR runs past a page it is usually several decisions that should be split into separate records.
# 7. Use Postgres row-level security for tenant isolation
Date: 2026-03-14
Status: Accepted
## Context
We are multi-tenant. Tenant data must not leak across accounts. Isolation can
live in the application query layer, in a schema per tenant, or in Postgres
row-level security. We have 4 engineers and expect ~2,000 tenants within a year.
## Decision
Use Postgres row-level security, with a policy on every tenant-scoped table
keyed off a session variable set by the connection pool.
## Consequences
- Isolation is enforced by the database, so an ORM mistake cannot leak data.
- Every new table MUST have a policy; a migration test fails if a tenant-scoped
table has RLS disabled.
- Debugging is harder: queries silently return fewer rows if the session
variable is unset.
- Rules out any client that cannot set session variables.
## Alternatives considered
- Schema per tenant: rejected, 2,000 schemas makes migrations unmanageable.
- Application-layer filtering: rejected, one missed WHERE clause is a breach.When should you write an ADR?
Write one when a decision is expensive to reverse and someone will ask why later. That usually means it changes a boundary: a datastore, a protocol between services, an auth model, a deployment topology, or a dependency you cannot easily remove. Skip it for choices a future engineer can safely change alone.
- Choosing a database, queue or cache — and equally, deciding not to add one.
- Fixing a contract between two services or two teams.
- Adopting or rejecting a framework that will spread across the codebase.
- Accepting a known tradeoff deliberately, such as consistency for latency.
- Reversing an earlier decision, which supersedes the earlier ADR rather than editing it.
The rule that makes ADRs work
Never edit an accepted ADR. If the decision changes, write a new one and mark the old one `Superseded by ADR-0012`. An edited ADR loses the thing that makes it valuable: an accurate record of what was known and believed at the time. A record that is quietly rewritten is not a record.
What makes an ADR useless?
Three failure modes account for nearly every abandoned ADR practice. All come from treating the ADR as documentation to be completed rather than reasoning to be captured.
- Writing it after the fact as a formality. The value is in recording what was genuinely uncertain, not narrating a decision as if it were obvious.
- Omitting the consequences. A decision with no accepted downsides is marketing. The consequences section is what future readers need most.
- Storing them outside the repo. In a wiki they rot and nobody finds them. In docs/adr/ they surface in code review, in grep, and in the diff that changed the thing they govern.
How do ADRs relate to RFCs and design docs?
An RFC or design doc proposes and explores; an ADR records what was settled. They are complementary — a long design doc can end with a two-paragraph ADR that outlives it. The ADR is the durable artefact precisely because it is short enough that people still read it two years later.
Frequently Asked Questions
How long should an ADR be?
One page. Context, decision, consequences, alternatives. If it is longer, it is probably several decisions and should be split into separate records.
Where should ADRs live?
In the repository they govern, conventionally docs/adr/ or docs/decisions/, numbered sequentially. Keeping them in version control means they appear in code review and travel with the code.
Who writes the ADR?
Whoever made the decision, not a designated documentarian. The reasoning is only accurate if it comes from the person who actually held it.
What if we change our minds?
Write a new ADR that supersedes the old one and add a Superseded by line to the original. Never delete or rewrite the original — the history of what you believed is the point.
Do small teams need ADRs?
Small teams need them most. A four-person team has no redundancy of memory: when one person leaves, a quarter of the context leaves with them.
References
- Documenting Architecture Decisions — Michael Nygard / Cognitect
- Architecture Decision Records — ADR GitHub organisation
- Azure Well-Architected Framework — Microsoft Learn
About Jishu Labs
Jishu Labs is a software development company founded in 2016. We build custom software, AI/ML systems, and full-stack web and mobile applications for clients, and we make eight AI tools for software teams.