The Problem
Architecture Decision Records are one of the best ideas in software engineering documentation. They capture why a system is built the way it is. Not what it does. What was decided, and what was rejected.
The problem is that the canonical Michael Nygard format, dating to 2011, runs four to six pages: full context, complete options analysis, multi-paragraph consequences, formal status with state transitions. Comprehensive. Useful as a reference. Almost never written.
Engineers don’t write ADRs because:
- The format implies a level of formality that doesn’t match how decisions actually get made.
- A four-page ADR feels disproportionate to most decisions.
- Reviewing a four-page ADR is its own effort.
- By the time you have time to write the full version, the decision is six weeks old and the context is gone.
The fix is a shorter format. The one-page ADR keeps every component that makes ADRs valuable, drops everything that’s optional or ceremonial, and fits in a single screen.
The Approach
Six fields. Maximum one screen. No subsections. No formal status transitions. No optional fields. The shape is the contract.
Field 1: Title
Numbered, present tense. The number is monotonic across the repo’s history (ADR-001, ADR-002, …). The title states the decision affirmatively, not the question:
Bad: ADR-007: How should we handle async jobs? Good: ADR-007: Use SQS + Lambda for asynchronous job processing
A reader scanning the index should be able to know the decision from the title alone.
Field 2: Status
One of four values:
- Proposed. Under discussion. The ADR exists but the decision isn’t made.
- Accepted. Decision made, no superseding decision yet.
- Superseded by ADR-NNN. A later ADR overrides this one. Both stay in the repo.
- Deprecated. The decision no longer applies (system retired, constraint changed) but no new decision replaces it.
That’s the entire state machine. No “rejected.” No “under review.” No nesting. The typical path is Proposed → Accepted, with a small fraction eventually marked Superseded.
Field 3: Context
Three to four sentences. What’s the situation that requires a decision? What forces are at play? No history lesson, no scope justification, no roadmap context.
Bad: “Our system has been growing for two years. As traffic increased, we noticed that synchronous calls to our PDF rendering service started to time out. We had a meeting where we discussed several options including…” Good: “PDF rendering takes 5-30 seconds per request. Synchronous handling causes p95 latency violations and ties up application threads. We need an async path.”
If you can’t make the context fit in four sentences, the decision is probably actually two decisions.
Field 4: Decision
One sentence. State the decision, not the deliberation.
Bad: “After considering Lambda, ECS, and self-hosted workers, we decided that SQS + Lambda was the best option because…” Good: “Render PDFs via SQS + Lambda, with the queue fronted by an API Gateway endpoint.”
The reasoning belongs in Consequences, not Decision. The Decision field is the answer; everything else is supporting.
Field 5: Consequences
Three bullets. Positive, negative, neutral. Each bullet is one sentence.
Positive: Application threads released immediately; horizontal scale is automatic. Negative: Lambda cold starts add 200-400ms to first-request latency. Neutral: Operational visibility shifts from APM to CloudWatch Logs + queue metrics.
Three bullets forces honesty. You can’t write three meaningful positive bullets if the decision has only two real upsides, and you can’t hide the downsides when the negative bullet has to be substantive.
Field 6: References
Links. PRs that implement the decision, related ADRs, external documentation, design docs. Bulleted list, no annotations needed: the link text or URL is enough.
If there are no references, leave the field blank with the heading present (so the template stays consistent across ADRs).
When to Write an ADR — and When Not To
Write one when:
- The decision is hard to reverse cheaply. “Hard” here means more than a week of engineering work to undo.
- The decision has architectural consequences that aren’t obvious from the code alone.
- A future engineer reading the codebase will ask “why is it like this?”
- The decision was contested in any way before being made.
Don’t write one for:
- Library versions or framework choices that you’d swap in a sprint.
- Implementation details (variable naming, function structure, file layout).
- Anything fully captured in code or config. The code is the record.
- Decisions you’re going to revisit in three months. Wait until they stabilize.
The hardest rule to enforce is the first one. Engineers tend to write ADRs for every meaningful decision rather than only the consequential ones. That’s a learnable habit, and the cost of one too many is much lower than the cost of skipping the one that mattered.
Where ADRs Live
In the repository. Specifically, in docs/decisions/, as numbered markdown files: 0001-use-postgres.md, 0002-async-jobs-via-sqs-lambda.md, etc.
The repo is the right home because:
- The decisions are versioned alongside the code they describe.
- The Pull Request that implements the decision can reference the ADR by file path.
- A new engineer reading the codebase finds the ADRs in the natural place.
- The ADRs survive Confluence migrations, Notion reorganizations, and tool changes.
There are tools (adr-tools, log4brains) that automate ADR numbering and templating. They’re helpful but optional. Markdown files in docs/decisions/ work fine with no tooling at all.
The Template
The single-page format, copy-pasteable into a new docs/decisions/NNNN-short-title.md:
# ADR-NNNN: <Decision in present tense>
## Status
Proposed | Accepted | Superseded by ADR-NNNN | Deprecated
## Context
<3-4 sentences. What's the situation? What forces require a decision now?>
## Decision
<One sentence. The decision itself.>
## Consequences
- **Positive:** <one sentence>
- **Negative:** <one sentence>
- **Neutral:** <one sentence>
## References
- <PR link>
- <Related ADR>
- <External documentation>That’s the entire format. Six headings, four to six fields filled in, total length under a screen on a normal monitor.
Operating Notes
Make ADRs part of the PR template for significant changes. The PR template includes a line like “Does this require an ADR? If yes, link the file.” That single question catches the changes that should have one.
In code review, ask for ADRs the way you ask for tests: not for every change, but for changes where the absence is conspicuous. “Why is this a separate service?” usually means an ADR is missing.
When an ADR is superseded, don’t delete it. Mark the status. The history is part of what makes ADRs valuable. Six months from now, someone reads ADR-007 (superseded), realizes the original reasoning, and avoids recreating the same mistake.
The first month after introducing the practice, expect the team to write three or four ADRs. The second month, fewer. They’ve learned what counts. By month six, you have a small library of decisions that captures the architectural skeleton of the system in a form that’s still readable three years and three engineering generations later.