AGENTS.md voor Codex: schrijven, sjabloon en het verschil met CLAUDE.md

Wat het is

Wat AGENTS.md is en welke tools het lezen

AGENTS.md is een gewoon Markdown-bestand: geen verplichte velden, geen vaste koppen. Waar je README uitlegt aan mensen hoe het project werkt, vertelt AGENTS.md een coding agent wat hij moet weten voordat hij iets aanpast. Codex laadt het automatisch, dus je hoeft de afspraken niet in elke prompt te herhalen. OpenAI noemt het in de documentatie de beste plek om vast te leggen hoe jij en je team Codex in een repository willen laten werken.

Een open standaard, niet alleen van OpenAI

AGENTS.md begon als conventie van Codex en valt nu onder de Agentic AI Foundation, een project van de Linux Foundation. Volgens agents.md gebruiken meer dan 60.000 open-sourceprojecten het bestand. De site noemt onder meer Codex, Cursor, GitHub Copilot (coding agent), Gemini CLI, Jules, Aider, opencode, Zed, Warp, VS Code, Junie, Windsurf en Devin. Claude Code staat niet in die lijst, maar leest AGENTS.md volgens de eigen documentatie sinds versie 2.1.277 wel. Waarom dat telt: werkt je team met meer dan één tool, dan schrijf je de afspraken één keer.

Wat AGENTS.md niet is

Het is context, geen slot op de deur. Codex leest de regels en probeert ze te volgen, maar een regel als "nooit naar main pushen" houdt niets tegen. Wat echt niet mag, regel je met de sandbox en approval-instellingen (zie privacy en sandbox), met branch protection in GitHub en met tests in je CI. OpenAI zegt het zelf over reviewregels: ze sturen Codex, maar vervangen geen tests, branch protection of verplichte goedkeuringen.

AGENTS.md naast skills en plugins

AGENTS.md laadt bij elke taak volledig mee. Een skill laadt Codex pas als die nodig is: vooraf alleen de naam en beschrijving, de inhoud pas als de skill gekozen wordt. Daarom hoort een vaste huisregel in AGENTS.md en een stappenplan voor één soort klus (een release, een nieuwsbrief, een export) in een skill. De officiële bouwvolgorde begint ook bij AGENTS.md, daarna skills of plugins, dan MCP en als laatste subagents.

Locaties

Waar Codex AGENTS.md zoekt, en welk bestand wint

Codex bouwt bij het starten een instructieketen op: één keer per run, en in de terminal meestal één keer per gestarte sessie. Er is geen cache. Dit zijn de plekken waar je een bestand kunt zetten.

Wat dit voor je mappenindeling betekent

Start je Codex in de root, dan leest het alleen je persoonlijke bestand en de root-AGENTS.md. Een AGENTS.md in site/ telt pas mee als je Codex in site/ of dieper start, of met codex --cd site. Zet regels die altijd moeten gelden dus in de root, en regels voor één onderdeel in de map van dat onderdeel. Waarom: zo krijgt Codex alleen de regels die bij het werk horen, en blijft de totale omvang klein.

Windows en WSL

De Windows-app gebruikt dezelfde Codex-map als de native CLI: %USERPROFILE%\.codex. Draai je de CLI in WSL, dan gebruikt die standaard je Linux-homemap en dus een andere AGENTS.md en config.toml. Wil je één set, zet dan in WSL bijvoorbeeld export CODEX_HOME=/mnt/c/Users/jouwnaam/.codex. Installeren op Windows staat op Codex installeren.

En in Codex cloud en bij GitHub-reviews?

Voor code review in GitHub zoekt Codex de AGENTS.md-bestanden in je repository en volgt het de reviewregels die gelden voor elk gewijzigd bestand: de root plus de specifiekere bestanden. In een pull request kun je @codex add this to AGENTS.md typen om een aanpassing aan een cloudtaak over te laten. Of je persoonlijke ~/.codex/AGENTS.md in een cloudtaak meetelt, staat niet in de documentatie. Ga ervan uit van niet en zet alles wat het team nodig heeft in de repository. Meer over cloudtaken op Codex cloud.

/init

AGENTS.md maken met /init

/init maakt een AGENTS.md-scaffold in de map waar je het draait. Het commando staat in de Codex CLI en in de IDE-extensie voor VS Code. OpenAI noemt het resultaat uitdrukkelijk een startpunt dat je aanpast aan hoe je team echt werkt. Zo doe je dat in zes stappen.

Komt je setup uit Claude Code of Cursor?

