72 lines
1.5 KiB
Markdown
72 lines
1.5 KiB
Markdown
# 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:
|
|
|
|
```md
|
|
# 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:
|
|
|
|
```text
|
|
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.
|