59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# 0000. ADR process and template
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
We are about to make several architecture decisions about how the Qdrant
|
|
vector store is structured and used (ingestion, CRUD, and agent retrieval).
|
|
`docs/adr/README.md` currently has no convention for recording these
|
|
decisions. We need a lightweight, consistent format so future contributors
|
|
can understand *why* the system is built the way it is, not just *what* it
|
|
does.
|
|
|
|
## Decision
|
|
|
|
We will record architecturally significant decisions as Architecture Decision
|
|
Records (ADRs) under `docs/adr/`, using this convention:
|
|
|
|
- **Filename**: `NNNN-short-title.md`, zero-padded, monotonically increasing
|
|
(`0000`, `0001`, `0002`, ...). The number is permanent once assigned.
|
|
- **Sections**, in this order:
|
|
1. Title (`# NNNN. Title`)
|
|
2. Status — one of `Proposed`, `Accepted`, `Superseded by NNNN`
|
|
3. Context — the problem, constraints, and forces at play
|
|
4. Decision — what we're doing, stated directly
|
|
5. Consequences — `Positive` and `Negative` subsections
|
|
6. Alternatives Considered — options we rejected and why
|
|
- **Immutability**: once an ADR is `Accepted`, it is not edited to reflect a
|
|
changed decision. A changed decision gets a *new* ADR that sets the old
|
|
one's status to `Superseded by NNNN` and links back to it. Small
|
|
clarifications/typo fixes are fine to edit in place.
|
|
- **Scope**: only decisions with real architectural weight (data model,
|
|
external system boundaries, protocols, cross-cutting concerns) get an ADR.
|
|
Routine implementation choices do not.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Future contributors (and agents) can trace *why* the Qdrant schema, CRUD
|
|
API, and retrieval pipeline look the way they do without re-deriving it
|
|
from code.
|
|
- Decisions that turn out wrong are corrected via a visible trail
|
|
(superseding ADRs) instead of silently rewritten history.
|
|
|
|
### Negative
|
|
- Adds minor overhead — anyone making a significant architectural change must
|
|
also write or update an ADR.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **No formal record, rely on commit messages/PR descriptions**: rejected —
|
|
these are hard to discover later and don't survive squash-merges or
|
|
history rewrites.
|
|
- **Full MADR template (with explicit "Decision Drivers" and scored option
|
|
comparison tables)**: rejected as too heavyweight for this project's current
|
|
size; we can adopt more structure later if needed via a new ADR.
|