Dan hoef je niet bij nul te beginnen. Met /import in de Codex CLI kies je Claude Code of Cursor en neem je setup, projectbestanden en recente chats over. Instructiebestanden worden daarbij AGENTS.md, settings.json wordt config.toml, en skills blijven skills. Je bestaande setup in de andere tool blijft ongewijzigd. In de desktop-app kan dit ook vanuit Claude Cowork, en daar kun je automatische updates aanzetten. Lees de geïmporteerde AGENTS.md daarna net zo kritisch als een /init-resultaat. Alle commando's staan op Codex-commands.

Inhoud

Wat er in AGENTS.md hoort, en wat er niet in hoort

De best practices van OpenAI noemen de indeling van de repo en belangrijke mappen, de build-, test- en lintcommando's, en wat "klaar" betekent en hoe je werk controleert. Hun advies over lengte is kort: een korte, juiste AGENTS.md is nuttiger dan een lang bestand vol vage regels. Gebruik deze tabel als filter voor elke regel.

Schrijf regels die je kunt controleren

"Schrijf nette code" kan Codex niet toetsen. "Draai npm test voordat je klaar meldt en noem welke test je wijziging bewijst" wel. Een goede regel zegt wat Codex moet doen, wanneer, en hoe jij achteraf ziet dat het gebeurd is. Twijfel je of een regel erin moet, stel dan de vraag: maakt Codex zonder deze regel aantoonbaar een fout? Zo nee, laat hem weg.

Verwijzen in plaats van importeren

Claude Code kent @-imports in CLAUDE.md; de Codex-documentatie beschrijft voor AGENTS.md geen importsyntax. Een regel als @docs/review.md is voor Codex dus gewone tekst. Wordt je bestand te groot, volg dan het advies uit de best practices: houd het hoofdbestand kort en verwijs naar losse Markdown-bestanden per onderwerp, bijvoorbeeld "Lees docs/release.md voordat je een release voorbereidt."

Sjabloon

AGENTS.md voorbeeld: sjabloon voor een Nederlandse MKB-repo

Dit voorbeeld is voor een veelvoorkomende opzet: een website plus een paar interne scripts, bijvoorbeeld voor exports uit Exact Online of AFAS. Kopieer het, vervang alles tussen blokhaken en schrap wat niet voor jouw repo geldt. Ongewijzigd is het ongeveer 1,3 KB, ruim binnen de limiet van 32 KiB.

AGENTS.md om te kopiëren

# AGENTS.md voor [bedrijfsnaam]

## Project
- Website (Astro) in /site, interne scripts (Python) in /scripts
- Lezers zijn Nederlandse MKB-klanten. Alle teksten in het Nederlands, je-vorm

## Commando's
- Installeren: npm ci in /site, pip install -r scripts/requirements.txt
- Bouwen: npm run build in /site
- Testen: npm test in /site, pytest in /scripts

## Klaar betekent
- Build en tests slagen, en je noemt welke test je wijziging bewijst
- Je sluit af met: wat je hebt veranderd en wat je niet zeker weet

## Werkafspraken
- Kleine wijzigingen per taak. Geen nieuwe pakketten zonder akkoord
- Bedrijfsgegevens (KVK, adres, telefoon) alleen uit site/src/data/bedrijf.json
- Geen verzonnen cijfers, reviews of klantnamen. Ontbreekt iets, zet [AANVULLEN]
- Lees docs/huisstijl.md voordat je teksten voor de website schrijft

## Niet aanraken
- .env en alles in /exports (klantdata): niet openen, niet committen
- Scripts nooit tegen de echte administratie draaien, alleen tegen de testomgeving

## Code Review Rules
### Privacy
- Markeer code die persoonsgegevens logt of naar een dienst buiten de EU stuurt
- Markeer nieuwe tracking- of cookiescripts die niet via de cookiebanner lopen
### Inhoud
- Markeer elk nieuw cijfer, jaartal of klantcitaat dat niet in bedrijf.json staat

Welke regels het meeste doen

De sectie "Klaar betekent" is de belangrijkste. Zonder die regel meldt Codex klaar zodra de code compileert; met de regel draait het de tests en zegt het eerlijk wat onzeker is. "Niet aanraken" beschermt je klantdata, maar alleen als advies: zet /exports daarnaast in .gitignore en houd de sandbox op workspace-write, zodat Codex buiten je project niets kan schrijven. De Code Review Rules werken pas als je Codex-review in GitHub aanzet. OpenAI meldt dat Codex daar alleen P0- en P1-problemen markeert, dus jouw regels bepalen wat voor jouw repo als ernstig telt.

Een persoonlijk bestand voor jezelf

