Scrum4Me/CLAUDE.md

title	status	audience	language	last_updated
CLAUDE.md — Scrum4Me	active	ai-agent	nl	2026-05-08

CLAUDE.md — Scrum4Me

Desktop-first Scrum-app voor solo developers en kleine teams. Hiërarchie: product → PBI → story → taak. Zie README.md voor setup.

---

Orientatie

Bestand	Waarvoor
docs/INDEX.md	Gegenereerde index van alle docs — begin hier
docs/specs/functional.md	Acceptatiecriteria, user flows
docs/architecture.md	Breadcrumb → 6 topische arch-bestanden
docs/backlog/index.md	Implementatievolgorde, "done when"-criteria
docs/api/rest-contract.md	REST API contract voor Claude Code
docs/design/styling.md	Lees vóór elk component — MD3-tokens, shadcn
docs/plans/<key>-*.md	Implementatieplan per milestone
docs/adr/	Architecture Decision Records — tech-keuzes (base-ui vs Radix, sort-order, demo-policy, …)
docs/manual/	7-delige gebruiks- en operationele handleiding (workflow, git, docker, troubleshooting)
docs/architecture/	6 topische architecture-bestanden (data-model, auth, sprint-execution, …) — uitwerking van docs/architecture.md

---

Hoe werk vinden

Track A — MCP (aanbevolen):

1. Branch aanmaken: git checkout -b feat/<batch-slug> — nog geen gh pr create
2. mcp__scrum4me__get_claude_context → pak de next story
3. Voer taken uit in sort_order; update status per taak
4. Lees het relevante patroon en styling vóór je begint
5. Verifieer: npm run verify && npm run build — verify = lint + typecheck + test
6. Commit per laag: git add -A && git commit — geen git push — zie docs/runbooks/branch-and-commit.md
7. Herhaal stap 2–6 per story; branch blijft dezelfde
8. Queue leeg → git push -u origin <branch> + gh pr create

Track B — manueel:

1. Lees taak in docs/backlog/index.md
2. Zoek spec in docs/specs/functional.md
3. Lees patroon + styling → bouw → verifieer → vraag bevestiging → commit

Volledige MCP-tool documentatie: docs/runbooks/mcp-integration.md

---

Hardstop regels

• Styling: nooit bg-blue-500; altijd MD3-tokens (bg-primary, bg-status-done, …)
• UI: gebruik @base-ui/react met render-prop, niet Radix asChild
• Push: commits accumuleren lokaal per taak (git add -A && git commit); push + PR pas bij lege queue of na expliciete gebruikersbevestiging — zie branch-and-commit.md
• Demo: drie lagen — proxy.ts + server action + UI disabled knop
• Enum: DB UPPER_SNAKE ↔ API lowercase — uitsluitend via lib/task-status.ts
• Foutcodes: 400 = parse-fout, 422 = Zod-validatie, 403 = demo-token
• Server/client grens: *-server.ts bevat DB/node-only; nooit importeren in client component
• Worker/jobs: ClaudeJob queue (QUEUED → CLAIMED → RUNNING → DONE|FAILED|SKIPPED); MCP-worker claimt via wait_for_job en sluit met update_job_status — zie worker-idempotency.md
• Model/mode per ClaudeJob: kind-default → product → job-snapshot → task.requires_opus. Resolver in scrum4me-mcp/src/lib/job-config.ts (en gespiegeld in lib/job-config.ts) — zie job-model-selection.md
• Deployment: npm run verify && npm run build vóór elke PR. Selectieve deploy-controle (labels + path-filter): zie docs/runbooks/deploy-control.md

---

Stack

Laag	Technologie
Framework	Next.js 16 (App Router) + React 19
Taal	TypeScript strict
Styling	Tailwind CSS + shadcn/ui + MD3 via app/styles/theme.css
State	Zustand + dnd-kit
DB	Prisma v7 + PostgreSQL (Neon)
Auth	iron-session + bcryptjs
Test	Vitest (__tests__/, config in vitest.config.ts)
Utilities	Zod, Sonner, Sharp, Vercel Analytics

---

Patterns quickref

Patroon	Bestand
iron-session	docs/patterns/iron-session.md
Prisma singleton	docs/patterns/prisma-client.md
Server Action (auth + Zod)	docs/patterns/server-action.md
Route Handler (REST)	docs/patterns/route-handler.md
Zustand optimistic update	docs/patterns/zustand-optimistic.md
Float sort_order / drag-and-drop	docs/patterns/sort-order.md
Proxy / route protection	docs/patterns/proxy.md
QR-pairing	docs/patterns/qr-login.md
Claude ↔ user vraagkanaal	docs/patterns/claude-question-channel.md
Entity Dialog (verplicht)	docs/patterns/dialog.md
Realtime NOTIFY-payload	docs/patterns/realtime-notify-payload.md
Story met UI-component	docs/patterns/story-with-ui-component.md
Web Push	docs/patterns/web-push.md
Job-config resolver (PBI-67)	lib/job-config.ts ↔ scrum4me-mcp/src/lib/job-config.ts
Debug-id op component-root	docs/patterns/debug-id.md
Debug-labels (BEM)	docs/patterns/debug-labels.md

---

Env vars

DATABASE_URL=""    # postgresql://...
DIRECT_URL=""      # pooler-bypass voor LISTEN/NOTIFY
SESSION_SECRET=""  # min 32 chars
CRON_SECRET=""     # Bearer-secret /api/cron/*

Volledig schema: lib/env.ts. Canonieke lijst: .env.example — bevat ook web-push (VAPID_*, INTERNAL_PUSH_SECRET), Sentry (SENTRY_*) en optioneel ANTHROPIC_API_KEY.

---

MCP & cron

• MCP-server (extern): standalone Node-proces in ~/Development/scrum4me-mcp/ — Prisma-schema gesynced via sync-schema.sh. 30+ tools (get_claude_context, wait_for_job, update_task_status, …)
• Cron (vercel.json):
  • /api/cron/expire-questions — dagelijks 04:00 UTC
  • /api/cron/cleanup-agent-artifacts — dagelijks 03:00 UTC
• Realtime: SSE op /api/realtime/*, gevoed door PostgreSQL LISTEN/NOTIFY op kanaal scrum4me_changes (vereist DIRECT_URL voor pooler-bypass)

---

Scrum-terminologie

PBI (niet: Feature/Epic) · Story (niet: Ticket) · Sprint Goal (niet: Objective)

---

Verificatie

npm run verify && npm run build   # verify = lint + typecheck + test

Worker job-status protocol (wanneer DONE / SKIPPED / FAILED): zie docs/runbooks/worker-idempotency.md.