Madhura68
8a7d419972
Set up docs/adr/ as the canonical home for architecture decisions: - templates/nygard.md — default four-section format (Status, Context, Decision, Consequences) for one-way-door decisions. - templates/madr.md — MADR v4 with YAML front-matter and explicit Considered Options for decisions where rejected alternatives matter. - README.md — naming convention (NNNN-kebab-case), template-selection guidance (Nygard default; MADR for auth, queue mechanics, agent integration), status lifecycle, and ADR roster. - 0000-record-architecture-decisions.md — meta-ADR establishing the practice itself, in Nygard format. Backfilling existing implicit decisions (base-ui-over-radix, float sort_order, demo-user three-layer policy, etc.) is fase 6 of the docs-restructure plan.
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# ADR-0000: Record architecture decisions
|
||
|
||
## Status
|
||
|
||
accepted
|
||
|
||
## Context
|
||
|
||
Scrum4Me makes several non-obvious architectural choices that aren't visible
|
||
from the code alone — for example, why we use `@base-ui/react` rather than
|
||
Radix, why drag-and-drop ordering uses float `sort_order` instead of integer
|
||
positions, why authentication runs on iron-session rather than NextAuth,
|
||
and why the demo-user policy is enforced in three layers. These decisions
|
||
are scattered across `CLAUDE.md`, individual pattern docs, plan files, and
|
||
commit messages. New contributors and AI agents working on the codebase
|
||
have no fast path to the *why*, which leads to one of two failure modes:
|
||
they either re-litigate decisions that were already settled, or they make
|
||
changes that violate constraints they didn't know about.
|
||
|
||
We want a single, predictable place to record significant architectural
|
||
choices, with enough context that a reader six months from now can decide
|
||
whether the decision still holds.
|
||
|
||
## Decision
|
||
|
||
We adopt Architecture Decision Records (ADRs) as the canonical format for
|
||
documenting significant architectural choices in this codebase. ADRs live
|
||
in `docs/adr/`, are numbered sequentially with a four-digit prefix
|
||
(`0001-...md`, `0002-...md`, …), and follow one of two templates:
|
||
|
||
- **Nygard** ([`templates/nygard.md`](./templates/nygard.md)) — default,
|
||
for one-way-door decisions with a clear motivating context.
|
||
- **MADR v4** ([`templates/madr.md`](./templates/madr.md)) — for
|
||
decisions where weighing multiple alternatives is part of the value
|
||
the record provides (auth, queue mechanics, agent integration).
|
||
|
||
The full conventions — file naming, status lifecycle, template selection
|
||
guidance — are documented in [`README.md`](./README.md).
|
||
|
||
ADRs are immutable once accepted: course corrections create a new ADR
|
||
that supersedes the old one rather than editing the original.
|
||
|
||
## Consequences
|
||
|
||
### Positive
|
||
|
||
- Architectural choices have a single, predictable home that an AI agent
|
||
or new contributor can find with one `ls docs/adr/`.
|
||
- The "why" of each decision is captured at the moment it's made, when
|
||
the context is fresh, rather than reconstructed later from commits.
|
||
- Superseded decisions remain readable, so future contributors can see the
|
||
history of a choice without git archaeology.
|
||
- The format scales: writing an ADR is a 15-minute activity for the
|
||
default Nygard template, low enough overhead to be worth doing every
|
||
time.
|
||
|
||
### Negative
|
||
|
||
- Adds a small ritual to every significant architectural decision — easy
|
||
to skip when moving fast, leading to a stale or incomplete record if
|
||
not enforced through review.
|
||
- Backfilling existing decisions requires writing 5–8 retrospective ADRs
|
||
for choices that were never recorded (planned in fase 6 of
|
||
[`../plans/docs-restructure-ai-lookup.md`](../plans/docs-restructure-ai-lookup.md)).
|
||
- Two templates means a per-decision choice about which to use. Mitigated
|
||
by making Nygard the explicit default in `README.md`.
|