b39c3ec2e1
* docs(cleanup): archief verouderde plannen, backlog en root-duplicaten
- 6 plans naar docs/old/plans/ (PBI-11/75/78, user-settings-store, Local github setup, lees-de-readme — laatste was verkeerde repo)
- docs/backlog/ naar docs/old/backlog/ (pre-MCP statische registry; live werk loopt via Scrum4Me-MCP)
- 6 root-level duplicaten naar docs/old/ (functional, {pbi,story,task}-dialog, product-backlog, backlog)
- 2 landing plans (niet uitgevoerd) krijgen archived: true frontmatter — blijven op plek maar uit INDEX
- scripts/generate-docs-index.mjs: skip docs/old/** + skip archived: true
- CLAUDE.md: rijen docs/backlog/, docs/plans/<key>-*.md, docs/manual/ weg; Track B-sectie verwijderd
- README.md / CHANGELOG.md / docs/plans/v1-readiness.md: link-fixes naar nieuwe locaties
Verify groen (lint + typecheck + 718 tests). docs/INDEX.md geregenereerd.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(cleanup): registreer handmatige verplaatsingen en fix referenties
- 4 plans verplaatst naar docs/old/plans/ (M10-qr-pairing-login, auto-pr-deploy-sync, docs-restructure-ai-lookup, v1-readiness)
- 3 archive-plans verplaatst naar docs/old/plans/ (archive-map nu leeg)
- ST-1114-copilot-reviews + 3 research-docs naar nieuwe docs/Ideas/ map
- Duplicaat docs/old/2026-04-27-m8-realtime-solo.md verwijderd (origineel zit in docs/old/plans/)
- Link-fixes naar nieuwe locaties:
- CHANGELOG.md → docs/old/plans/v1-readiness.md
- docs/runbooks/deploy-control.md → docs/old/plans/auto-pr-deploy-sync.md (2x)
- docs/runbooks/worker-idempotency.md → docs/old/plans/auto-pr-deploy-sync.md
- docs/plans/docs-restructure-pbi-spec.md → docs/old/plans/docs-restructure-ai-lookup.md (4x text + 2x href)
- docs/INDEX.md geregenereerd (96 docs, was 100)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
150 lines
7.1 KiB
Markdown
150 lines
7.1 KiB
Markdown
---
|
|
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
|