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:
# 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:
0001-short-decision-name.md
0002-another-decision.md
The repository currently follows this convention:
0001-runtime-and-development-stack.md0002-initial-project-structure.md0003-containerized-developer-workflow.md0004-configuration-and-environment-strategy.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.