Scrum4Me/docs/agent-instruction-audit.md

Agent Instruction Audit

Datum: 2026-04-25

Aanleiding

Tijdens de code review kwamen twee soorten fouten naar voren:

• Server Actions vertrouwden client-provided IDs te veel nadat alleen de parent-resource was gecontroleerd.
• Documentatie liep achter op dependency-, API- en deploymentwijzigingen.

Dit document legt vast welke wijzigingen zijn gecontroleerd, welke documentatie is bijgewerkt en welke instructies Claude Code en Codex voortaan expliciet moeten volgen.

Gecontroleerde wijzigingen

Wijziging	Code-locatie	Documentatie bijgewerkt
Reorder-acties valideren alle IDs binnen de juiste parent-scope	actions/stories.ts, actions/sprints.ts	docs/scrum4me-architecture.md, docs/patterns/server-action.md, docs/patterns/sort-order.md, CLAUDE.md, AGENTS.md
Sprint afronden accepteert alleen stories uit de actieve sprint	actions/sprints.ts	docs/scrum4me-architecture.md, docs/patterns/server-action.md, AGENTS.md
Todo-promotie gebruikt scoped todo lookup en pbi.product_id als bron van waarheid	actions/todos.ts	docs/scrum4me-architecture.md, docs/patterns/server-action.md, CLAUDE.md, AGENTS.md
GET /api/products retourneert ook gedeelde producten via product_members	app/api/products/route.ts	README.md, docs/scrum4me-functional-spec.md, docs/scrum4me-backlog.md, docs/patterns/route-handler.md
sharp is directe runtime dependency	package.json, package-lock.json	README.md, docs/scrum4me-architecture.md, CLAUDE.md
Vercel Analytics is toegevoegd aan de root layout	app/layout.tsx, package.json, package-lock.json	README.md, docs/scrum4me-architecture.md, CLAUDE.md
.env.example ontbrak ondanks verwijzingen in architectuurdocs	.env.example	README.md, docs/scrum4me-architecture.md

Preventieve regels

Access-control regels

Agents mogen nooit aannemen dat een ID veilig is omdat de UI hem normaal gesproken correct doorgeeft. Elke Server Action en Route Handler moet bij writes de volledige resource-scope bewijzen.

Concrete regels:

• Gebruik productAccessFilter(userId) voor product-scoped resources waar eigenaar en teamlid toegang hebben.
• Gebruik owner-only filters alleen bij echte eigenaarsacties.
• Valideer bulk-ID's met id in (...) plus parent-scope voordat er wordt geschreven.
• Weiger dubbele IDs in reorder- en decision-payloads.
• Leid denormalized foreign keys af van de database-parent, niet van client-input.
• Valideer runtime waarden met Zod of expliciete runtime checks; TypeScript types alleen zijn onvoldoende.
• Gebruik scoped deletes/updates nadat ownership bewezen is.

Documentatie-regels

Een codewijziging is niet klaar als de documentatie een oud contract beschrijft. Agents moeten bij elke wijziging nagaan of deze plekken geraakt worden:

• README.md: setup, scripts, dependencies, deployment, API-overzicht.
• docs/scrum4me-functional-spec.md: functionele eisen en API-contracten.
• docs/scrum4me-architecture.md: stack, datamodel, securitymodel, env vars, deployment.
• docs/scrum4me-backlog.md: "done when"-criteria en scope van backlog-items.
• docs/patterns/: herbruikbare implementatiepatronen.
• CLAUDE.md en AGENTS.md: agent-regels die de fout in de toekomst voorkomen.

Dependency-regels

• Elke runtime import moet als directe dependency in package.json staan.
• Als een dependency aan deploymentgedrag raakt, moet README of architectuurdocs dat noemen.
• Na npm install moet package-lock.json meegaan in dezelfde change.

Verification-regels

Voor oplevering:

npm run lint
npm test
npm run build

Bij securitywijzigingen hoort minimaal een test die laat zien dat cross-user of cross-scope input wordt geweigerd. Als die test nog niet bestaat, noteer dat expliciet in de oplevering.

Claude Code

CLAUDE.md is aangescherpt met:

• een verwijzing naar dit auditdocument;
• de directe stackwijzigingen voor Sharp en Vercel Analytics;
• expliciete access-control regels voor productAccessFilter, bulk-ID's en foreign-key afleiding;
• een docs-sync regel voor gedrags-, API-, dependency- en deploymentwijzigingen.

Codex

AGENTS.md is uitgebreid van alleen Next.js-waarschuwing naar projectregels voor:

• access control;
• documentatie-sync;
• verificatiecommands.

Deze regels zijn korter dan CLAUDE.md, maar bewust dwingend: ze moeten direct gelezen worden bij elke Codex-taak in deze repo.