Janpeter Visser
fb4d2e093f
* docs(ST-1001..1008): add M10 — QR-pairing login milestone to backlog Plant acht stories ST-1001..ST-1008 voor password-loze inlog via QR-pairing. Mobiele bevestiging met UA+IP, demo-blokkade, paired-sessie 8u TTL. Security-uitgangspunt: mobileSecret reist alleen via QR-fragment + POST-body, desktop-SSE/claim via HttpOnly pre-auth cookie — geheim materiaal nooit in URL-paden, querystrings, access logs of browsergeschiedenis. Twee gescheiden hashes in DB (secret_hash + desktop_token_hash). Bouwt voort op M8 LISTEN/NOTIFY- infra met eigen channel scrum4me_pairing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(ST-1001..1008): teach backlog parser about M9 + M10 M9 (Actief Product Backlog) was bij eerdere merge per ongeluk overgeslagen in de drie milestone-maps; viel terug op fallbacks. Nu expliciet, samen met M10 (QR-pairing). Parser self-test toont 12 milestones / 118 stories / 190 tasks. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-1001..1008): document QR-login flow in functional spec + persona Voeg F-01b (Inloggen via mobiel via QR-pairing) toe aan de functional spec met acceptatiecriteria, randgevallen en datamodel. Beveiligingsuitgangspunt expliciet: mobileSecret in URL-fragment en HttpOnly desktop-cookie zodat geheim materiaal nooit in URL-paden of access logs belandt. Lars-persona krijgt de bijbehorende use-case (publieke/geleende laptops bij klantbezoek of familie) zodat de feature een herkenbare aanleiding heeft in v1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-1001..1008): add M10 implementation plan + link from backlog Volledig implementatie-plan per story (Bestanden / Stappen / Aandachtspunten / Verificatie) in dezelfde stijl als M9. Citeert de patronen uit docs/patterns/iron-session.md, route-handler.md en server-action.md, en hergebruikt het LISTEN/NOTIFY-pattern uit app/api/realtime/solo/route.ts. Bevat ook commit/branch-strategie per laag, reseed-stap voor de MCP-context, en verificatie-acceptatie inclusief log-controle dat geheim materiaal niet in access logs belandt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: enforce one-branch-per-milestone policy to limit Vercel builds Vercel preview-deployments worden bij elke push naar een feature-branch getriggered en kosten op het Hobby-account budget. Voeg expliciete Branch & PR Strategy toe aan CLAUDE.md: één branch per milestone, commits accumuleren lokaal, push + PR pas na handmatige gebruiker-acceptatie. Uitzonderingen voor planning-only PR's (alleen docs) en hotfixes. Update tegelijk de branch/commit-strategie-tabel in het M10-implementatieplan zodat die de nieuwe policy weerspiegelt (één branch feat/M10-qr-login, chronologische commits per stap, push pas bij groene happy-path-acceptatie). Bevat een 'Wanneer aanpassen'-sectie zodat de regel makkelijk teruggedraaid kan worden zodra het account naar Pro gaat. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
262 lines
12 KiB
Markdown
262 lines
12 KiB
Markdown
# CLAUDE.md — Scrum4Me
|
||
|
||
Dit is het centrale instructiedocument voor Claude Code. Lees dit volledig voordat je iets bouwt.
|
||
|
||
---
|
||
|
||
## Wat is Scrum4Me?
|
||
|
||
Een desktop-first fullstack webapplicatie voor solo developers en kleine Scrum Teams die meerdere softwareprojecten parallel beheren. De app organiseert werk hiërarchisch (product → PBI → story → taak), biedt gesplitste planningsschermen met drag-and-drop, en integreert met Claude Code via een REST API.
|
||
|
||
---
|
||
|
||
## Specificatiedocumenten
|
||
|
||
Lees het relevante document voordat je aan een feature begint. Nooit gokken over requirements.
|
||
|
||
| Document | Gebruik voor |
|
||
|---|---|
|
||
| `docs/scrum4me-functional-spec.md` | Acceptatiecriteria, randgevallen, user flows |
|
||
| `docs/scrum4me-architecture.md` | Stack, datamodel, Prisma schema, Zustand stores |
|
||
| `docs/scrum4me-backlog.md` | Welke task bouwen, volgorde, "done when"-criteria |
|
||
| `docs/scrum4me-personas.md` | Lars (primair), Dina, Remi — gebruik bij UI-beslissingen |
|
||
| `docs/scrum4me-product-backlog.md` | Historische domein-backlog (referentie); seed wordt sinds ST-004 gegenereerd uit `scrum4me-backlog.md` via `prisma/seed-data/parse-backlog.ts` |
|
||
| `docs/API.md` | REST-API contract voor Claude Code — endpoints, status-enums, foutcodes, voorbeeld-curls |
|
||
| `docs/scrum4me-styling.md` | **Lees dit voor elk component** — MD3-kleuren, shadcn patronen |
|
||
| `docs/agent-instruction-audit.md` | Waarom de agent-instructies zijn aangescherpt; checklist voor toekomstige wijzigingen |
|
||
| `docs/plans/<milestone-key>-*.md` | Implementatieplan per milestone — Bestanden, Stappen, Aandachtspunten, Verificatie. Lees vóór je aan een ST begint. Milestone-key matcht backlog-header (`M9`, `M3.5`, `PBI-9`, …). |
|
||
| [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule |
|
||
|
||
---
|
||
|
||
## Waar te beginnen
|
||
|
||
Volg de backlog strikt op volgorde. Start bij **ST-001**. Sla geen milestone over.
|
||
|
||
```
|
||
M0 (ST-001–008) → M1 (ST-101–110) → M2 (ST-201–210)
|
||
→ M3 (ST-301–312) → M4 (ST-401–410) → M5 (ST-501–506)
|
||
→ M6 (ST-601–612)
|
||
```
|
||
|
||
Werken aan een task kan via twee tracks. Track A heeft de voorkeur als je in Claude Code zit; Track B is voor Codex of omgevingen zonder MCP.
|
||
|
||
### Track A — via Claude Code MCP (aanbevolen)
|
||
|
||
1. Roep `mcp__scrum4me__implement_next_story` aan met `product_id` (gebruik `mcp__scrum4me__list_products` als je het id niet weet)
|
||
2. De prompt orkestreert: `get_claude_context` → `log_implementation` → per task `update_task_status(in_progress)` → bouw → `update_task_status(done)` → `log_test_result` → `log_commit`
|
||
3. Bouw de tasks in volgorde van `sort_order`; lees per task de relevante pattern-doc en styling
|
||
4. Verifieer: `npm run lint && npm test && npm run build`
|
||
5. Commit per laag (zie Commit Strategy)
|
||
|
||
### Track B — manueel (Codex of zonder MCP)
|
||
|
||
1. Lees de task in `scrum4me-backlog.md`
|
||
2. Zoek de bijbehorende feature-spec in `scrum4me-functional-spec.md`
|
||
3. Lees het relevante patroon in `docs/patterns/` en styling in `docs/scrum4me-styling.md` als dat van toepassing is
|
||
4. Bouw — test — verifieer de "Done when"-criteria
|
||
5. Vraag of de code correct is
|
||
6. Commit (zie Commit Strategy hieronder)
|
||
7. Vraag of de volgende taak gedaan moet worden
|
||
|
||
---
|
||
|
||
## Tech stack
|
||
|
||
```
|
||
Next.js 16 (App Router) + React 19
|
||
TypeScript strict
|
||
Tailwind CSS + shadcn/ui
|
||
MD3 kleurensysteem via app/styles/theme.css
|
||
Zustand (client state)
|
||
dnd-kit (drag-and-drop)
|
||
Prisma v7 + PostgreSQL (Neon)
|
||
iron-session (auth cookies)
|
||
bcryptjs + Zod + Sonner
|
||
Sharp (avatarverwerking)
|
||
Vercel Analytics (@vercel/analytics/next)
|
||
```
|
||
|
||
> ⚠️ **Stylingregel:** Gebruik **nooit** `bg-blue-500` of willekeurige Tailwind-kleuren.
|
||
> Gebruik altijd semantische MD3-tokens: `bg-primary`, `bg-status-done`, `bg-priority-critical`.
|
||
> Zie `scrum4me-styling.md` voor alle patronen.
|
||
|
||
> ⚠️ **Next.js-versie:** Lees `node_modules/next/dist/docs/` bij twijfel — API's kunnen afwijken van trainingsdata.
|
||
|
||
---
|
||
|
||
## Implementatiepatronen
|
||
|
||
Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven.
|
||
|
||
| Patroon | Bestand |
|
||
|---|---|
|
||
| iron-session (auth cookies) | `docs/patterns/iron-session.md` |
|
||
| Prisma Client singleton | `docs/patterns/prisma-client.md` |
|
||
| Server Action (met auth + Zod) | `docs/patterns/server-action.md` |
|
||
| Route Handler (REST API) | `docs/patterns/route-handler.md` |
|
||
| Zustand optimistische update + rollback | `docs/patterns/zustand-optimistic.md` |
|
||
| Float sort_order drag-and-drop | `docs/patterns/sort-order.md` |
|
||
| Middleware (route protection) | `docs/patterns/middleware.md` |
|
||
| Status-enum mapping (DB ↔ API) | `lib/task-status.ts` |
|
||
| Client/server module-boundary | `*-server.ts` bevat DB-calls of node-only deps; `*.ts` is pure (client-safe). Nooit `import { ... } from '@/lib/foo-server'` in een client-component, anders krijg je `Module not found: 'dns'`/`'pg'`-style runtime fouten |
|
||
|
||
---
|
||
|
||
## Env vars
|
||
|
||
```bash
|
||
DATABASE_URL="" # postgresql://...
|
||
DIRECT_URL="" # alleen bij Neon/cloud
|
||
SESSION_SECRET="" # openssl rand -base64 32
|
||
```
|
||
|
||
---
|
||
|
||
## Conventies
|
||
|
||
- **Branches:** `feat/ST-001-scaffolding`
|
||
- **Server Actions:** altijd in `actions/[domein].ts`, nooit inline in page.tsx
|
||
- **Validatie:** altijd Zod, nooit handmatige checks
|
||
- **Toegangsmodel:** product-scoped resources gebruiken `productAccessFilter(userId)` tenzij het expliciet een eigenaarsactie is
|
||
- **Bulk-ID's:** reorder- en beslissingsacties valideren dat alle meegegeven IDs binnen dezelfde parent-scope vallen voordat er geschreven wordt
|
||
- **Foreign keys:** denormalized keys zoals `story.product_id` worden afgeleid uit de database-parent (`pbi.product_id`), nooit uit client-input
|
||
- **Demo-check:** elke Server Action controleert `session.isDemo` vóór schrijven
|
||
- **Foutberichten:** Nederlands voor eindgebruikers — comments in code: Engels
|
||
- **Dependencies:** elke geïmporteerde runtime package staat direct in `dependencies`, niet alleen transitief in `package-lock.json`
|
||
- **Docs-sync:** elke gedrags-, dependency-, API- of deploymentwijziging werkt README, relevante docs en patterns bij in dezelfde change
|
||
- **Entity codes:** gebruik product/PBI/story-codes in commit-titles wanneer aanwezig (`feat(ST-356.2): ...`); branchnaam blijft `feat/ST-XXX-slug`
|
||
- **Status-enums op API:** lowercase (`todo|in_progress|review|done`, `open|in_sprint|done`); DB houdt UPPER_SNAKE; conversie uitsluitend via `lib/task-status.ts`-mappers — nooit ad-hoc `.toLowerCase()` elders
|
||
- **Foutcodes API:** `400` alleen voor malformed JSON-body (parse-fout via `request.json()`); `422` voor zod-validatie en well-formed-maar-niet-acceptabel; `403` voor demo-tokens. Documenteer per endpoint in `docs/API.md`
|
||
- **Tests volgen contract:** bij een API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook `__tests__/api/` mee — een test die rood gaat omdat de oude waarde wordt verwacht is een onvolledige wijziging, niet een "kapotte test"
|
||
- **Dev port:** `npm run dev` draait altijd op **3000**. Een `predev`-hook killt vooraf elk proces op 3000 (stale Next.js dev-server, vorige sessie) zodat sessies, cookies en MCP-config consistent op één poort werken. Wijk hier niet van af — geen `-p 3001` o.i.d. tenzij je expliciet twee dev-servers naast elkaar wil draaien
|
||
|
||
---
|
||
|
||
## Branch & PR Strategy (STRICT — kostenbeheersing)
|
||
|
||
> **Core rule: één branch per milestone, PR alleen na gebruikerstest**
|
||
|
||
Elke `git push` naar een feature-branch triggert een Vercel preview-deployment. Op het huidige Hobby-account zijn die schaars en kosten geld; we minimaliseren preview-builds tot er werkelijk iets te reviewen valt.
|
||
|
||
### Wel doen
|
||
|
||
- Eén branch voor de hele milestone — `feat/M{N}-{slug}` (bv. `feat/M10-qr-login`); voor losse stories zonder milestone blijft `feat/ST-XXX-{slug}` geldig
|
||
- Commits accumuleren lokaal volgens de Commit Strategy hieronder — één commit per stap, ST-code in de titel
|
||
- Pushen + PR openen **pas nadat de gebruiker de milestone handmatig heeft getest en goedgekeurd** — vraag expliciet om bevestiging vóór `git push`
|
||
- Tussentijdse "klaar voor jouw test"-momenten markeren met een lokale tag of een berichtje in chat, niet met een push
|
||
|
||
### Niet doen
|
||
|
||
- Pushen na elke story of commit
|
||
- Een PR per story openen tijdens de implementatie
|
||
- "Just-in-case" pushen om backup te hebben — gebruik `git stash`, een lokale tag, of meerdere lokale branches
|
||
- `--force-push` om eerdere preview-builds "weg te toveren" (kost dezelfde build opnieuw bij hercreatie)
|
||
|
||
### Uitzonderingen
|
||
|
||
- Een **planning-PR** zonder code-wijzigingen (alleen docs in `docs/plans/` of `docs/`) mag direct gepusht worden — die triggert geen functional regressie en is goedkoop te bouwen
|
||
- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden
|
||
|
||
### Wanneer aanpassen
|
||
|
||
Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) gaat: vervang deze regel door "branch + PR per story" zoals oorspronkelijk in dit document stond. Werk deze sectie bij én documenteer de wijziging in `docs/agent-instruction-audit.md`.
|
||
|
||
---
|
||
|
||
## Commit Strategy (STRICT)
|
||
|
||
> **Core rule: één commit = één verantwoordelijkheid**
|
||
|
||
### Nooit doen
|
||
|
||
- Database + API + UI in één commit mengen
|
||
- Feature + documentatie combineren
|
||
- Grote "alles gewijzigd" commits
|
||
- Vage berichten zoals "update stuff"
|
||
|
||
### Verplichte structuur
|
||
|
||
Splits werk op in logische lagen:
|
||
|
||
1. Database / Prisma
|
||
2. API / server actions
|
||
3. UI / components
|
||
4. Config / infra
|
||
5. Documentatie
|
||
|
||
### Commit-formaat
|
||
|
||
```
|
||
feat(ST-XXX): korte beschrijving
|
||
fix(ST-XXX): korte beschrijving
|
||
chore(ST-XXX): korte beschrijving
|
||
docs(ST-XXX): korte beschrijving
|
||
```
|
||
|
||
### Voorbeeld (verplicht patroon)
|
||
|
||
In plaats van:
|
||
|
||
```bash
|
||
feat: add profile system
|
||
```
|
||
|
||
Splits altijd op in:
|
||
|
||
```bash
|
||
feat(ST-XXX): add user profile fields to Prisma schema
|
||
feat(ST-XXX): add avatar upload endpoint
|
||
feat(ST-XXX): add profile editor component
|
||
chore(ST-XXX): configure sharp for avatar processing
|
||
docs(ST-XXX): document profile feature
|
||
```
|
||
|
||
---
|
||
|
||
## Scrum-terminologie
|
||
|
||
| Correct | Niet gebruiken |
|
||
|---|---|
|
||
| Product Backlog Item (PBI) | Feature, Epic, Issue |
|
||
| Story | User Story, Ticket |
|
||
| Sprint Goal | Sprint Objective |
|
||
| Scrum Team | Team |
|
||
|
||
---
|
||
|
||
## MCP-integratie
|
||
|
||
Scrum4Me heeft een eigen MCP-server in repo [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) die de REST-API als native tools voor Claude Code aanbiedt. Schema's worden gedeeld via een git submodule (`vendor/scrum4me`), niet gedupliceerd.
|
||
|
||
### Tools beschikbaar in Claude Code
|
||
|
||
- `mcp__scrum4me__health` — service + DB ping
|
||
- `mcp__scrum4me__list_products` — producten waar de tokengebruiker toegang tot heeft
|
||
- `mcp__scrum4me__get_claude_context` — bundled product / actieve sprint / next story (met tasks) / open todos
|
||
- `mcp__scrum4me__update_task_status`, `mcp__scrum4me__update_task_plan`
|
||
- `mcp__scrum4me__log_implementation`, `mcp__scrum4me__log_test_result`, `mcp__scrum4me__log_commit`
|
||
- `mcp__scrum4me__create_todo`
|
||
|
||
### Prompt
|
||
|
||
- `implement_next_story` (arg: `product_id`) — end-to-end workflow
|
||
|
||
### Schema-drift bewaking
|
||
|
||
Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuhhWNGBQKFD` die `vendor/scrum4me` syncet en `prisma:generate` + `tsc --noEmit` uitvoert in scrum4me-mcp. Als die agent drift rapporteert, hoort dat **vóór** een Scrum4Me-PR met schema-wijziging gemerged kan worden — anders breekt de MCP-server stilletjes op runtime.
|
||
|
||
---
|
||
|
||
## Definition of Done (MVP)
|
||
|
||
M7 (MCP-server) is post-MVP en heeft eigen acceptatie in `docs/scrum4me-backlog.md`.
|
||
|
||
- [ ] Alle 62 tasks (ST-001 t/m ST-612) afgerond
|
||
- [ ] Volledige Lars-flow zonder fouten (ST-612)
|
||
- [ ] Alle 7 API-endpoints werken via curl
|
||
- [ ] Demo-gebruiker heeft geen schrijfrechten
|
||
- [ ] App opzetbaar via README zonder extra hulp
|
||
- [ ] CI/CD actief — falende build blokkeert merge
|
||
- [ ] Beveiligingsreview API geslaagd (cross-user toegang onmogelijk)
|
||
- [ ] Documentatie is bijgewerkt voor gewijzigde API's, dependencies, deployment en agent-instructies
|