AGENTS.md instellen: zo onthoudt Codex de regels van je project

Je legt Codex voor de derde keer uit dat je in dit project pnpm gebruikt en dat de tests met make test draaien. Dat hoeft niet. Codex leest voor elke opdracht een instructiebestand in, en als je dat goed neerzet, weet de agent die afspraken vanaf dan uit zichzelf. Vijf stappen, een kwartier werk.

Stap 1: zet je persoonlijke voorkeuren globaal

Begin met de dingen die in élk project gelden. Die horen in je Codex-home:

mkdir -p ~/.codex

Maak daar AGENTS.md aan met je vaste werkafspraken:

## Werkafspraken

- Draai `npm test` na elke wijziging in JavaScript-bestanden.
- Gebruik `pnpm` bij het installeren van dependencies.
- Vraag om bevestiging voor je een nieuwe productie-dependency toevoegt.

Houd het kort en dwingend. Dit bestand gaat mee bij elke opdracht in elke repository, dus alles wat hier staat kost je tokens en aandacht van het model.

Stap 2: leg projectregels vast in de repo-root

Regels die alleen over dit project gaan, zet je in een AGENTS.md in de root van de repository — meestal je Git-root. Codex vindt hem vanzelf.

## Verwachtingen in deze repository

- Draai `npm run lint` voordat je een pull request opent.
- Documenteer publieke utilities in `docs/` als je gedrag wijzigt.

Dit bestand commit je mee. Iedereen die met Codex aan deze repo werkt, krijgt dezelfde uitgangspunten, en nieuwe teamleden hoeven de ongeschreven regels niet te raden.

Stap 3: maak uitzonderingen per map

Werkt één onderdeel anders dan de rest — een betaaldienst met eigen testcommando’s, een map met gegenereerde code — dan zet je daar een AGENTS.override.md neer:

## Regels voor de payments-service

- Gebruik `make test-payments` in plaats van `npm test`.
- Roteer nooit API-keys zonder het securitykanaal te informeren.

Twee dingen om te snappen. Codex neemt per map hooguit één bestand mee, en een AGENTS.override.md verdringt de gewone AGENTS.md in diezelfde map volledig. En omdat Codex de bestanden van boven naar beneden achter elkaar plakt, staat het bestand dat het dichtst bij je werkmap ligt als laatste in de prompt — dat is precies waarom het de bredere regels overruled (Bron: OpenAI).

Zet uitzonderingen dus zo dicht mogelijk bij het werk waar ze over gaan.

Stap 4: controleer wat er daadwerkelijk geladen is

Vertrouw niet op de bestandsstructuur, vraag het gewoon:

codex --ask-for-approval never "Summarize the current instructions."

Codex hoort dan de punten uit je instructiebestanden terug te geven voordat hij aan werk begint. Wil je een geneste override controleren, start dan vanuit die map:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Verwacht drie bronnen in deze volgorde: het globale bestand, de repo-root, en daarna de override. Wijkt dat af, dan weet je meteen waar je moet kijken.

Stap 5: ken de twee limieten

De gecombineerde instructies stoppen bij 32 KiB. Zit je daarboven, dan kapt Codex af, en dat merk je niet als een foutmelding maar als een agent die het laatste deel van je regels lijkt te negeren. Verhoog dan project_doc_max_bytes in ~/.codex/config.toml, of verdeel de tekst over geneste mappen.

De tweede: gebruikt je team al een andere bestandsnaam, zet die dan in de fallback-lijst.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Namen die niet in die lijst staan, worden voor instructie-ontdekking genegeerd. Herstart Codex na een configuratiewijziging.

Als het niet werkt

Er is geen cache om te legen — Codex bouwt de instructieketen bij elke run opnieuw op, en in de TUI bij elke sessiestart. Ziet het er toch verouderd uit, herstart dan in de juiste map. Laadt er niets, controleer dan of je wel in de bedoelde repository zit en of je bestanden inhoud hebben; lege bestanden slaat Codex over. Krijg je regels te zien die je niet herkent, zoek dan naar een AGENTS.override.md hoger in de boom of in je Codex-home.

Deze aanpak werkt trouwens niet alleen voor Codex: het bestandsformaat is een open afspraak die meerdere coding-agents inmiddels lezen. Werk je met meerdere tools naast elkaar, dan is dat prettig — al bespaart één bestand je niet de moeite om zelf te blijven volgen wat de agent doet. Waarom dat laatste ertoe doet, staat in dit stuk over vaardigheidsverlies door AI op Het Laatste AI Nieuws.

Werk je ook met Claude Code, dan is plugins installeren de vergelijkbare stap daar. En wil je meerdere terminal-agents naast elkaar draaien, kijk dan naar Solo.