docs(workflow): align CLAUDE.md with M7 and post-PR-#2 contract (#4)
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) <noreply@anthropic.com>
This commit is contained in:
GitHub
parent
c8bab7396a
commit
86a5397517
2 changed files with 130 additions and 2 deletions
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue