88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|