From 4c979eee85067553ac69116beeb6e2ec0515cd5c Mon Sep 17 00:00:00 2001 From: Janpeter Visser Date: Wed, 29 Apr 2026 14:46:38 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20clean=20up=20CLAUDE.md=20=E2=80=94=20re?= =?UTF-8?q?structure=20scrambled=20sections=20+=20sync=20stale=20facts=20(?= =?UTF-8?q?#14)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Het bestand was structureel gebroken: prompt_scaffold-instructies uit /insights ("Add as a new ## X section ...\\n\\n## X") waren als platte tekst in de Branch & PR Strategy-sectie beland, met drie nieuwe secties (UI Library Conventions, Deployment, Plan Mode) onleesbaar verstopt daarbinnen. Wijzigingen: Restructurering - Branch & PR Strategy: scaffold-residue weg, oorspronkelijke 'core rule' + do/don't/exceptions hersteld - UI Library Conventions: eigen sectie, na Tech stack — base-ui/react render-prop pattern (niet Radix asChild) expliciet beschreven - Deployment (Vercel): eigen sectie, vóór DoD — Sharp Linux-binaries, image remotePatterns, Hobby cron-limieten, CRON_SECRET, preflight - Plan Mode: eigen sectie, achter Branch & PR — wanneer wel/niet, plus regel dat plannen in docs/plans/ landen Nuance op Git Workflow-regel - Auto-commit-verbod uit /insights was te strict: botst met Track A commit-per-laag dat we de afgelopen sprints (M9/M10/M11) consequent doen - Verfijnd: tijdens directed sprint-flow is commit-per-laag impliciet geautoriseerd; ad-hoc/out-of-band werk vereist 'commit it'-bevestiging - git push blijft altijd expliciet (de hele kostenbeheersings-policy gaat daarover) Stale content gesynced - MCP-tools-lijst 9 → 13 (M11 question-tools toegevoegd: ask_user_question, get_question_answer, list_open_questions, cancel_question), gegroepeerd per categorie - DoD: 'Alle 7 API-endpoints' → 'Alle gedocumenteerde API-endpoints (zie docs/API.md)' (we hebben er nu 13+) - Env vars: CRON_SECRET toegevoegd; SESSION_SECRET min-32-chars eis vermeld; verwijzing naar lib/env.ts en .env.example Co-authored-by: Claude Opus 4.7 (1M context) --- CLAUDE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a539598..07da6e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,6 +85,17 @@ Vercel Analytics (@vercel/analytics/next) --- +## UI Library Conventions + +- Dit project gebruikt **`@base-ui/react`**, *niet* Radix UI — ondanks dat shadcn-componenten visueel-identiek zijn +- Composition gebeurt via de **`render`-prop**, niet via Radix's `asChild`: + - ✅ `}>...` + - ❌ `` — geeft TS-errors +- Vóór je een nieuwe shadcn-/UI-primitive gebruikt: grep eerst de codebase voor bestaand gebruik en volg dat patroon (`grep -rn "PrimitiveTrigger" components/`) +- shadcn-componenten in `components/ui/` zijn dunne wrappers rond `@base-ui/react`-primitives; lees die voor de exacte prop-API + +--- + ## Implementatiepatronen Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven. @@ -108,11 +119,14 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven. ## Env vars ```bash -DATABASE_URL="" # postgresql://... -DIRECT_URL="" # alleen bij Neon/cloud -SESSION_SECRET="" # openssl rand -base64 32 +DATABASE_URL="" # postgresql://... (verplicht) +DIRECT_URL="" # postgresql://... — pooler-bypass voor LISTEN/NOTIFY (Neon/cloud) +SESSION_SECRET="" # min 32 chars; openssl rand -base64 32 +CRON_SECRET="" # M11 — Bearer-secret voor /api/cron/*; verplicht in productie, optioneel lokaal (genereer met openssl rand -base64 32) ``` +Volledige Zod-schema in `lib/env.ts`. `.env.example` is de canonieke lijst voor nieuwe checkouts. + --- ## Conventies @@ -154,11 +168,18 @@ Elke `git push` naar een feature-branch triggert een Vercel preview-deployment. - 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) +- **Direct pushen naar `main`** — die branch heeft protection rules; gebruik altijd een PR -### Uitzonderingen +### Wanneer wel commit-zonder-vragen, wanneer niet + +- **Tijdens een directed sprint-flow** (Track A: `mcp__scrum4me__implement_next_story` of een expliciete *"implementeer M{N}"*-opdracht): commit-per-laag conform de Commit Strategy hieronder is impliciet geautoriseerd — niet per commit vragen +- **Bij ad-hoc / out-of-band werk** (bug-fix tussendoor, refactor, kleine wijziging op verzoek): toon de diff + voorgestelde commit-message en wacht op `"commit it"` voordat je `git commit` draait +- **`git push` is altijd expliciet** — de scope van de policy gaat over preview-builds, dus push gebeurt alleen na gebruiker-test, ongeacht commit-context + +### Uitzonderingen op de push-regel - 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 +- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden (via een PR — zie boven) ### Wanneer aanpassen @@ -166,6 +187,14 @@ Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) g --- +## Plan Mode + +- Voor simpele, goed-afgebakende file-edits: **niet** in plan mode gaan — gewoon de wijziging maken +- Reserveer plan mode voor multi-step refactors, ambigue verzoeken, of milestone-planning waarbij design-keuzes vooraf bevestigd moeten worden +- Plannen die uit plan mode komen: opslaan als `docs/plans/M{N}-{slug}.md` (zie memory `feedback_plan_location`), niet als ephemeral systeem-bestand + +--- + ## Commit Strategy (STRICT) > **Core rule: één commit = één verantwoordelijkheid** @@ -216,6 +245,8 @@ docs(ST-XXX): document profile feature --- + + ## Scrum-terminologie | Correct | Niet gebruiken | @@ -231,15 +262,24 @@ docs(ST-XXX): document profile feature 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 +### Tools beschikbaar in Claude Code (13) +**Read / context:** - `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 + +**Task / story writes:** - `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` +**Vraag-antwoord-kanaal (M11):** +- `mcp__scrum4me__ask_user_question` — post een vraag over een story; optionele `wait_seconds` (max 600) polt voor het antwoord +- `mcp__scrum4me__get_question_answer` — huidige status + antwoord (voor latere session-pickup) +- `mcp__scrum4me__list_open_questions` — eigen vragen, max 50, recente eerst +- `mcp__scrum4me__cancel_question` — asker-only annulering van een eigen open vraag + ### Prompt - `implement_next_story` (arg: `product_id`) — end-to-end workflow @@ -250,13 +290,23 @@ Wekelijks (maandag 08:00 Amsterdam) draait de remote agent `trig_015FFUnxjz9WMuh --- +## Deployment (Vercel) + +- **Sharp** moet Linux-binaries hebben voor de Vercel-runtime: `npm i --include=optional sharp` of platform-specifieke deps configureren in `package.json` +- **Externe image hostnames** in `next.config.js` `images.remotePatterns` configureren *vóór* `next/image` op die hosts wijst — anders 500 in productie +- **Vercel cron**: Hobby-plan staat alleen daily crons toe (max 1×/dag); Pro ondersteunt fijnmaziger. Bij wijziging van `vercel.json` `crons` ook `docs/API.md` + relevante pattern-docs updaten +- **`CRON_SECRET`** moet als env-var op de Vercel-project-omgeving staan vóór de eerste cron-run, anders 401 op `/api/cron/*`-endpoints +- **Preflight** vóór deploy: `npm run lint && npm test && npm run build` — falende build laat een PR niet door (CI blokkeert merge per ST-610) + +--- + ## 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 +- [ ] Alle gedocumenteerde API-endpoints werken via curl (zie `docs/API.md`) - [ ] Demo-gebruiker heeft geen schrijfrechten - [ ] App opzetbaar via README zonder extra hulp - [ ] CI/CD actief — falende build blokkeert merge