janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
Scrum4Me/CLAUDE.md
Madhura68 f9c56ab074 docs(PBI-74): richtlijn workspace-store + realtime patroon 
Documenteert het patroon dat in Stories 1-8 is opgeleverd, zodat een
volgende workspace-store (sprint, of een nieuwe bounded context) hetzelfde
recept volgt.

- docs/patterns/workspace-store.md (nieuw): wanneer een workspace-store, de
  vijf state-slices, selectors-regels (G1/G2), race-safe ensure*Loaded met
  activeRequestId-guard (G4), SSE-hook + applyRealtimeEvent met
  unknown-event filter, hidden-tab + reconnect resync via
  useWorkspaceResync, restore-hint flow met await-chain en URL-prioriteit,
  optimistic mutations (applyOptimisticMutation/rollback/settle), API
  endpoint-vereisten (force-dynamic, cache: no-store), test-setup met
  MemoryStorage + originalActions snapshot + mockImplementation, gotchas
  G1-G8 als comment-template, en het 8-staps migratiepad.
- docs/patterns/zustand-optimistic.md: bijgewerkt voor de nieuwe
  workspace-store API; verwijst voor het bredere patroon naar
  workspace-store.md. Voorbeelden voor pbi-order + entity-patch.
- CLAUDE.md: patterns quickref aangevuld met workspace-store-rij.

Verify: typecheck clean.

Refs: PBI-74

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 01:53:55 +02:00

6.3 KiB
Raw Blame History

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
Workspace-store + realtime (PBI-74) docs/patterns/workspace-store.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.