Scrum4Me/docs/plans/archive/2026-04-27-claude-md-workflow-update.md

title	status	audience	language	last_updated	applies_to
CLAUDE.md workflow-update na M7 + ST-509/511/512/513	done	maintainer contributor	nl	2026-05-03	M7 ST-509 ST-511 ST-512 ST-513

Plan: CLAUDE.md workflow-update na M7 + ST-509/511/512/513

Aanleiding

CLAUDE.md is voor het laatst groot bijgewerkt op 2026-04-25 (docs/decisions/agent-instructions-history.md). Sindsdien is er substantieel werk geland dat de workflow raakt:

• ST-511 entity codes (Product/PBI/Story) — branch- en commit-conventies hangen er nu aan vast
• ST-513 API hardening — 400 (malformed JSON) vs 422 (zod-validatie), lowercase status-enums op API-grens, StoryLog.metadata JSONB
• PR #2 review-saga (8 testbestanden faalden bij contract-flip) — duidelijk leerpunt: testpariteit hoort bij contract-wijziging
• M7 MCP-server — Claude Code praat nu native met Scrum4Me via mcp__scrum4me__* tools en de prompt implement_next_story. De huidige 7-stap "vraag-de-gebruiker"-loop in CLAUDE.md is daarmee gedateerd
• lib/code-server.ts vs lib/code.ts — split is nodig om client-bundle vrij te houden van pg. Als gotcha noemenswaard
• Schema-drift cron (trig_015FFUnxjz9WMuhhWNGBQKFD) — wekelijkse remote agent — agents moeten weten wat ze met zijn rapport doen

Doel: CLAUDE.md weerspiegelt de werkelijke 2026-04-27 workflow zonder dat het een changelog wordt.

Scope — wat we wél en niet aanpassen

Wel (in CLAUDE.md):

1. Workflow-sectie — MCP-first met expliciete fallback
2. Conventies — uitbreiden met status-enums, foutcodes, test-pariteit, entity codes in commits
3. Implementatiepatronen — rij voor lib/task-status.ts en lib/code-server.ts-boundary toevoegen
4. Nieuwe sectie "MCP-integratie" — wat staat er, hoe te gebruiken, link naar mcp repo
5. Definition of Done — markeer expliciet als MVP-scope; M7 is post-MVP en heeft eigen acceptatie

Niet:

• Geen changelog of historiek in CLAUDE.md zelf — dat hoort in docs/decisions/agent-instructions-history.md (separate update)
• Geen volledige herschrijving — bestaande structuur blijft (Wat is Scrum4Me, Spec-tabel, Stack, Conventies, Commit Strategy, etc.)
• Geen wijziging in AGENTS.md (Codex) — die heeft geen MCP, mag los blijven
• Geen wijziging in functional-spec/architecture/styling docs — die zijn al actueel

Concrete edits in CLAUDE.md

1. Sectie "Specificatiedocumenten" — uitbreiden

Voeg toe onder de bestaande tabel:

Document	Gebruik voor
https://github.com/madhura68/scrum4me-mcp	MCP-server repo: tools, prompts, schema-sync workflow

(docs/api/rest-contract.md staat er al — laten staan.)

2. Sectie "Waar te beginnen" — herschrijven

Vervang de 7-stap manual loop door een dual-track:

Track A — via Claude Code MCP (aanbevolen):

1. Roep `mcp__scrum4me__implement_next_story` aan met product_id
   (of `list_products` als je het id niet weet)
2. De prompt orkestreert: get_claude_context → log_implementation
   → per task in_progress/done → log_test_result → log_commit
3. Bouw de tasks in volgorde van `sort_order`
4. Test: `npm run lint && npm test && npm run build`
5. Commit per laag (zie Commit Strategy)

Track B — manueel (Codex of zonder MCP):

• Lees task in docs/backlog/index.md
• Volg verder de bestaande 7-stappen-loop

