Quick Navigation
- Start here — The problem ADRs solve
- What an ADR is
- When to write one
- The process
- Where ADRs live
- Integrating ADRs into workflow
- When ADRs go wrong
- Putting it all together
- Cheat sheet
Before we start — the one thing to hold onto
Undocumented decisions become tribal knowledge — debated again six months later by people who weren't in the room. I've sat in meetings where teams spent an hour re-debating a decision that was already made, documented nowhere, and the person who made it had left the company three months ago.
An ADR (Architecture Decision Record) is a short document that captures an important architectural decision — the context, the options considered, the choice made, and the consequences.
ADRs are decision receipts. Proof of what was decided and why. Fifteen minutes of writing saves hours of re-debate.
Keep it in mind.
1. The problem — Tribal knowledge and decision debt
Architecture decisions are made in meetings, in corridors, in Slack threads. They live in people's heads. When those people leave, the decisions are lost.
Without documentation, decisions become tribal knowledge. New team members can't understand why things are the way they are. Old decisions get re-debated. Contradictory decisions get made because no one remembers the original.
The signs:
- "Why did we choose Kafka over RabbitMQ?" — "I think Sarah decided that, but she left."
- "We decided to use microservices" — "When? Who approved that?"
- "The architecture says X but the code does Y" — no one documented the change.
- Every new architect wants to revisit past decisions because they have no context.
flowchart LR
UNDOC["Undocumented\nDecision"] --> TRIBAL["Tribal Knowledge\nOnly in people's heads"]
TRIBAL --> DEBATE["Re-debated\nEvery 6 months"]
TRIBAL --> CONTRADICT["Contradicted\nConflicting decisions"]
TRIBAL --> LOST["Lost\nWhen people leave"]
Here's the part that catches teams out: decision debt is a form of technical debt. But it's about knowledge, not code. The cost compounds — undocumented decisions make future decisions harder.
Undocumented decisions = technical debt in knowledge form.
Try it yourself — The decision debt audit
Think of three decisions your team made in the last year. For each one:
| Decision | Is it documented? | Could a new joiner find the rationale? |
|---|---|---|
| e.g. Chose PostgreSQL over MongoDB | No — it was a Slack conversation | No — they'd have to ask someone who was there |
If your answers are mostly "no," you're carrying decision debt. Every re-debate is the interest payment.
2. What an ADR is — Context, options, decision, consequences
Architecture documentation is often either too heavy (50-page documents no one reads) or too light (a Slack message that disappears).
ADRs find the sweet spot — lightweight enough to write quickly, structured enough to be useful, and durable enough to last.
An ADR captures four things:
Context — what situation required a decision? What forces are at play? Options — what alternatives were considered? What were the pros and cons of each? Decision — what was chosen? State it clearly and concisely. Consequences — what does this enable and constrain? What are the positive and negative outcomes?
flowchart TD
ADR["ADR"]
ADR --> C["Context\nWhat situation\nrequired this?"]
ADR --> O["Options\nWhat alternatives\nwere considered?"]
ADR --> D["Decision\nWhat was chosen?"]
ADR --> CO["Consequences\nWhat does this\nenable and constrain?"]
ADRs have a status lifecycle. Proposed — under review. Accepted — active decision. Deprecated — no longer recommended. Superseded — replaced by a new ADR. This means ADRs are living documents — they can evolve as context changes.
An ADR captures context, options, decision, and consequences — nothing more.
Try it yourself — The ADR draft
Take a recent decision from your team. Draft an ADR for it in under 15 minutes:
| Section | Your answer |
|---|---|
| Context | What situation required this decision? |
| Options | What alternatives did you consider? |
| Decision | What did you choose? |
| Consequences | What does this enable? What does it constrain? |
If you can't fill in all four sections, the decision wasn't fully thought through. That's valuable to know.
3. When to write one — The significance threshold
Not every decision needs an ADR. Writing one for every technology choice creates documentation fatigue.
You need a threshold — which decisions are significant enough to document?
The threshold: decisions that are costly to change, affect multiple teams, or set a precedent.
Write an ADR when:
- The decision affects multiple services or teams
- The decision is costly to reverse
- The decision sets a precedent for future decisions
- The decision involves a significant trade-off
- The decision will be questioned by future team members
- The decision is required for compliance or audit
Don't write an ADR for:
- Decisions that are easily reversible
- Decisions that affect only one team
- Decisions that are implementation details, not architectural choices
- Decisions that are already documented elsewhere
flowchart TD
DEC["Decision Made"] --> SIGN{"Significant?"}
SIGN -->|"Multi-team impact"| ADR["Write ADR"]
SIGN -->|"Costly to reverse"| ADR
SIGN -->|"Sets precedent"| ADR
SIGN -->|"Significant trade-off"| ADR
SIGN -->|"Will be questioned"| ADR
SIGN -->|"Compliance required"| ADR
SIGN -->|"Reversible"| SKIP["Don't write ADR"]
SIGN -->|"Single team"| SKIP
SIGN -->|"Implementation detail"| SKIP
Here's the quick test. Will this affect more than one team? Would reversing this take more than one sprint? Does this set a precedent for future decisions? Is there a significant trade-off being made? Will someone ask "why did we do this?" within six months? Answer yes to any one — write the ADR.
Write ADRs for decisions that are costly to change or affect multiple teams.
Try it yourself — The significance test
Think of three recent decisions. Run them through the test:
| Decision | Multi-team? | Costly to reverse? | Sets precedent? | Write ADR? |
|---|---|---|---|---|
| e.g. Chose Kafka for event streaming | Yes — 3 teams consume events | Yes — migration would take months | Yes — sets event-driven precedent | Yes |
If you're unsure, write the ADR. It's better to over-document than to lose context.
4. The process — Draft, review, approve, communicate, maintain
Who drafts? Who reviews? Who approves? Without a process, ADRs either don't get written or don't get followed.
The process must be lightweight enough to be followed and structured enough to produce quality decisions.
Draft — the person closest to the decision writes the ADR. Review — affected teams and architects review and challenge. Approve — designated authority accepts the decision. Communicate — the decision is shared with all affected parties. Maintain — the ADR is updated when context changes.
flowchart LR
DRAFT["1. Draft\nPerson closest\nto the decision"] --> REVIEW["2. Review\nAffected teams\n+ architects"]
REVIEW --> APPROVE["3. Approve\nDesignated\nauthority"]
APPROVE --> COMM["4. Communicate\nShare with all\naffected parties"]
COMM --> MAINTAIN["5. Maintain\nUpdate when\ncontext changes"]
For small teams, the lightweight process works: author drafts ADR in 15-30 minutes, opens a PR to the architecture repo with reviewers tagged, reviewers comment asynchronously in 1-3 days, author accepts or lead architect approves, merge to repo — decision is active.
For larger organisations, the formal process: author drafts ADR, presents to Architecture Board in scheduled review, board challenges options and trade-offs, board decides — accept, reject, or request changes, log in Decision Register, communicate to all affected teams, review at next cycle.
ADR process = draft, review, approve, communicate, maintain.
Try it yourself — The process fit
Which process fits your team?
| Question | Your answer |
|---|---|
| How many teams would be affected by an architecture decision? | |
| Do you have an Architecture Board or similar review body? | |
| Can decisions be reviewed asynchronously via PR? | |
| How long does it typically take to get a decision approved? |
If you're under five teams, use the lightweight process. Over five, you need something more formal.
5. Where ADRs live — In version control, close to the code
ADRs stored in a wiki no one checks, or in a shared drive no one navigates, don't influence decisions.
ADRs should live where the decisions matter — close to the code they affect, in version control, alongside the systems they describe.
Best practices:
In the repository — alongside the code the decision affects. In version control — so changes are tracked and reviewable. With an index — so people can find decisions easily. Numbered sequentially — so references are unambiguous. In markdown — so they are readable in any tool.
repository/
├── docs/
│ └── architecture/
│ └── adr/
│ ├── 0001-use-event-driven-integration.md
│ ├── 0002-choose-postgresql-for-orders.md
│ ├── 0003-adopt-c4-model-for-documentation.md
│ └── README.md (index)
├── src/
│ └── ...
In-repository ADRs integrate with existing developer workflows — PRs, code review, version control. The numbering convention makes ADRs referenceable — "see ADR-0017" is unambiguous. ADRs in version control mean you can see the history of a decision — when it was proposed, accepted, deprecated.
ADRs live in version control, close to the code they affect.
Try it yourself — The findability test
If a new joiner asked "why did we choose X?" — how long would it take them to find the answer?
| Storage location | Time to find | Would a new joiner know to look there? |
|---|---|---|
| e.g. Wiki nobody updates | Hours — if they know it exists | No |
| e.g. In repo docs/adr/ | Minutes — linked from README | Yes — if onboarding points to it |
If your answer isn't "minutes," your ADRs aren't findable. Fix that first.
6. Integrating ADRs into workflow — Part of the workflow, not outside it
ADRs that sit outside the workflow don't get written and don't get read.
ADRs must be part of how teams work — sprint planning, code review, onboarding, and architecture reviews.
Sprint planning — when a story requires an architecture decision, write the ADR first. Code review — when code implements an ADR, verify it matches the decision. Onboarding — new team members read the ADR log to understand past decisions. Architecture reviews — reviews check that decisions are documented. Incident review — when incidents reveal wrong decisions, update or deprecate the ADR.
flowchart TD
ADR["ADRs"] --> SP["Sprint Planning\nDecision before implementation"]
ADR --> CR["Code Review\nVerify implementation matches decision"]
ADR --> ON["Onboarding\nNew joiners read decision log"]
ADR --> AR["Architecture Reviews\nCheck decisions are documented"]
ADR --> IR["Incident Review\nUpdate decisions when context changes"]
The flywheel effect: write ADRs when decisions are made. Read ADRs when joining or questioning. Build trust — decisions are documented. More ADRs — teams see the value. Repeat.
ADRs must be part of the workflow — not outside it.
Try it yourself — The integration check
Where could ADRs plug into your current workflow?
| Process | Current state | ADR integration |
|---|---|---|
| Sprint planning | Decisions made during implementation | ADR must be accepted before implementation starts |
| Code review | No check against architecture decisions | Reviewers verify code matches ADR |
| Onboarding | "Ask someone who's been here a while" | Read ADR log as first-week activity |
Pick one. What would it take to integrate ADRs there?
7. When ADRs go wrong — The anti-patterns
ADRs can be done badly — too heavy, too vague, too rigid, or too ignored.
Anti-patterns undermine the value of ADRs and create the documentation fatigue that makes teams abandon the practice.
The novel — ADRs that are 10 pages long; no one reads them. The vague — "We chose microservices because they are better" — no rationale, no options. The museum — ADRs that are never updated; decisions from 3 years ago that no longer apply. The rubber stamp — ADRs written after the decision was already implemented; documentation theatre. The silo — ADRs that only architects write; teams have no ownership. The gate — ADRs required for every trivial decision; documentation becomes a bottleneck.
flowchart TD
ANTI["ADR Anti-patterns"]
ANTI --> NOVEL["The Novel\n10 pages, no one reads"]
ANTI --> VAGUE["The Vague\nNo rationale, no options"]
ANTI --> MUSEUM["The Museum\nNever updated"]
ANTI --> STAMP["The Rubber Stamp\nWritten after implementation"]
ANTI --> SILO["The Silo\nOnly architects write"]
ANTI --> GATE["The Gate\nRequired for everything"]
NOVEL --> FIX["Fix: Keep it short\n1-2 pages max"]
VAGUE --> FIX
MUSEUM --> FIX2["Fix: Review quarterly\nDeprecate stale decisions"]
STAMP --> FIX3["Fix: Write before\nimplementation"]
SILO --> FIX4["Fix: Anyone can\nauthor an ADR"]
GATE --> FIX5["Fix: Threshold for\nsignificance"]
ADR anti-patterns undermine the practice — keep them short, relevant, and current.
Try it yourself — The health check
Run your ADR practice through the health check:
| Question | Your answer |
|---|---|
| Are ADRs under 3 pages? | |
| Do ADRs list options and trade-offs? | |
| Are ADRs reviewed quarterly? | |
| Can anyone author an ADR? |
Any "no" means your ADR practice has a problem. Fix the first "no" you find.
Putting it all together
Here's the complete picture in one diagram. This is the mental model worth internalising.
flowchart TD
PROBLEM["Problem:\nTribal Knowledge\nDecisions lost,\nre-debated, contradicted"]
PROBLEM --> SOLUTION["Solution:\nADRs"]
SOLUTION --> WHAT["What to Capture\nContext, options,\ndecision, consequences"]
SOLUTION --> WHEN["When to Write\nSignificant decisions\nonly"]
SOLUTION --> WHO["Who Drafts\nPerson closest\nto the decision"]
SOLUTION --> WHERE["Where They Live\nIn version control,\nclose to code"]
SOLUTION --> HOW["How to Integrate\nSprint planning,\ncode review, onboarding"]
WHAT --> VALUE["Value\nShared understanding\nReduced re-debate\nFaster onboarding"]
WHEN --> VALUE
WHO --> VALUE
WHERE --> VALUE
HOW --> VALUE
The foundation:
Undocumented decisions become tribal knowledge — re-debated, contradicted, and lost when people leave. ADRs are lightweight — context, options, decision, consequences; 15 minutes to write, hours of re-debate saved. Integrate into workflow — ADRs must be part of sprint planning, code review, and onboarding, not outside them. ADRs are decision receipts. Write them close to the code. Keep them short. Review them regularly.
Cheat Sheet — All the key terms
| Concept | One-Line Memory | Key Action |
|---|---|---|
| Decision debt | Undocumented decisions cost later | Identify and document significant decisions |
| ADR format | Context, options, decision, consequences | Use the template — keep it under 3 pages |
| When to write | Significant decisions only | Multi-team impact, costly to reverse, sets precedent |
| Process | Draft, review, approve, communicate | Match formality to organisation size |
| Storage | In version control, close to code | docs/architecture/adr/ with numbered files |
| Integration | Part of the workflow | Sprint planning, code review, onboarding |
| Anti-patterns | Common mistakes to avoid | Keep short, require options, review quarterly |
How to know if this landed
You'll know this has landed when someone stops re-debating old decisions and starts looking up the ADR. They can explain what an ADR is and why it matters. They know when to write one — and when not to. They can draft an ADR using the template in under 30 minutes. They store ADRs in version control with proper indexing. They integrate ADRs into sprint planning and code review. And they review ADRs quarterly — deprecating stale decisions.
What changes when the mental model clicks
I've run this session with teams who spent hours re-debating decisions that were already made. The gap at the start is usually not about documentation — it's about not having a lightweight mechanism that captures what matters.
What changes after this session:
Teams stop re-debating old decisions and start looking up the ADR. The decision debt audit — "could a new joiner find the rationale?" — is always the moment things click. People stop treating ADRs as bureaucracy and start treating them as decision receipts. Their results get better. They stop blaming tribal knowledge when the real problem was that nobody wrote the decision down.
The ADR draft exercise tends to immediately change how teams think about their decisions. They start noticing that many decisions weren't fully thought through — they couldn't fill in all four sections. Their decisions get better. They stop making choices by accident when the real problem was that they never considered the alternatives.
Book a Workshop
Ready to introduce ADRs in your organisation?
or
Half-day workshop includes ADR writing exercise with real decisions from your team, template customisation for your organisation, process design — lightweight or formal, matching your context, integration planning — sprint, review, onboarding, anti-pattern identification and avoidance, and ADR template + decision log + rationale guide.