Skip to content

0001-template.adoc

Latest commit

 

History

History
53 lines (40 loc) · 1.94 KB

0001-template.adoc

File metadata and controls

53 lines (40 loc) · 1.94 KB
Raw

ADR-0001 — Use Architecture Decision Records

Context

We need a lightweight way to record significant architectural decisions and the reasoning behind them, so future maintainers (and AI agents) can understand why the project is shaped as it is.

Decision

Adopt Architecture Decision Records (ADRs) in docs/decisions/, numbered sequentially (0001, 0002, …​).

  • Each ADR is a single .adoc file.

  • The first ADR (this one) records the decision to use ADRs.

  • Status values: PROPOSED, ACCEPTED, DEPRECATED, SUPERSEDED.

  • When a decision is overturned, the new ADR records the supersession and updates the old one’s status to SUPERSEDED by 00NN.

Consequences

  1. Positive: future readers see why without git-archaeology.

  2. Positive: design alternatives are documented, not just the winning choice.

  3. Positive: ADRs are reviewable in PRs — the design discussion happens alongside the code that implements it.

  4. Negative: maintenance burden — every non-obvious decision now warrants an ADR. (We mitigate by keeping ADRs short; "non-obvious" is a judgment call.)

  5. Negative: ADRs can rot. We accept this; the SUPERSEDED chain is the recovery mechanism.

Alternatives considered

  1. Comments in code — too local; doesn’t capture cross-cutting decisions.

  2. Wiki / external doc — drifts from code; not in PR review.

  3. Commit messages — too transient and not discoverable.

  4. No record — discarded; this is how every project ends up with "I don’t know why we do it this way" debt.

Companion ADRs

  • (None yet — this is the first ADR.)

References