AGENTS.md: Configureer uw repository-instructies
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van de pagina Custom instructions with AGENTS.md: Codex leest alleen
AGENTS.md-bestanden die zich tussen de projectroot en de huidige werkmap bevinden (plus het globale bestand op~/.codex). Een bestand in een submap buiten dit pad wordt niet geladen, in tegenstelling tot wat de vorige versie impliceerde. Bron: AGENTS.md.
Het Codex-configuratiebestand onder de knie krijgen
U heeft AGENTS.md ontdekt in Les 3. Hier duiken we in geavanceerde patronen: het verschil tussen een decoratief bestand (drie regels geschreven bij de start en vervolgens vergeten) en een bestand dat het gedrag van de agent daadwerkelijk stuurt in een live project.
De hiërarchie van AGENTS.md
Codex leest deze bestanden hiërarchisch, van algemeen naar specifiek: eerst het globale bestand in uw Codex-map (~/.codex/AGENTS.md, of AGENTS.override.md als dit bestaat), en vervolgens, beginnend vanaf de projectroot, de bestanden in de mappen die worden doorlopen tot aan de huidige werkmap. Op een gestructureerd project ziet de boom er als volgt uit:
mon-projet/
AGENTS.md → Globale regels (lage prioriteit)
src/
AGENTS.md → Regels voor alle broncode
api/
AGENTS.md → Regels specifiek voor API's
routes/
AGENTS.md → Regels voor routes
components/
AGENTS.md → Regels voor React-componenten
tests/
AGENTS.md → Regels voor tests
Regels stapelen zich op: Codex voegt bestanden samen van de root tot aan de huidige map, waarbij die het dichtst bij die map liggen, als laatste worden gelezen en algemene instructies overschrijven. Eén punt wordt vaak verkeerd begrepen: alleen mappen op het pad tussen de root en de huidige map worden gelezen. Als uw root-bestand any verbiedt terwijl tests/AGENTS.md soepelere asserties in mocks toestaat, geldt die tolerantie alleen wanneer Codex werkt vanuit tests/ of een van de submappen daarvan; gestart vanuit de root leest het tests/AGENTS.md niet. GitHub-code-review werkt anders: Codex doorzoekt daar de volledige repository naar AGENTS.md-bestanden en past de reviewregels (## Code Review Rules) toe uit het bestand dat het dichtst bij de betreffende code ligt. Samenvoegen stopt standaard bij 32 KiB (project_doc_max_bytes): een te lang bestand wordt afgekapt.
De secties die het bestand vormen
Context komt eerst, omdat deze elke daaropvolgende beslissing vormgeeft. Een SaaS-toepassing die onder de AVG (Algemene Verordening Gegevensbescherming) valt, wordt niet op dezelfde manier gecodeerd als een interne tool voor vijf personen:
## Context
SaaS-factuurbeheertoepassing voor Franse MKB'ers.
Naleving van de AVG is verplicht. Data gehost in Frankrijk (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authenticatie: Better Auth met server-sessies.
Wetende dat het gegevens verwerkt die onder de AVG vallen, zal Codex de verwachte beschermingen toevoegen zonder dat u deze bij elk verzoek hoeft te specificeren. Daarna volgen de conventies, die één vraag beantwoorden: hoe ziet correcte code er hier uit?
## Conventies
- Strict TypeScript (geen any, geen impliciete any)
- Alleen functionele React-componenten
- Naamgeving: kebab-case bestanden, PascalCase componenten,
camelCase variabelen
- Imports: @/ voor pad-aliassen
- Validatie: Zod voor alle gebruikersinvoer
- Fouten: aangepaste foutklassen in src/lib/errors.ts
- Logging: gebruik src/lib/logger.ts (geen console.log)
De sectie commando’s wordt het vaakst weggelaten, en de afwezigheid ervan is kostbaar: zonder deze commando’s kan Codex zijn eigen werk niet verifiëren en retourneert het code die het nooit heeft uitgevoerd of getest.
## Commando's
- `npm run dev` — Ontwikkelserver (poort 4321)
- `npm run build` — Productiebuild
- `npm run test` — Vitest-tests
- `npm run test:e2e` — Playwright-tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma-migraties
- `npm run db:seed` — Database seed
Strikte regels vormen de vangrail. Geformuleerd als “NOOIT” en “ALTIJD”, voorkomen ze fouten die een hele avond kosten om op te lossen: een verwijderde Prisma-migratie die u vanuit productie moet reconstrueren, een gecommitte geheim dat moet worden ingetrokken, of een innerHTML die in een component is geslopen en een XSS-kwetsbaarheid opent.
## Strikte regels (breek deze NOOIT)
- Wijzig NOOIT het Prisma-schema zonder een migratie aan te maken
- Sla NOOIT geheimen op in code (gebruik .env)
- Gebruik NOOIT innerHTML (XSS-risico)
- Verwijder NOOIT een bestaande Prisma-migratie
- Stel NOOIT interne ID's bloot in openbare URL's
- Valideer ALTIJD gebruikersinvoer met Zod
- Gebruik ALTIJD Prisma-transacties voor bewerkingen op meerdere tabellen
Ten slotte beschrijft de architectuur de toegestane stroom tussen lagen. Zonder dit produceert Codex code die werkt, maar uw structuur omzeilt—bijvoorbeeld een route die rechtstreeks Prisma bevraagt, omdat dat de kortste weg was.
## Architectuur
Lagen:
1. Routes (src/pages/) → ontvangen verzoeken
2. Services (src/services/) → bedrijfslogica
3. Repositories (src/repositories/) → datatoegang
Regel: Routes MOGEN Prisma NIET rechtstreeks benaderen.
Alles gaat via een service, die via een repository gaat.
Hieraan worden, project per project, instructies toegevoegd die specifiek zijn voor elke gebruikte technologie:
## React
- Geef standaard de voorkeur aan Server Components
- Client Components alleen wanneer nodig (interactiviteit)
- Geen useEffect voor data ophalen (gebruik Server Actions)
- Lokale state met useState, globale state met Zustand
## Prisma
- Relaties: neem verplichte velden altijd expliciet op
- Paginatie: gebruik cursor-gebaseerd, niet offset-gebaseerd
- Soft delete: gebruik deletedAt in plaats van DELETE
Twee patronen die verrassingen voorkomen
Het declareren van verwachte omgevingsvariabelen verhindert dat Codex sleutelnamen verzint bij het schrijven van een script, of per ongeluk een gevoelige waarde logt in een debug-trace:
## Vereiste omgevingsvariabelen
- DATABASE_URL — PostgreSQL-verbindings-URL
- AUTH_SECRET — Geheim voor Better Auth (min. 32 tekens)
- SMTP_HOST — SMTP-server voor e-mails
- STRIPE_SECRET_KEY — Stripe API-sleutel (nooit loggen)
Het benoemen van uw voorkeursbibliotheken, en vooral die welke u weigert, lost een terugkerende ergernis op: de agent installeert een afhankelijkheid die op zich perfect geldig is, maar die uw team twee jaar geleden heeft afgewezen na een slechte ervaring.
## Afhankelijkheden
Als u nodig heeft:
- Validatie → Zod (NIET Joi, NIET Yup)
- Datums → date-fns (NIET moment, NIET dayjs)
- HTTP-client → ofetch (NIET axios)
- Tests → Vitest (NIET Jest)
- E2E → Playwright (NIET Cypress)
Het bestand levend houden
AGENTS.md evolueert met uw code, net als een test of een README. Werk het bij zodra u een nieuwe conventie overneemt, wisselt van bibliotheken of frameworks, en vooral zodra u een terugkerende Codex-fout identificeert: dat laatste geval signaleert altijd een ontbrekende instructie in plaats van een modelstoring. Een vierde, subtielere trigger is het waard om op te letten: wanneer een nieuwe ontwikkelaar een vraag stelt die AGENTS.md had moeten beantwoorden, hoort dat antwoord in het bestand thuis.
Belangrijkste punten
- De hiërarchie van
AGENTS.mdmaakt steeds specifiekere instructies mogelijk - Commando’s zijn cruciaal zodat Codex zijn werk kan verifiëren
- NOOIT-regels zijn het belangrijkst om fouten te voorkomen
- Documenteer voorkeursafhankelijkheden om slechte keuzes te voorkomen
- Onderhoud
AGENTS.mdals levende code