Topic: adr template markdown

ADR Template in Markdown — Copy-Paste Ready

A short, opinionated Markdown ADR template you can drop into your repo in 30 seconds. Based on Nygard's 5-section format, trimmed to the parts teams actually fill out.

TL;DR

Copy the template below into doc/decisions/0001-use-postgres-over-mongodb.md. Fill in the five sections: Title, Status, Context, Decision, Consequences. Keep it under 250 words. One-liner to set up the folder structure:

mkdir -p doc/decisions && \
  curl -o doc/decisions/0000-template.md https://whychose.com/assets/adr-template.md

The template

# 0001. <Short title that describes the decision>

**Date:** 2026-04-24
**Status:** Accepted
**Deciders:** @your-handle, @reviewer-1, @reviewer-2
**Supersedes:** —
**Superseded by:** —

## Context

What forces are at play? What problem are we trying to solve? Include
anything a future reader needs to understand why this decision mattered
at the time — team size, scale assumptions, tech constraints, deadlines.
2–4 sentences.

## Decision

The choice, in one sentence: "We will use X."

Then a short paragraph on how we'll use it.

## Alternatives considered

- **Y** — rejected because <one-line reason>
- **Z** — rejected because <one-line reason>

## Consequences

### Positive
- What this unlocks.
- What it makes easier.

### Negative
- What trade-off we're accepting.
- What we'll have to revisit later.

### Neutral
- What this doesn't change.

## Links

- PR: #123
- Related ADR: [0007. Caching strategy](0007-caching-strategy.md)
- Original discussion: <chat link, Slack link, or design doc URL>

Why this shape

Three choices are worth calling out, because most ADR templates get them wrong:

Alternatives is a required section, not optional. An ADR without alternatives is a one-sided decision. Six months from now, the reader needs to know what you didn't pick and why — that's most of the audit-trail value.
250-word cap. Long ADRs don't get read. Nygard's original post in 2011 was explicit about this; teams routinely forget it and end up with multi-page documents nobody opens. If you need more words, you're documenting a design, not a decision — use an RFC.
Status as an enum, not free text. Proposed | Accepted | Deprecated | Superseded. Anything else makes the log unsearchable.

File naming and workflow

Store ADRs under doc/decisions/ (or docs/adr/ — both conventions are in the wild). Filename format: NNNN-short-slug.md, zero-padded to four digits so you don't have to rename files when you hit 100. Commit ADRs with the PR that implements the decision — that way git-blame on the code points at the ADR PR, and the ADR PR links back to the implementation commits.

For lint rules and CI integration, see ADR template for GitHub repos.

How WhyChose helps

Most teams already made the decisions — in ChatGPT, Claude, Slack threads, and 1:1s — then don't write them up. WhyChose extracts the decisions you already reasoned through with your AI assistant and produces an ADR-shaped record per decision, in this exact format. You get back a draft; you edit and commit. The ceremony drops from "sit down and write an ADR" to "review and land the draft". The extractor is open-source if you want to self-host.

Get early access