101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
---
|
|
title: Architecture Decision Records
|
|
status: active
|
|
audience: ai-agent, maintainer, contributor
|
|
language: en
|
|
last_updated: 2026-05-02
|
|
---
|
|
|
|
# Architecture Decision Records
|
|
|
|
This directory contains the Architecture Decision Records (ADRs) for Scrum4Me.
|
|
|
|
## What is an ADR
|
|
|
|
An ADR is a short document that captures a single significant architectural
|
|
decision: the context that forced the decision, the choice we made, and the
|
|
consequences of that choice. ADRs are immutable once accepted — if a later
|
|
decision changes course, we write a new ADR that supersedes the old one.
|
|
|
|
We use ADRs because the project mixes several non-obvious choices (Next.js 16
|
|
specifics, `@base-ui/react` over Radix, float `sort_order` for drag-and-drop,
|
|
iron-session over NextAuth, demo-user three-layer policy, MCP integration
|
|
patterns) and an AI agent reading the codebase six months from now needs to
|
|
find the *why* without spelunking through commit history.
|
|
|
|
## File naming
|
|
|
|
```
|
|
NNNN-kebab-case-title.md
|
|
```
|
|
|
|
- `NNNN` — four-digit zero-padded sequential number, starting at `0001`
|
|
(`0000` is reserved for the meta-ADR that introduces the practice).
|
|
- `kebab-case-title` — lowercase, hyphen-separated, short noun phrase
|
|
echoing the decision (`base-ui-over-radix`, not `decided-to-use-baseui`).
|
|
- Always `.md`.
|
|
|
|
## Choosing a template
|
|
|
|
Two templates live in [`templates/`](./templates/). Default to Nygard.
|
|
|
|
### Nygard (default — [`templates/nygard.md`](./templates/nygard.md))
|
|
|
|
Use Nygard for the common case: a decision that is essentially a one-way
|
|
door with a clear motivating context and one obvious choice. Four sections:
|
|
**Title, Status, Context, Decision, Consequences (Positive / Negative)**.
|
|
|
|
Aim: ≤60 lines. Reads in under a minute.
|
|
|
|
### MADR v4 (when alternatives matter — [`templates/madr.md`](./templates/madr.md))
|
|
|
|
Use MADR when the decision involves weighing multiple alternatives that a
|
|
future reader would otherwise re-litigate. Triggers:
|
|
|
|
- **Authentication / session strategy** (NextAuth vs iron-session vs Clerk).
|
|
- **Queue / messaging mechanics** (LISTEN/NOTIFY vs Redis vs SQS).
|
|
- **Agent integration patterns** (REST polling vs MCP vs SSE channel).
|
|
- **Schema or data-model choices with non-trivial migration cost.**
|
|
- Any decision where you want to record the *rejected* options so future
|
|
contributors don't propose them again.
|
|
|
|
MADR adds: YAML front-matter (status, date, decision-makers, consulted,
|
|
informed), explicit Decision Drivers, Considered Options, Pros and Cons of
|
|
each option, Confirmation, and More Information.
|
|
|
|
## Status lifecycle
|
|
|
|
```
|
|
proposed → accepted → (optionally) superseded by NNNN
|
|
↘ (optionally) deprecated
|
|
```
|
|
|
|
- **proposed** — drafted, awaiting decision-maker sign-off.
|
|
- **accepted** — current binding decision; the codebase reflects this.
|
|
- **superseded by ADR-NNNN** — replaced. Keep the file; never edit the
|
|
Decision section. Add a one-line "Superseded by …" note at the top of
|
|
the Status section and link to the new ADR.
|
|
- **deprecated** — still current but no longer recommended; usually a
|
|
precursor to a future supersession.
|
|
|
|
Once an ADR is accepted, it is immutable except for the Status field and
|
|
typo fixes. Course corrections always create a new ADR.
|
|
|
|
## Index of ADRs
|
|
|
|
| # | Title | Status | Template |
|
|
|---|---|---|---|
|
|
| [0000](./0000-record-architecture-decisions.md) | Record architecture decisions | accepted | Nygard |
|
|
| [0001](./0001-base-ui-over-radix.md) | @base-ui/react over Radix UI | accepted | Nygard |
|
|
| [0002](./0002-float-sort-order.md) | Float sort_order for drag-and-drop reorder | accepted | Nygard |
|
|
| [0003](./0003-one-branch-per-milestone.md) | One branch per milestone (Hobby plan) | accepted | MADR |
|
|
| [0004](./0004-status-enum-mapping.md) | Status enum mapping via lib/task-status.ts | accepted | Nygard |
|
|
| [0005](./0005-iron-session-over-nextauth.md) | iron-session over NextAuth/Clerk | accepted | MADR |
|
|
| [0006](./0006-demo-user-three-layer-policy.md) | Demo-user three-layer write guard | accepted | Nygard |
|
|
| [0007](./0007-claude-question-channel-design.md) | Agent ↔ user question channel via persistent table + LISTEN/NOTIFY | accepted | MADR |
|
|
| [0008](./0008-agent-instructions-in-claude-md.md) | Agent instructions in CLAUDE.md + topical runbooks | accepted | Nygard |
|
|
|
|
When new ADRs are added, the docs index generator (`npm run docs:index`)
|
|
will list them in [`../INDEX.md`](../INDEX.md). Update this table by hand
|
|
when you add or supersede an ADR — the script aggregates across the whole
|
|
docs tree, this README is the canonical ADR-only roster.
|