Photo via Unsplash
Six months into a project, a senior engineer asks: “Why are we using Kafka here instead of a simple job queue? This feels like overkill.”
Nobody on the team knows. The original architect left eight months ago. There’s no documentation. The decision could have been brilliant foresight, or it could have been cargo-culting because someone read a Netflix blog post. No one can tell.
This situation — repeated daily in engineering teams everywhere — is exactly what Architecture Decision Records (ADRs) prevent.
What Is an ADR?
An ADR is a short document that captures a single architectural decision: what you decided, why you decided it, and what alternatives you considered. It’s usually 200–500 words, stored in the repository alongside the code it describes.
That’s it. The entire concept fits in a sentence. The value is disproportionate to the effort.
The Standard ADR Format
There are many ADR templates. We use a simple five-section format that covers everything important without creating documentation overhead:
When to Write an ADR
Not every decision needs an ADR. Apply the “if someone asks why in 6 months” test: if you can imagine a reasonable engineer asking “why did we do this?” and the answer not being immediately obvious from the code — write an ADR.
Always write ADRs for:
- Technology or framework selections
- Database choices
- API design patterns
- Security architecture decisions
- Infrastructure choices (cloud provider, service topology)
- Decisions that explicitly reject an obvious alternative
- Decisions made under constraints that may later change
You probably don’t need ADRs for:
- Implementation details that are clear from the code
- Decisions that can be changed trivially without side effects
- Purely stylistic choices covered by a style guide
The Hidden Value: Onboarding
The immediate benefit of ADRs is obvious — you don’t lose institutional knowledge when people leave. The less obvious benefit is onboarding.
When a new engineer joins and sees an unfamiliar pattern, their first question is “why does it work this way?” Without ADRs, they either ask a senior engineer (interrupting them) or make assumptions (dangerous). With ADRs, they can find the answer themselves and understand the reasoning.
This changes how new engineers engage with the codebase. Instead of assuming the existing architecture is arbitrary or wrong, they see it as a set of deliberate decisions — decisions they can now engage with critically because they understand the original intent.
ADRs Are Not Immutable
A common objection: “If we write ADRs, engineers will feel locked into decisions.” This misunderstands the point.
ADRs document decisions, they don’t freeze them. When a decision needs to be revisited, you write a new ADR. The old ADR gets status “Superseded by ADR-015” and a link to the new one. The history is preserved; the present is updated.
This actually makes it easier to change decisions well. Instead of quietly rearchitecting something and hoping nobody notices the inconsistency, the change is explicit, documented, and understood by the team.
Tooling
ADRs don’t need special tooling. A folder in your repository — typically docs/decisions/ or docs/adr/ — with numbered Markdown files is all you need.
If you want structured tooling, adr-tools (command-line) generates numbered files from templates and manages the status links automatically. For teams using Confluence or Notion, a page per decision in a dedicated space works fine — the important thing is that they’re findable, not where they live.
The ROI Is Undeniable
We’ve seen teams that have been using ADRs for two years move faster than teams that don’t — not slower. Onboarding new engineers takes weeks instead of months. Architecture reviews are more productive because the context already exists. Decisions don’t get relitigated.
The investment is one 20-minute document per significant decision. The return is compounding institutional knowledge that survives team changes, reorgs, and the inevitable turnover that comes with any growing engineering organization.
Start today. Your future self will be grateful.