8c63ba377d
* feat(PBI-67/ST-1297): datamodel-velden voor job-model-selectie
Voegt 8 nieuwe optionele velden toe verspreid over Product, Task en
ClaudeJob ten dienste van de override-cascade:
task.requires_opus → job.requested_* → product.preferred_* → kind-default
Bestaande rijen krijgen NULL (Product/ClaudeJob) of false (Task) en
vallen daarmee terug op de kind-defaults uit de resolver (ST-1298).
Migration is additief: alleen ALTER TABLE ADD COLUMN, geen RENAME of
DROP. Bestaande factories en seed-script blijven werken zonder
aanpassing omdat alle nieuwe velden default-waardes hebben.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-67/ST-1299): job-config snapshot bij enqueue + worker-flag-runbook
T-789: Snapshot van resolved JobConfig in ClaudeJob.requested_*
bij elke job-creatie. Helper in lib/job-config-snapshot.ts laadt
product (preferred_*) en task (requires_opus) en draait de resolver
uit lib/job-config.ts (mirror van scrum4me-mcp/src/lib/job-config.ts —
zelfde matrix, sync-comment in bestand). Toegepast op alle 5
enqueue-locaties:
- actions/user-questions.ts (PLAN_CHAT)
- actions/sprint-runs.ts × 3 (SPRINT_IMPLEMENTATION x2,
TASK_IMPLEMENTATION loop)
- actions/ideas.ts (IDEA_GRILL / IDEA_MAKE_PLAN)
Test-mocks uitgebreid met product.findUnique en task.findUnique zodat
de helper bij unit tests veilig terugvalt op kind-defaults (alle 563
tests groen).
T-790: Sectie 'Config doorgeven aan Claude Code' toegevoegd aan
docs/runbooks/worker-idempotency.md met CLI-flag-mapping en de
verwachte aanroep per kind. Forward-link naar
docs/runbooks/job-model-selection.md (volgt in T-794).
Plus: docs/plans/job-model-selection.md (de approved plan-doc).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-67/ST-1300): cost-attribution voor thinking-tokens + admin UI
T-792: token-stats + token-history rekenen actual_thinking_tokens nu
mee in de totale kosten (tegen input-rate, conform Anthropic billing).
COALESCE-veilig zodat oude rijen 0 bijdragen i.p.v. NaN. Nieuwe export
`getTokenStatsByKind` aggregeert tokens en kosten per ClaudeJob.kind
zodat we relatieve uitgaven van IDEA_GRILL/IDEA_MAKE_PLAN/PLAN_CHAT/
TASK_IMPLEMENTATION/SPRINT_IMPLEMENTATION kunnen zien.
T-793: admin/jobs Kosten-tabel toont:
- Nieuwe kolom 'Thinking' (aantal verbruikte thinking-tokens)
- Mismatch-marker (rood) als requested_model afwijkt van actuele
model_id — duidt op een worker die de CLI-flag niet doorgaf.
Tooltip toont aangevraagd model. Geen Sentry/log-noise.
Page-level cost-berekening volgt dezelfde formule (input_price ×
thinking_tokens). 563 tests groen.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(PBI-67/ST-1301): runbook + CLAUDE.md updates voor model/mode-selectie
T-794: Nieuwe runbook docs/runbooks/job-model-selection.md met
override-cascade, kind-default-matrix, override-voorbeelden,
auditspoor en cost-attribution-formule. 107 regels.
T-795: CLAUDE.md hardstop-bullet voor 'Model/mode per ClaudeJob'
(verwijst naar nieuwe runbook) + patterns-quickref-rij voor
job-config resolver. CLAUDE.md blijft 139 regels (≤ 150).
T-796: docs:check-links groen — 108 files, geen broken links. Twee
externe-repo verwijzingen (scrum4me-mcp/...) ge-de-linked tot plain
text omdat de check-links script de zustertree niet traverseert; de
referenties blijven leesbaar.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
139 lines
6.1 KiB
Markdown
139 lines
6.1 KiB
Markdown
---
|
||
title: "CLAUDE.md — Scrum4Me"
|
||
status: active
|
||
audience: [ai-agent]
|
||
language: nl
|
||
last_updated: 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](./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](./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](./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](./docs/runbooks/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](./docs/runbooks/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](./docs/runbooks/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](./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` |
|
||
|
||
---
|
||
|
||
## Env vars
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
npm run verify && npm run build # verify = lint + typecheck + test
|
||
```
|
||
|
||
Worker job-status protocol (wanneer `DONE` / `SKIPPED` / `FAILED`): zie [docs/runbooks/worker-idempotency.md](./docs/runbooks/worker-idempotency.md).
|