# Architecture Decision Records: The 1-Page Version

Canonical: https://kaansystems.com/library/one-page-adrs
Topic: Engineering Practice · Published: 2026-05-12 · Updated: 2026-10-12
Summary: Architecture Decision Records are valuable. The canonical Michael Nygard format is also long enough that most teams don't keep up with writing them. The one-page version preserves the value with a tenth of the friction.

## Key takeaways

- The canonical Michael Nygard ADR format, dating to 2011, runs four to six pages — comprehensive, but long enough that most teams never actually write them.
- The one-page ADR is six fields — Title, Status, Context, Decision, Consequences, References — capped at a single screen, with no subsections and no formal status transitions.
- Status has exactly four values: Proposed, Accepted, Superseded by ADR-NNN, and Deprecated. The typical path is Proposed → Accepted, with a small fraction later marked Superseded.
- Write an ADR only when a decision is hard to reverse (more than a week of work to undo), has architectural consequences that aren't obvious from the code, or was contested before being made — skip library versions, implementation details, and anything the code already records.
- ADRs live in the repository under docs/decisions/ as numbered markdown files, so they're versioned alongside the code and survive Confluence migrations, Notion reorganizations, and tool changes.
- When an ADR is superseded, mark the status instead of deleting it — the original reasoning is what lets a future reader avoid recreating the same mistake.

**What is a one-page ADR, and why use it instead of the full format?** A one-page Architecture Decision Record captures a decision in six fields — Title, Status, Context, Decision, Consequences, References — on a single screen. It keeps everything that makes ADRs valuable and drops the ceremony of the four-to-six-page canonical format, so engineers actually write them.

Two decisions that belong in this format the week you make them: [Argo CD versus Flux](/library/argo-cd-vs-flux) and [Control Tower versus Terraform](/library/control-tower-vs-terraform-landing-zone). The [7-day Assessment](/assessment) is where those calls get made against the estate instead of in a thread.

## Why don't engineers write architecture decision records?

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.

## What fits on one page and still gets written?

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.

```mermaid
stateDiagram-v2
  direction LR
  [*] --> Proposed: ADR drafted
  Proposed --> Accepted: decision made
  Proposed --> [*]: discarded before merge
  Accepted --> Superseded: later ADR overrides
  Accepted --> Deprecated: context changed,<br/>no replacement
  Superseded --> [*]
  Deprecated --> [*]

  note right of Superseded
    Keep both ADRs.
    Future readers need
    the original reasoning.
  end note
```

### 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

```mermaid
flowchart TD
  Start[A decision was made]
  Q1{Hard to reverse?<br/>more than 1 week<br/>of work to undo}
  Q2{Architectural<br/>consequences not<br/>obvious from code?}
  Q3{Was it contested<br/>before being made?}
  Q4{Will it stabilize<br/>within 3 months?}

  Start --> Q1
  Q1 -- no --> SKIP[Skip — code is the record]
  Q1 -- yes --> Q2
  Q2 -- no --> Q3
  Q2 -- yes --> WRITE[Write the ADR]
  Q3 -- yes --> WRITE
  Q3 -- no --> Q4
  Q4 -- no --> WAIT[Wait — revisit when stable]
  Q4 -- yes --> WRITE

  classDef yes fill:#1F4A3E,stroke:#3FA585,stroke-width:2px;
  classDef no  fill:#0a1612,stroke:#2E8B6F,stroke-width:1px;
  classDef q   fill:#0d1f1a,stroke:#3FA585,stroke-width:1.5px;
  class Start,Q1,Q2,Q3,Q4 q;
  class WRITE yes;
  class SKIP,WAIT no;
```

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`:

```markdown
# 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.

## Frequently asked questions

**Q: What is a one-page ADR?**

A one-page ADR is an Architecture Decision Record compressed to six fields — Title, Status, Context, Decision, Consequences, References — that fits on a single screen. It keeps everything that makes ADRs valuable and drops the ceremony of the canonical four-to-six-page format.

**Q: Why don't engineers write traditional ADRs?**

The canonical Michael Nygard format runs four to six pages, which feels disproportionate to most decisions and implies more formality than how decisions actually get made. By the time someone has time to write the full version, the decision is weeks old and the context is gone.

**Q: When should I write an ADR?**

Write one when a decision is hard to reverse (more than a week of work to undo), has architectural consequences that aren't obvious from the code, or was contested before being made. Don't write one for library versions, implementation details, or anything fully captured in code or config.

**Q: Where should ADRs be stored?**

In the repository, under docs/decisions/ as numbered markdown files like 0001-use-postgres.md. Keeping them with the code means they're versioned alongside it and survive Confluence and Notion migrations. Tools like adr-tools and log4brains help but are optional.

**Q: What are the four ADR statuses?**

Proposed, Accepted, Superseded by ADR-NNN, and Deprecated. That is the entire state machine — no rejected, no under review — and the typical path is Proposed → Accepted, with a small fraction eventually marked Superseded.

**Q: What happens to an ADR when the decision changes?**

Don't delete it. Mark the status as Superseded (or Deprecated) and keep both records in the repo. The original reasoning is part of the value: months later someone can read why the earlier decision was made and avoid recreating the same mistake.

Template: "1-page ADR markdown template" — branded PDF at https://kaansystems.com/templates/one-page-adrs.pdf

Source: https://kaansystems.com/library/one-page-adrs · Work with Kaan Systems: https://kaansystems.com/contact