From 86a5397517d24f7b6579f380e811ad7e3c90456d Mon Sep 17 00:00:00 2001 From: Janpeter Visser Date: Mon, 27 Apr 2026 00:28:58 +0200 Subject: [PATCH] docs(workflow): align CLAUDE.md with M7 and post-PR-#2 contract (#4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update agent-facing docs to match the workflow that actually shipped in ST-509/511/512/513 and M7 (scrum4me-mcp). CLAUDE.md - Spec-tabel: link toegevoegd naar de scrum4me-mcp repo - Waar te beginnen: dual-track — Track A via mcp__scrum4me__implement_ next_story (aanbevolen), Track B is de bestaande manuele 7-stappen loop voor Codex/zonder MCP - Implementatiepatronen: rijen voor lib/task-status.ts mappers en client/server module-boundary (bv. lib/code.ts vs lib/code-server.ts) - Conventies: entity codes in commit-titles, lowercase API-status, 400/422 error-code split, verplichte test-pariteit bij contract- wijziging - Nieuwe sectie "MCP-integratie" — alle 9 tools + prompt + schema-drift cron (trig_015FFUnxjz9WMuhhWNGBQKFD, ma 08:00 Amsterdam) - Definition of Done expliciet als MVP; M7 is post-MVP agent-instruction-audit.md - Round 2 (2026-04-27) sectie met aanleiding, gecontroleerde wijzigingen en nieuwe preventieve regels (test-pariteit, status-enum boundary, error-code split, module-boundary) Co-authored-by: Claude Opus 4.7 (1M context) --- CLAUDE.md | 47 +++++++++++++++++- docs/agent-instruction-audit.md | 85 +++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d9e4572..7c6b301 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,7 @@ Lees het relevante document voordat je aan een feature begint. Nooit gokken over | `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 | +| [`madhura68/scrum4me-mcp`](https://github.com/madhura68/scrum4me-mcp) | MCP-server repo: native tools voor Claude Code, schema-sync via git submodule | --- @@ -37,7 +38,18 @@ M0 (ST-001–008) → M1 (ST-101–110) → M2 (ST-201–210) → M6 (ST-601–612) ``` -Per task: +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 @@ -85,6 +97,8 @@ Lees het relevante patroon vóór je begint. Nooit uit het hoofd schrijven. | 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 | --- @@ -110,6 +124,10 @@ SESSION_SECRET="" # openssl rand -base64 32 - **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" --- @@ -174,7 +192,32 @@ docs(ST-XXX): document profile feature --- -## Definition of Done +## 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) diff --git a/docs/agent-instruction-audit.md b/docs/agent-instruction-audit.md index a3bc7c2..1cd185f 100644 --- a/docs/agent-instruction-audit.md +++ b/docs/agent-instruction-audit.md @@ -86,3 +86,88 @@ Bij securitywijzigingen hoort minimaal een test die laat zien dat cross-user of - verificatiecommands. Deze regels zijn korter dan `CLAUDE.md`, maar bewust dwingend: ze moeten direct gelezen worden bij elke Codex-taak in deze repo. + +--- + +# Agent Instruction Audit — Round 2 + +Datum: 2026-04-27 + +## Aanleiding + +Sinds ronde 1 (2026-04-25) is er substantieel werk geland dat de agent-workflow raakt: + +- **ST-509** Todo description (max 2000) +- **ST-511** Entity codes voor Product/PBI/Story (auto-default + manual override + retry op race condition) +- **ST-512** REST API uitgebreid met `code`, `description`, `implementation_plan` in alle endpoints +- **ST-513** API hardening voor Claude Code: `GET /api/health`, `GET /api/products/:id/claude-context`, lowercase status-enums op de API-grens, `StoryLog.metadata` JSONB, validatie-fouten van `400` → `422`, nieuwe `docs/API.md` +- **PR #2 Codex-review-saga** — 8 testbestanden faalden bij de contract-flip; tests werden niet meebijgewerkt. Twee P2-issues van Codex: malformed JSON moet `400` blijven (P2.1), en `status: review` werd geaccepteerd terwijl de sprint-UI er niet mee om kan gaan (P2.2) +- **M7: scrum4me-mcp** — aparte MCP-server repo (`madhura68/scrum4me-mcp`) met 9 tools en 1 prompt voor Claude Code, schema gedeeld via git submodule +- **lib/code.ts vs lib/code-server.ts** — gesplitst om client-bundle vrij te houden van `pg` (gaf eerst `Module not found: 'dns'` build-error) +- **Wekelijkse schema-drift cron** (`trig_015FFUnxjz9WMuhhWNGBQKFD`) — remote agent die ma 08:00 Amsterdam de MCP-submodule syncet en typecheckt + +## Gecontroleerde wijzigingen + +| Wijziging | Code-locatie | Documentatie bijgewerkt | +|---|---|---| +| Lowercase status-enums op REST-grens, mappers naar DB-enum | `lib/task-status.ts`, `app/api/tasks/[id]/route.ts`, `app/api/sprints/[id]/tasks/route.ts`, `app/api/products/[id]/next-story/route.ts` | `docs/API.md`, `CLAUDE.md` | +| 400 (malformed JSON) gescheiden van 422 (zod-validatie) | `app/api/tasks/[id]/route.ts`, `app/api/stories/[id]/tasks/reorder/route.ts`, `app/api/todos/route.ts`, `app/api/stories/[id]/log/route.ts` | `docs/API.md`, `CLAUDE.md` | +| `status: review` geweigerd door PATCH `/api/tasks/:id` zolang sprint-UI geen REVIEW rendert | `app/api/tasks/[id]/route.ts` | `docs/API.md` | +| Entity codes (Product/PBI/Story) met auto-default + retry-on-P2002 | `actions/products.ts`, `actions/pbis.ts`, `actions/stories.ts`, `lib/code.ts`, `lib/code-server.ts` | `docs/scrum4me-backlog.md` (ST-511) | +| `StoryLog.metadata` JSONB | `prisma/schema.prisma`, `prisma/migrations/20260426214905_add_story_log_metadata/`, `app/api/stories/[id]/log/route.ts` | `docs/API.md` | +| Health- en bundled-context endpoints voor Claude Code | `app/api/health/route.ts`, `app/api/products/[id]/claude-context/route.ts` | `docs/API.md`, `CLAUDE.md` | +| MCP-server gepubliceerd als aparte repo | `madhura68/scrum4me-mcp` (extern) | `CLAUDE.md` (sectie MCP-integratie), `docs/scrum4me-backlog.md` (M7) | + +## Nieuwe preventieve regels + +### Test-pariteit bij contract-wijziging + +Een wijziging die een API-contract aanraakt (status, foutcode, response-shape, request-shape) is pas klaar als `__tests__/api/` in dezelfde commit meegaat. Wat NIET acceptabel is: + +- "Tests gaan rood maar de implementatie is correct" — herstel óf implementatie óf test, niet later +- Stilletjes 8 testbestanden laten breken zoals in PR #2 — Codex/CI vangt het, maar te laat in de cyclus + +### Status-enums boundary-conversie + +API exposeert lowercase, DB houdt UPPER_SNAKE. Conversie uitsluitend via `lib/task-status.ts`-mappers (`taskStatusToApi`, `taskStatusFromApi`, `storyStatusToApi`, `storyStatusFromApi`). Verboden: + +- Ad-hoc `status.toLowerCase()` of `status.toUpperCase()` in route handlers +- Direct vergelijken van API-input met DB-enum (`if (body.status === 'IN_PROGRESS')`) — input is altijd lowercase +- Een nieuwe enum-waarde toevoegen zonder de mapper bij te werken + +### Error-code split 400/422 + +- `400`: parse-fout op `request.json()` — wikkel altijd in `try/catch` +- `422`: zod-validatie of well-formed-maar-niet-acceptabel (bv. `task_id` van andere story) +- `403`: demo-token op write +- Documenteer per endpoint in `docs/API.md` + +### Client/server module-boundary + +`lib/foo-server.ts` mag DB-calls (`prisma`), node-only deps (`pg`, `crypto.createHash`) en server-actions doen. `lib/foo.ts` is pure helpers, client-veilig. Een client-component (`'use client'`) mag nooit uit een `*-server.ts`-module importeren — dat haalt `pg` of `dns` mee de bundle in en breekt de build. + +### Verplichte verificatie vóór oplevering + +Naast bestaande lint/test/build-stappen voor MCP-relevante wijzigingen ook: + +```bash +# In scrum4me-mcp na een schema-wijziging in Scrum4Me: +npm run sync-schema && npm run prisma:generate && npm run typecheck +``` + +De wekelijkse cron doet dit automatisch, maar ad-hoc checken is nog steeds verstandig vóór een Scrum4Me-PR met migratie naar productie gaat. + +## Claude Code + +`CLAUDE.md` is uitgebreid met: + +- Specificatiedocumenten-rij voor `madhura68/scrum4me-mcp` +- Dual-track workflow (Track A: MCP-prompt; Track B: manueel) +- Twee patroon-rijen: `lib/task-status.ts` en client/server module-boundary +- Vier nieuwe conventies: entity codes in commits, lowercase API-status, error-code split, test-pariteit +- Nieuwe sectie "MCP-integratie" met tools, prompt en schema-drift cron +- Definition of Done expliciet als MVP-scope; M7 is post-MVP + +## Codex + +`AGENTS.md` is in deze ronde **niet** bijgewerkt — Codex heeft geen MCP-toegang en de Track B-workflow daar werkt nog. Bij volgende ronde apart uitbreiden met de status-enum/error-code/test-pariteit regels (die zijn ook voor Codex relevant).