3. Sectie "Implementatiepatronen" — uitbreiden

Twee rijen toevoegen aan de patronen-tabel:

Patroon	Bestand
Status-enum mapping (DB ↔ API)	lib/task-status.ts
Client/server module-boundary	regel: *-server.ts bevat DB-calls, *.ts is pure helpers — nooit import { ... } from 'lib/foo-server' in een client component

4. Sectie "Conventies" — vier regels toevoegen

Voeg toe aan de bestaande lijst:

• 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 via lib/task-status.ts-mappers — nooit ad-hoc lowercase elders
• Foutcodes API: 400 alleen voor malformed JSON-body (parse-fout); 422 voor zod-validatie en well-formed-maar-niet-acceptabel; 403 voor demo-tokens. Documenteren in docs/api/rest-contract.md
• Tests volgen contract: bij API-contract-wijziging (status, foutcode, response-shape) MOET in dezelfde commit ook __tests__/api/ bijgewerkt worden — een falende test op review betekent niet dat de tests "stuk zijn" maar dat de wijziging onvolledig is

5. Nieuwe sectie "MCP-integratie" — toevoegen vóór "Definition of Done"

Korte sectie (~15 regels):

## MCP-integratie

Scrum4Me heeft een eigen MCP-server (repo: `madhura68/scrum4me-mcp`)
die deze API exposed als native tools voor Claude Code.

### Tools beschikbaar in Claude Code
- `mcp__scrum4me__health` — service + DB ping
- `mcp__scrum4me__list_products` — producten waar je toegang tot hebt
- `mcp__scrum4me__get_claude_context` — bundled product/sprint/story/todos
- `mcp__scrum4me__update_task_status`, `_update_task_plan`
- `mcp__scrum4me__log_implementation`, `_log_test_result`, `_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 een remote agent
(`trig_015FFUnxjz9WMuhhWNGBQKFD`) die `vendor/scrum4me` syncet en
`prisma:generate + typecheck` uitvoert in mcp. Als die agent
een drift-rapport opent, hoort dat **vóór** een Scrum4Me-PR met
schema-wijziging gemerged kan worden — zodat de MCP-server niet
stilletjes breekt op runtime.

6. Sectie "Definition of Done" — kop verduidelijken

Wijzig ## Definition of Done → ## Definition of Done (MVP) en voeg eronder een korte zin toe: "M7 (MCP-server) is post-MVP en heeft eigen acceptatie in docs/backlog/index.md."

Bijwerken van auditdoc

Voeg een sectie aan docs/decisions/agent-instructions-history.md toe (datum: 2026-04-27) met:

• Aanleiding: ST-509/511/512/513 + M7 + PR #2 review-saga
• Gecontroleerde wijzigingen: zelfde tabel-stijl als 2026-04-25
• Nieuwe regels: status-enums op API-grens, error-code split 400/422, test-pariteit bij contract-wijziging, client/server module-boundary
• Verwijzing naar mcp repo en schema-drift cron

Volgorde van uitvoering

1. Edits in CLAUDE.md — alle 6 secties hierboven, in volgorde
2. Edits in docs/decisions/agent-instructions-history.md — nieuwe sectie 2026-04-27
3. npm run lint — sanity check
4. Commit als één logische change — docs(workflow): align CLAUDE.md with M7 and post-PR-#2 contract
5. PR openen — review-bare scope, deploys triggeren maar zijn docs-only

Wat het NIET oplost

• AGENTS.md (Codex) blijft achter; los aan te pakken indien gewenst
• Eventuele drift in docs/specs/functional.md rond status-enums — niet onderzocht; te volgen bij volgende audit
• Geen check of de losse pattern-files in docs/patterns/ nog kloppen — ook volgende audit

Geschatte size

• ~80 regels toegevoegd/gewijzigd in CLAUDE.md
• ~30 regels nieuw in docs/decisions/agent-instructions-history.md
• 1 commit, 1 PR