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

Minimum ADR Template

Each ADR should include at least:

title
status
date
context
decision
consequences

Minimal example:

# ADR-0001: Example Decision

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

## Context

What problem or uncertainty is being resolved?

## 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, record the decision first or explicitly resolve it as part of the task before implementation proceeds.