The standard ADR template has a flaw that none of the thousand blog posts about it mention: it assumes the decision is already made.
Look at the sections — Context, Decision, Alternatives, Consequences. Every one is written in the past tense of a choice that's over. "We will use Postgres." The template is a machine for documenting your decision at the exact moment it stops being changeable. The hardest part of an architecture decision isn't recording it; it's making it — validating the assumption that Postgres is the right call with the people who'll operate it, build on it, and live with it. The ADR format has no step for that.
We'll fix that gap at the end. First, the template itself — because the format, within its limits, is genuinely excellent, and most teams still manage to botch it.
An Architecture Decision Record is a short document that captures a decision and the reasoning behind it. Not a design doc. Not an RFC. Just: we faced this choice, we considered these options, we picked this one, here's why. The concept comes from Michael Nygard's original 2011 post, and his core insight holds up: decisions are the most important thing to document because they're the hardest to reconstruct later. Code tells you what the system does. ADRs tell you why.
The template
# ADR-[number]: [Title]
**Date:** [Date]
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** [Who made or needs to make this call]
## Context
What is the issue? What forces are at play? Why does this
decision need to be made now?
Keep this to 2-3 paragraphs. Include constraints — technical,
organizational, timeline — that shaped the options.
## Decision
We will [do X].
State it plainly. One or two sentences. If you need a paragraph
to explain the decision, you might be bundling multiple decisions
together.
## Alternatives considered
### [Option A]
[1-2 sentences. Why it was attractive, why we didn't pick it.]
### [Option B]
[Same.]
## Consequences
What becomes easier or harder as a result of this decision?
Include both positive and negative consequences. If there are
follow-up actions, list them.That's it. Four sections. A good ADR takes 15-20 minutes to write and two minutes to read.
What makes this format work
It's short
The biggest reason ADRs fail is that teams make them too long. An ADR is not a design doc. It doesn't need diagrams, API schemas, or rollout plans. It captures the decision and the reasoning. Everything else belongs somewhere else.
If your ADR is longer than a page, either the decision is too big (split it) or you're including implementation details that don't belong.
It's immutable
An accepted ADR doesn't get edited. If a decision is reversed, you write a new ADR that supersedes it. This preserves the historical record — you can see not just what you decided, but what you used to believe and why you changed your mind.
The status field handles this: Superseded by ADR-047 tells you this decision was replaced and where to find the current one.
It captures the "why"
The alternatives section is the most valuable part. Six months from now, someone will look at the system and think "why didn't they just use Redis for this?" The ADR answers that: "We considered Redis. We didn't use it because X and Y. We went with Postgres because Z."
Without this, every new team member re-litigates the same decisions. With it, they can read the reasoning, agree or disagree, and propose a new ADR if the constraints have changed.
Where ADRs live
Two common approaches:
In the repo. A docs/adr/ directory with numbered markdown files. This is the default recommendation and it works well for engineering teams — the ADRs are version-controlled, discoverable, and close to the code.
In a wiki or Notion. Easier for non-engineers to access but harder to keep in sync. Works if your ADRs are mostly about organizational decisions rather than code.
Pick one and be consistent. An ADR that nobody can find is worse than no ADR at all.
Back to the flaw: records aren't conversations
So the format works — as a record. But remember where we started: the template picks up after the decision, and the decision is the hard part.
Before you can write "We will use Postgres," you need input from the people who'll bear the consequences. In practice, teams handle this one of three ways:
- A meeting. Get the relevant people in a room and hash it out. Works, but doesn't scale, and quieter voices get drowned out. (Most of these meetings are avoidable anyway.)
- A shared doc with comments. Write the ADR as a draft, share it, ask for feedback. Better, but the feedback is unstructured and the comments don't map to the actual options on the table.
- Just decide and hope. Write the ADR, mark it Accepted, and find out later that the platform team can't support your choice. This happens far more often than anyone writes down — by design, since the ADR only records the confident version.
The missing step is structured input collection: before the ADR is finalized, specific people weigh in on specific questions, and their responses come back organized by question — not scattered across a comment thread.
Turning an ADR into a living decision
Inkling adds the missing step. You write your ADR as a GitHub issue (the draft, before the decision is made), and Inkling lets you embed questions inline:
- After the Context section: "Is this the right framing of the problem? What constraints are we missing?"
- After each alternative: "Has anyone operated this at our scale? What broke?"
- Before the Decision section: "Given the tradeoffs above, which option do you favor and why?"
You send a scoped link to the deciders listed in the ADR. They read the draft, answer the questions, and their responses come back structured. You see what everyone thinks about each option before you commit.
Then you write the ADR with actual input, not assumptions about what people would have said — and the record you file is worth trusting.