This directory captures significant design decisions for the ABCA project. Each ADR explains why a decision was made — not just what was decided — so that future contributors (human and AI) can understand the reasoning without excavating git history or PR discussions.
Write an ADR when a decision:
- Affects multiple packages or the overall architecture
- Establishes a pattern other code will follow
- Is non-obvious — a reasonable person might choose differently
- Is hard to reverse once implemented
Do not write an ADR for routine implementation choices that are self-evident from the code.
# ADR-NNN: Title
**Status:** proposed | accepted | superseded | deprecated
**Date:** YYYY-MM-DD
**Supersedes:** ADR-NNN (if applicable)
**Superseded by:** ADR-NNN (if applicable)
## Context
What is the problem or situation that requires a decision? Include constraints, requirements, and forces at play.
## Decision
What was decided and why. Be specific — name the approach chosen.
## Consequences
What follows from this decision:
- (+) Positive outcomes
- (-) Negative outcomes or trade-offs
- (!) Risks or things to watch
## References
- Links to RFCs, issues, PRs, or external resources that informed the decisionADRs are numbered sequentially with zero-padded three-digit prefixes: ADR-001-slug.md, ADR-002-slug.md, etc. Numbers are never reused.
| Status | Meaning |
|---|---|
proposed |
Under discussion, not yet binding |
accepted |
Active and authoritative |
superseded |
Replaced by a newer ADR (link to successor) |
deprecated |
No longer applicable (context changed) |
A decision starts as proposed during RFC discussion and moves to accepted when the implementing PR merges. To change an accepted decision, write a new ADR that supersedes it — do not edit the original.
Design documents describe system shape, interfaces, and implementation detail. ADRs capture cross-cutting choices that constrain multiple designs. When a design decision is significant enough to be "hard to reverse" or "non-obvious," extract it as an ADR and reference it from the design doc. An ADR may supersede another ADR; a design doc is simply updated in place.
- Agents:
AGENTS.mdroutes to this directory for understanding past design rationale. - Humans: Browse this directory or the docs site under the "Decisions" section.
- Search: Each ADR title and context section are written to be grep-friendly.