Wat er in AGENTS.md staat
AGENTS.md noemt zichzelf “a README for agents”. Een README is voor mensen: wat het project is en hoe je begint. AGENTS.md is voor de agent: hoe je bouwt en test, welke stijl de code heeft, wat je niet aanraakt, hoe een pull request eruitziet. Het is gewone Markdown zonder verplichte velden.
Het formaat is niet van OpenAI alleen. Het valt onder de Agentic AI Foundation van de Linux Foundation en wordt gelezen door onder meer Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Google Jules, Aider, Devin, Windsurf, Zed, Warp, VS Code en JetBrains Junie. Volgens agents.md gebruiken meer dan 60.000 open-sourceprojecten het.
Hoe Codex het precies leest
Codex bouwt bij het begin van elke sessie een instructieketen in drie stappen.
- Globaal. In je Codex-thuismap (~/.codex, of de map in CODEX_HOME) leest Codex AGENTS.override.md als die bestaat, anders AGENTS.md. Alleen het eerste bestand dat niet leeg is telt.
- Project. Vanaf de projectwortel, meestal de root van de Git-repo, loopt Codex omlaag tot de map waarin je werkt. In elke map kijkt hij eerst naar AGENTS.override.md, dan naar AGENTS.md, dan naar de namen in
project_doc_fallback_filenames. Per map neemt hij hoogstens één bestand. Is er geen projectwortel, dan kijkt Codex alleen in de huidige map. - Samenvoegen. De gevonden bestanden worden van boven naar beneden achter elkaar geplakt, met lege regels ertussen. Een bestand dichter bij je werkmap komt later en gaat daardoor voor bij tegenstrijdige instructies. Lege bestanden worden overgeslagen. Codex stopt zodra het totaal
project_doc_max_bytesbereikt, standaard 32 KiB.
| Instelling in ~/.codex/config.toml | Wat het doet | Standaard |
|---|---|---|
project_doc_fallback_filenames |
Extra bestandsnamen per map, bijvoorbeld ["TEAM_GUIDE.md", ".agents.md"] |
Geen |
project_doc_max_bytes |
Bovengrens voor alle instructies samen, bijvoorbeeld 65536 |
32 KiB |
Na een wijziging in de configuratie of in een AGENTS.md is een nieuwe sessie nodig.
Een voorbeeld. Je werkt in services/betalen/ van deze repo:
~/.codex/AGENTS.md persoonlijke voorkeuren
repo/AGENTS.md afspraken voor de hele repo
repo/services/AGENTS.md afspraken voor alle services
repo/services/betalen/AGENTS.override.md tijdelijke afwijking
Codex plakt dan in deze volgorde: het globale bestand, repo/AGENTS.md, repo/services/AGENTS.md en AGENTS.override.md uit de map betalen. Een AGENTS.md naast die override in dezelfde map wordt overgeslagen. Wil je zien wat er echt geladen is, vraag Codex dan aan het begin van een sessie om de instructies op te sommen die het heeft gekregen.
Het misverstand: alles wat in AGENTS.md staat, komt aan
Veel teams zetten steeds meer in één groot bestand en gaan ervan uit dat de agent het allemaal leest. Codex kapt de keten af bij 32 KiB, en wat in de globale en bovenliggende bestanden staat gaat voor op wat diep in een submap staat. Een lange globale AGENTS.md kan zo de instructies van een submap uit beeld duwen. Houd elk bestand kort en zet specifieke regels in de map waar ze gelden; in een monorepo wint het dichtstbijzijnde bestand. Een expliciete instructie in de chat gaat volgens agents.md altijd voor op het bestand.
AGENTS.md naast CLAUDE.md
Claude Code leest AGENTS.md vanaf versie 2.1.277 als projectinstructies wanneer er in de werkmap en de mappen erboven geen CLAUDE.md of CLAUDE.local.md staat; de instelling Project instructions kan dat veranderen. Heeft je repo al een CLAUDE.md, zet dan de regel @AGENTS.md bovenaan: Claude Code laadt het gedeelde bestand dan mee en leest het niet dubbel. Andersom kan Codex een bestaande CLAUDE.md lezen als je die naam opneemt in project_doc_fallback_filenames. Zo hoeft een team met Codex en Claude Code naast elkaar de afspraken maar op één plek bij te houden.
Wat dit voor een team betekent
Een AGENTS.md die je commit, gaat met de repo mee naar iedereen, net als de README en de andere documentatie. De memories van Codex staan juist op één machine, en Codex zegt zelf: houd verplichte teamafspraken in AGENTS.md of in vastgelegde documentatie, niet in memories. Zie Onthoudt Codex wat we eerder deden?. Maar AGENTS.md is ook handwerk: iemand moet het schrijven, inkorten en bijhouden. Er mogen besluiten en verwijzingen naar andere documenten in, maar het haalt mail of documenten niet zelf op, en alles moet binnen de grens van 32 KiB passen. Hoe je die bredere kennis vastlegt staat in Hoe leg je je bedrijfscontext vast?.
Waar Bombos past
AGENTS.md geeft elke agent dezelfde regels voor één repo; Bombos geeft elke AI-tool van het team één gedeeld geheugen daarboven. Het bewaart de teamkennis en de regels die het team leert, en leest wat er al ligt in mail, documenten en repo’s, zodat Codex, Claude Code of Cursor het kunnen opvragen zonder dat het in een bestand van 32 KiB moet passen. Eén ontwikkelaar kan het eerst zelf proberen voor zijn eigen agents.
Vragen die hierbij horen
Wat is het verschil tussen AGENTS.md en AGENTS.override.md?
In dezelfde map wint AGENTS.override.md: staat die er, dan leest Codex de gewone AGENTS.md in die map niet. Handig voor een tijdelijke of persoonlijke afwijking zonder het gedeelde bestand te wijzigen.
Leest Claude Code ook AGENTS.md?
Ja, vanaf Claude Code v2.1.277, als er in de werkmap en de mappen erboven geen CLAUDE.md of CLAUDE.local.md staat. Staan beide er, dan leest Claude Code alleen CLAUDE.md, tenzij die de regel @AGENTS.md bevat.
Kan Codex ook een bestand met een andere naam lezen, zoals CLAUDE.md?
Ja, via project_doc_fallback_filenames in ~/.codex/config.toml. Codex probeert die namen per map als er geen AGENTS.override.md of AGENTS.md staat.
Waarom ziet Codex mijn wijziging in AGENTS.md niet?
Codex bouwt de instructieketen bij het begin van een sessie. Start een nieuwe sessie na een wijziging, en controleer of het totaal onder project_doc_max_bytes blijft.
