Madhura68 8a7d419972 docs(adr): add ADR scaffolding (templates, README, meta-ADR)

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.

2026-05-02 21:25:26 +00:00

2.9 KiB

Raw Blame History

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) — default, for one-way-door decisions with a clear motivating context.
MADR v4 (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.

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).
Two templates means a per-decision choice about which to use. Mitigated by making Nygard the explicit default in README.md.

2.9 KiB Raw Blame History Unescape Escape