Janpeter Visser
43a4294424
* docs(ST-511): add backlog entry for entity codes feature Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ST-511): add createWithCodeRetry helper to handle P2002 race on auto codes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ST-511): retry on auto-code unique conflict in story and pbi create Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ST-511): surface field errors for code and title in PBI dialog Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ST-511): read create-state errors in Story dialog fieldError Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-512): add backlog entry for REST API code/description/implementation_plan extensions; mark ST-511 done Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-512): extend REST API with code, description and implementation_plan - GET /api/products returns code, description and definition_of_done - GET /api/products/:id/next-story returns story.code and per-task code + implementation_plan - GET /api/sprints/:id/tasks returns description, implementation_plan, story_code and derived per-task code - POST /api/todos accepts and returns optional description (max 2000) All changes are additive — existing clients ignore unknown keys. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-512): mark ST-512 as done Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-513): add backlog entry for API hardening for Claude Code Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): add task and story status mappers for API boundary Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): expose lowercase status on API and accept lowercase in PATCH /api/tasks Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): add metadata JSONB column to StoryLog Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): accept optional metadata in story log and switch validation errors to 422 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): add GET /api/health endpoint with optional db ping Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(ST-513): add GET /api/products/:id/claude-context bundled endpoint Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-513): add docs/API.md and link from CLAUDE.md specs table Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(ST-513): mark ST-513 as done Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ST-513): split 400 (malformed JSON) from 422 (validation), reject 'review' Codex review on PR #2: - P2.1: routes treated JSON parse failures as 422 instead of 400, breaking the contract in docs/API.md. Replace `request.json().catch(() => null)` with try/catch in 4 routes (tasks, reorder, todos, story-log) so a malformed body returns 400 and only well-formed-but-invalid bodies return 422. - P2.2: PATCH /api/tasks/:id accepted `status: "review"`, but the sprint task list UI does not render REVIEW (no label/color, the cycle helper falls back to TO_DO). Reject `review` at the API until the sprint UI is extended; document the subset in docs/API.md. Tests in __tests__/api updated for the new contract (29 assertions: zod-failures now expect 422, status payloads use lowercase API values, sprint-tasks mocks include the new story relation). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
186 lines
6.2 KiB
Markdown
186 lines
6.2 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 |
|
||
|
||
---
|
||
|
||
## 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
|