# 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/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 |

---

## 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)
```

Per task:
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` |

---

## 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

---

## 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 |

---

## Definition of Done

- [ ] 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