2bef1a4c20
CI faalde sinds #191 (docs cleanup) op pre-existing broken links: - docs/old/ bevat archief-docs met by-design stale paden - docs/plans/PBI-79*, M9*, M11* hadden geprojecteerde paden naar ../backlog/index.md (verplaatst naar docs/old/backlog/) en naar app-bestanden die nooit met de juiste relatieve prefix waren geschreven - docs/adr/0000* verwees naar docs-restructure-ai-lookup.md (verplaatst) - docs/glossary.md verwees naar /docs/backlog/index.md (verplaatst) Fixes: - scripts/check-doc-links.mjs: skip docs/old/ recursief - Move docs/plans/{PBI-79,M9,M11}*.md → docs/old/plans/ (allemaal merged PBIs; plans waren historisch) - docs/adr/0000-record-architecture-decisions.md: update pad naar archief - docs/glossary.md: verwijder dode "backlog index"-link Verificatie: `npm run docs:check-links` → ✓ All doc links valid (105 files) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
|
||
[`../old/plans/docs-restructure-ai-lookup.md`](../old/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`.
|