In ~/.codex/AGENTS.md zet je wat voor al je projecten geldt en niet in de repo van je team hoort, bijvoorbeeld:

## Mijn werkafspraken
- Antwoord in het Nederlands, code en commits in het Engels
- Vraag eerst als een taak meer dan vijf bestanden raakt
- Leg in twee zinnen uit waarom je een aanpak kiest

Houd dit bestand nog korter dan het projectbestand: het telt mee in elke repo waarin je werkt. Een uitgewerkt voorbeeld voor een website met Codex staat op website beheren met Codex.

Limiet

De groottelimiet: 32 KiB voor alle AGENTS.md-bestanden samen

Codex stopt met het toevoegen van instructiebestanden zodra de gecombineerde omvang project_doc_max_bytes bereikt. Standaard is dat 32 KiB, oftewel 32.768 bytes. Dat geldt voor de hele keten samen: je persoonlijke bestand, de root en alle submappen op het pad. Wat erna komt, telt niet mee, en je krijgt daar in de sessie geen melding van.

Hoeveel tekst is 32 KiB?

Gewone letters, cijfers en leestekens kosten één byte per teken, letters met accenten zoals é en ë twee. Een Nederlandse AGENTS.md van 32 KiB is dus iets minder dan 32.000 tekens. Meet het in de terminal met wc -c AGENTS.md (macOS, Linux, Git Bash) of in PowerShell met (Get-Item AGENTS.md).Length. Tel de bestanden op het pad bij elkaar op.

De limiet verhogen kan, maar is zelden de oplossing

In ~/.codex/config.toml zet je bijvoorbeeld:

project_doc_max_bytes = 65536

en daarna herstart je Codex. OpenAI noemt verhogen en opsplitsen over submappen als oplossingen voor afgekapte instructies. Wij raden opsplitsen aan. Waarom: alles in de keten gaat bij elke taak mee, dus een groter bestand betekent meer verbruik per beurt en meer regels die met elkaar kunnen botsen. De pricingpagina noemt een kleinere, per map geneste AGENTS.md zelfs als manier om je verbruik te drukken, zie Codex-limieten.

Vs CLAUDE.md

AGENTS.md vs CLAUDE.md: de verschillen op een rij

Beide bestanden doen hetzelfde: vaste projectcontext die de agent bij de start inleest. De spelregels verschillen. CLAUDE.md is het eigen bestand van Claude Code; hoe je dat schrijft staat in de tutorial CLAUDE.md schrijven en in het woordenboek onder CLAUDE.md.

Kies AGENTS.md als je bron als...

er in je team meer dan één coding agent wordt gebruikt, of als dat binnen een jaar zou kunnen. AGENTS.md lezen Codex, Cursor, Copilot en Claude Code allemaal; CLAUDE.md leest alleen Claude Code. Kies CLAUDE.md als enige bestand alleen als je zeker weet dat je team bij Claude Code blijft en je functies als @-imports of .claude/rules/ met padfilters wilt gebruiken. Welke tool bij je team past, staat op Claude Code vs Codex.

Eén bron

Eén AGENTS.md voor Codex en Claude Code: vier opties

Het risico van twee bestanden is dat ze uit elkaar groeien: iemand past het testcommando aan in CLAUDE.md en vergeet AGENTS.md. Je krijgt geen foutmelding, de twee agents doen gewoon iets anders. Kies daarom één bron. Deze beslisregel helpt.

De CLAUDE.md die naast je AGENTS.md staat

Zo ziet de korte CLAUDE.md uit de tweede rij eruit:

@AGENTS.md

## Alleen voor Claude Code
- Gebruik de skill release-notes voor changelogs

Claude Code leest dan eerst AGENTS.md en daarna de regels eronder. Codex negeert CLAUDE.md, dus daar verandert niets. Let op: een CLAUDE.local.md telt voor Claude Code ook als CLAUDE.md. Maak je er een aan in een project dat op alleen AGENTS.md draait, dan leest Claude je AGENTS.md niet meer, tenzij je in /config bij Project instructions de waarde claude-md-and-agents-md kiest.

Codex laten lezen uit een bestaande CLAUDE.md

Zet in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

en herstart Codex. Codex leest CLAUDE.md dan in elke map waar geen AGENTS.md of AGENTS.override.md staat. Twee beperkingen: elke collega moet dit in de eigen config zetten, en Claude-specifieke regels zoals @-imports leest Codex als gewone tekst. Gebruik het als overgangsoplossing.

Waarom wij de symlink afraden in Nederlandse teams

