ADRs

What an ADR Is

An ADR, or Architecture Decision Record, is a short document that captures one important technical decision, its context, and its outcome.

When To Create One

Create an ADR when a decision:

affects architecture or major technical direction
changes implementation constraints for future work
needs durable reviewable documentation in the repository

Before an ADR is accepted, compare alternatives using the technical decision process in docs/DECISION_PROCESS.md.

Minimum ADR Template

Each ADR should include at least:

title
status
date
context
options considered
decision
consequences

Minimal example:

# ADR-0001: Example Decision

- Status: proposed
- Date: YYYY-MM-DD

## Context

What problem or uncertainty is being resolved?

## Options Considered

What meaningful alternatives were compared and why?

## Decision

What was chosen?

## Consequences

What follows from this decision?

Status Values

Use these status values:

proposed
accepted
superseded
rejected

Naming Convention

Name ADR files using a numeric prefix and a short slug:

ADR-0001-short-decision-name.md
ADR-0002-another-decision.md

Relationship to Implementation Tasks

Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, evaluate the options first, then record the accepted outcome in an ADR before implementation proceeds.

1.5 KiB Raw Blame History