An Architecture Decision Record Markdown template

Use an Architecture Decision Record (ADR) when a choice is important enough that someone may later ask what constraints shaped it. Markdown keeps the record readable in a text editor, easy to review in Git, and straightforward to link from code or project documentation.

When a decision needs a record

Record a decision when it changes system structure, dependencies, interfaces, deployment, data handling, or another constraint that will be hard to reconstruct from the final code alone. Do not create an ADR for every small implementation detail. The point is to keep the reasoning behind durable choices discoverable, not to turn routine work into paperwork.

A useful ADR describes a single decision. It can mention alternatives, but the decision itself should be clear enough that a new contributor can tell what the team chose and what consequences to expect.

Copyable Markdown template

Adapt the headings to the project. The basic sections below reflect widely used ADR guidance; a team may add its own review or ownership fields.

# ADR 001: Store drafts in browser storage

## Status
Proposed

## Context
Describe the problem, constraints, and desired outcomes.
Keep this section factual and name the forces that are in tension.

## Decision
State the choice in a direct sentence: “We will ...”

## Options considered
- Option A: benefits, costs, and constraints.
- Option B: benefits, costs, and constraints.

## Consequences
### Benefits
- What becomes easier or safer?

### Costs and risks
- What trade-offs or follow-up work does this create?

## Follow-up
- [ ] Owner — next action — due date, if applicable.

## References
- Link to the design, issue, or experiment behind this record.

Use your own status vocabulary, but define it. Common states include proposed, accepted, rejected, deprecated, and superseded. An accepted ADR should remain as part of the history; if the decision changes, write a new record that links to the earlier one rather than silently rewriting the past.

Make the record useful later

• Name the decision in the title. “Use PostgreSQL for account data” is easier to find than “Database discussion.”
• Separate facts from the choice. Context describes constraints; the decision states the team's response.
• Include the real trade-offs. Capture both benefits and costs. A record that only argues for the chosen path is weak evidence.
• Link evidence. Point to benchmarks, design notes, issues, or security reviews instead of copying them into every ADR.
• Keep it brief. If a section needs extensive detail, put that detail in a design document and link to it.

ADR guidance is a practice, not a single universal Markdown standard. Choose one template, make it easy to find, and use it consistently enough that the team knows where to look.

A lightweight repository workflow

1. Create a directory such as docs/decisions/.
2. Give each record a stable number and short title, for example 001-store-drafts-in-browser.md.
3. Review proposed decisions with the people affected before implementation becomes difficult to change.
4. Link the accepted record from the related design or implementation area.
5. When reality changes, add a superseding record and link both directions.

For meeting capture before an ADR is ready, use the Markdown meeting-notes template. To write project-wide agent instructions, see the AGENTS.md guide.

Want to inspect a small example? Try it in a Markdown preview, then verify your publishing destination.