Small teams make architecture decisions constantly: which database to use, how services talk to each other, how to structure a monolith, how to handle retries, where to put permissions checks. The problem is not making decisions. The problem is that the reasons disappear.
Six months later, someone asks, “Why did we do it this way?” and you get a mix of vague memories, half-true folklore, and a Slack thread nobody can find. That is how teams accidentally re-litigate the same choices, or “simplify” away critical constraints.
Architecture Decision Records (ADRs) are a low-effort way to capture the why behind the decisions that shape your system. You do not need a heavyweight process. You need a consistent habit.
What an ADR is (and what it is not)
An ADR is a short document that records a significant technical decision, the context that led to it, and the consequences you accept by choosing it. Think of it as a durable “commit message for architecture.”
ADRs are not design docs for every feature. They are not meeting notes. They are not long proposals. Their purpose is to make a decision understandable later, especially to someone who did not participate at the time.
- Good ADR: “We will use database-level unique constraints for idempotency keys because we need correctness under concurrency; we accept a small increase in write latency.”
- Not an ADR: “Here is every possible idempotency approach and a survey of academic literature.”
In practice, ADRs help teams in two ways: they create a shared memory, and they improve decision quality by forcing clarity before you ship.
When ADRs pay off
Not every choice deserves an ADR. You will get the most value when the decision is hard to reverse, hard to test, or likely to be questioned later.
Write an ADR when at least one of these is true:
- It changes system shape: new service boundaries, new data model, new integration pattern.
- It adds an operational commitment: background jobs, message queues, caching tiers, scheduled tasks.
- It affects security or compliance posture: auth model, secrets handling, auditing approach.
- It introduces a non-obvious constraint: “We must do X because the vendor API behaves like Y.”
- It creates long-term coupling: frameworks, persistence layer, schema design, shared libraries.
If you maintain an engineering handbook or internal wiki, ADRs also serve as a map for “how this system thinks.” They complement your README files, runbooks, and onboarding docs.
A lightweight ADR format that works
The best ADR template is the one your team will actually use. Keep it short enough that creating one feels easier than arguing in chat for an hour.
Recommended fields
Here is a minimal structure that covers what future readers need:
Title: Short decision name
Status: Proposed | Accepted | Superseded
Context: What problem and constraints exist?
Decision: What we chose (one clear sentence)
Consequences: What becomes easier/harder now?
Alternatives: What we didn't choose (1-3 bullets)
Links: Relevant tickets/docs (optional)Notes on using it well:
- Context should include constraints that are easy to forget: traffic profile, team size, vendor limitations, operational maturity.
- Decision should be specific enough to implement. “Use microservices” is not a decision. “Split email sending into a separate worker service that consumes a queue” is.
- Consequences should be honest. Every choice has tradeoffs; writing them down prevents surprise later.
- Alternatives do not need a debate transcript. Just record the most plausible other paths and why they were rejected.
Where to store ADRs
For small teams, the most effective storage is the same place you store code: a folder in the repo. That keeps ADRs close to the implementation and makes them easy to review alongside changes. A simple convention is /docs/adr/ with numbered files.
If your organization has multiple repos, you can keep ADRs per system, plus a small set of “org-wide” ADRs in a central repo. The key is to make them discoverable and to avoid duplicating decisions across scattered tools.
A simple workflow for creating and maintaining ADRs
ADRs are most useful when they are part of normal delivery, not a side project. The workflow below keeps the overhead low.
- Trigger: During planning or implementation, someone notices a decision with long-term impact.
- Draft: Write a 10 to 20 minute draft using the template, ideally in the same pull request that introduces the change.
- Review: Ask reviewers to focus on clarity: is the context complete, is the decision unambiguous, do consequences match reality?
- Accept: Merge the ADR with status “Accepted.” If the decision is still being evaluated, mark it “Proposed.”
- Revisit: When you change course, do not rewrite history. Create a new ADR that “Supersedes” the old one.
Key Takeaways
- Write ADRs for decisions that are costly to reverse, easy to forget, or likely to be questioned later.
- Keep ADRs short: context, decision, consequences, and a few alternatives are usually enough.
- Store ADRs with code and review them like code so they stay current and discoverable.
- When decisions change, supersede rather than edit old ADRs to preserve a clear timeline.
A checklist you can copy
Before you mark an ADR “Accepted,” run through this quick checklist:
- Does the title describe the decision, not the problem?
- Is the decision stated in one clear sentence?
- Does the context include constraints (scale, latency, staffing, vendor quirks)?
- Did you list at least one realistic alternative and why it was not chosen?
- Are consequences concrete (operational work, performance impact, failure modes)?
- Could a new teammate implement or maintain this choice using only this ADR and the code?
Real-world example: picking a job queue approach
Imagine a three-person product team building a SaaS app. They need background jobs for sending emails, resizing uploads, and syncing with a partner API. They have two options:
- Option A: Use the primary database table as a simple job queue (polling + status fields).
- Option B: Introduce a dedicated queue system and workers.
They choose Option A, but with guardrails: limit throughput expectations, add database indexes, and enforce a maximum number of retries. The ADR might include:
- Context: Low job volume at launch, small team, desire to avoid additional infrastructure and on-call complexity.
- Decision: Implement a database-backed job queue with a single worker process and explicit retry limits.
- Consequences: Simplifies deployment and observability initially, but risks contention on the primary database and may require migration later if job volume grows.
- Alternatives: Dedicated queue with workers (rejected due to operational overhead); fully synchronous processing (rejected due to timeouts and poor user experience).
Six months later, volume increases and the queue begins to contend with user traffic. A new ADR supersedes the old one: they introduce a dedicated queue, with a measured migration plan. Because the original ADR documented the constraint (“small team, low volume”), nobody feels like the team “made a mistake.” It was a reasonable decision for the context.
Common mistakes (and how to avoid them)
Most ADR failures come from making them too heavy, too vague, or too disconnected from real work.
- Writing essays. If an ADR takes hours, people stop doing them. Keep it short, link to deeper docs only when needed.
- Recording conclusions without context. “We chose PostgreSQL” is not helpful unless you include the constraints that mattered.
- Capturing team politics. ADRs should document engineering reasoning, not interpersonal conflict or vote counts.
- Never superseding. Teams quietly drift and the ADR folder becomes a museum. When you change course, create a new ADR that points to the old one.
- Overusing ADRs. If everything is an ADR, nothing is. Save them for decisions with real staying power.
A good litmus test is this: if you cannot imagine a future teammate asking “why did we do that?”, it probably does not need an ADR.
When not to use ADRs
ADRs are a tool, not a virtue. There are times when they add friction without enough value.
- Purely tactical choices: renaming variables, selecting a small library for a one-off script, adjusting CSS.
- Decisions that will be thrown away soon: short-lived prototypes where the whole point is to learn quickly.
- When you lack decision authority: if the choice is mandated by a platform team or customer requirement, document the constraint, but do not pretend it was an internal decision.
- When you already have an appropriate artifact: some decisions are best captured in a runbook, API spec, or system diagram instead.
If you are unsure, start with a “Proposed” ADR. If the decision becomes important, you can accept it. If it stays minor, you can drop it with minimal cost.
FAQ
How long should an ADR be?
Typically 200 to 600 words. If you need more, try splitting: keep the ADR focused on the decision and link to a deeper design doc stored in the repo.
Who should write the ADR?
The person doing the work should draft it, because they are closest to the constraints and implementation details. Reviewers then improve clarity and challenge assumptions.
Should we require ADRs for every architectural change?
No. Requiring ADRs for everything often creates performative paperwork. Instead, define a rule of thumb such as: “If the decision affects data model, boundaries, reliability, or security, write an ADR.”
What if we made the wrong decision?
That is normal. Create a new ADR that supersedes the prior one, document what changed in the context, and move forward. The goal is not to prove you were right. The goal is to preserve reasoning and reduce churn.
Conclusion
Lightweight ADRs give small teams a durable memory: what you decided, why you decided it, and what tradeoffs you accepted. The format can be simple, but the payoff is real: faster onboarding, fewer circular debates, and more confident evolution of the system.
If you want to start tomorrow, create a /docs/adr/ folder, pick a minimal template, and write one ADR for the next decision that feels “sticky.” Consistency beats perfection.