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

---
title: "CLAUDE.md workflow-update na M7 + ST-509/511/512/513"
status: done
audience: [maintainer, contributor]
language: nl
last_updated: 2026-05-03
applies_to: [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):

```markdown
## 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