In veel MKB-teams werkt minstens één persoon op Windows met Microsoft 365. Een symlink aanmaken vraagt op Windows extra rechten of de ontwikkelaarsmodus, en zonder de juiste Git-instelling wordt hij uitgecheckt als een tekstbestand met één regel. De import @AGENTS.md werkt op elk systeem en Claude Code leest de inhoud daarbij nooit dubbel.

Controleren

Controleren wat Codex inleest, en waarom het je AGENTS.md negeert

Begin bij twijfel altijd met de vraag wat Codex heeft geladen. Ligt het daaraan, dan zit het probleem in de plek of de naam van het bestand. Heeft Codex het wel geladen, dan zit het in hoe de regel geschreven is.

Valkuil

De grootste valkuil: van AGENTS.md een handboek maken

De fout zit zelden in een ontbrekend bestand. Teams draaien /init, zijn blij met het resultaat en plakken er daarna de README, de stijlgids en de onboarding-notities bij. Het bestand groeit, en twee dingen gaan mis zonder dat iemand het merkt.

Wat er technisch gebeurt

Eerst verwateren de regels: tussen honderden regels uitleg valt "draai de tests" niet meer op, en tegenstrijdige zinnen uit verschillende documenten laten Codex kiezen. Daarna raakt de keten de 32 KiB. Codex stopt dan met toevoegen, en wat onderaan staat telt niet mee. Juist onderaan staan vaak de Code Review Rules en de verboden mappen, omdat die er het laatst bij kwamen.

Hoe je het voorkomt

Houd je aan drie gewoontes. Eén: alleen regels die een fout voorkomen die je echt hebt gezien. Twee: de belangrijkste regels bovenaan, met "Klaar betekent" en "Niet aanraken" vóór de rest. Drie: lange uitleg naar een apart bestand met een verwijzing, of naar een skill als het om een vaste werkwijze gaat. Meet de omvang één keer per maand met wc -c, net als je andere onderhoud.

Ons oordeel

Ons oordeel: wanneer AGENTS.md loont, en wat Nederlandse teams anders moeten doen

AGENTS.md is het kleinste stuk werk met het grootste effect op hoe Codex in je repo werkt. Een uur om het bestand goed te zetten verdient zich terug zodra je Codex vaker dan een paar keer op dezelfde code loslaat. Voor een los script van één middag is het overbodig.

Wanneer wel, wanneer niet

Wel: elke repo waar je Codex structureel gebruikt, en zeker als meer mensen of meer tools in dezelfde code werken. Niet: een eenmalig experiment, of een repo die je niet zelf beheert. Kloon je code van een ander, lees dan eerst de AGENTS.md die erin staat. Codex laadt hem automatisch, dus instructies die je niet kent sturen je agent mee. Waarom dat een risico is, staat bij prompt-injectie.

AVG, taal en Windows

AGENTS.md staat in versiebeheer en gaat bij elke taak naar het model. Zet er dus geen namen van klanten, BSN's, wachtwoorden of API-keys in, ook niet als voorbeeld. Beschrijf liever waar gevoelige data staat en dat Codex daar niet aan mag komen. Leg ook je taal vast: in trainingen zien we dat Codex zonder regel wisselt tussen je en u en Engelse termen overneemt uit de code. Werkt je team op Windows, let dan op de aparte Codex-map in WSL en gebruik geen symlinks voor je instructiebestanden.

De fout die we in trainingen het vaakst zien

Teams corrigeren Codex in de chat ("nee, we gebruiken pnpm") en zijn de volgende dag verbaasd dat dezelfde fout terugkomt. Een correctie in de chat geldt alleen voor die sessie. OpenAI adviseert: maakt Codex dezelfde fout twee keer, vraag dan om een korte terugblik en zet de les in AGENTS.md. Je kunt Codex ook zelf vragen: "Voeg aan AGENTS.md een regel toe die deze fout voorkomt. Houd het bij één zin."

Een MKB-voorbeeld

Stel: een administratiekantoor met één interne developer die de website en een paar Python-scripts voor exports uit Exact Online onderhoudt, en een collega die af en toe teksten aanpast met Codex. De developer draait /init, schrapt de mappenboom en houdt vijf regels over: de commando's, "klaar betekent tests geslaagd", de map met exports als verboden terrein, de testadministratie als enige doel voor scripts, en je-vorm in alle teksten. In scripts/ komt een tweede AGENTS.md met de regel dat geen script klantgegevens logt. Na twee weken komen er twee regels bij, beide na een fout die echt twee keer gebeurde. Het bestand blijft onder 2 KB. Wil je zo'n eerste versie samen met je eigen repo maken, dan kan dat in een AI-werksessie.