AGENTS.md: Eén contextbestand voor elke coderingagent (Codex, Antigravity, Claude)

Je hebt een middag besteed aan het schrijven van een nette CLAUDE.md. Je agent stopte eindelijk met het raden van je stack en begon het juiste testcommando uit te voeren. Dan opent een teamgenoot dezelfde repo met Codex, probeer je Antigravity CLI op een zijtak, en geen van die moeizaam verworven context wordt overgedragen. Elk hulpmiddel wil zijn eigen bestand, op zijn eigen plek.

AGENTS.md is het antwoord op die chaos: één eenvoudig Markdown-bestand, in de root van je repo, dat elke code-agent leest voordat het je code aanraakt.

Wat AGENTS.md eigenlijk is

Geen magie. Het is een Markdown-bestand genaamd AGENTS.md, meestal in de root van de repository, dat een agent laadt als vaste instructies voordat het begint te werken. Zie het als de README die je schrijft voor je AI-teamgenoten in plaats van je menselijke: wat het project is, hoe het te bouwen en te testen, de conventies om te respecteren, en de valkuilen om te vermijden.

Het is een open conventie, al gelezen door Codex en een groeiende lijst van agenttools, met het expliciete doel om draagbaar te zijn tussen hen. Eén bestand, veel agents, in plaats van één op maat gemaakt bestand per tool.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Toen deze gids voor het eerst werd geschreven, zocht elke tool naar zijn eigen bestand. De meeste zijn sindsdien op AGENTS.md uitgekomen:

• Codex leest AGENTS.md, net als GitHub Copilot CLI, Cursor, Amp en de meeste nieuwere agent-CLI's.
• Claude Code leest CLAUDE.md, en sinds versie 2.1.277 leest het ook uit zichzelf AGENTS.md wanneer je werkmap en de mappen daarboven geen CLAUDE.md of CLAUDE.local.md hebben. Bestaat er een CLAUDE.md, dan leest Claude alleen dat bestand, tenzij je de instelling Project instructions in /config wijzigt.
• Antigravity CLI leest AGENTS.md of GEMINI.md, in de root van de repository of in elke submap, plus een map .agents/rules/ en globale regels onder ~/.gemini/.

De inhoud is bijna identiek in alle drie: projectcontext, commando's, conventies. Wat nog verschilt, is welk bestand een tool kiest als er meerdere aanwezig zijn. Dat is precies waarom het dupliceren van dezelfde regels in drie bestanden met de hand een verliezende strijd is (meer over het synchroniseren ervan hieronder). We hebben dit gedrag op 10 oktober 2026 gecontroleerd aan de hand van de geheugendocumentatie van Claude Code en de documentatie over regels van Antigravity.

Als je voornamelijk in Claude Code werkt, gaat onze CLAUDE.md-gids diep in op de Claude-specifieke structuur. AGENTS.md is de provider-neutrale tegenhanger van dat bestand.

Wat erin te zetten

Houd het kort en krachtig. Een agent leest dit bij elke taak, dus elke regel concurreert om aandacht. De essentie:

• De stack, in één adem. "Next.js 16, TypeScript, Prisma, MariaDB." Geen geschiedenis, geen marketing.
• Commando's die ertoe doen. Hoe te installeren, uitvoeren, bouwen, testen en linten. Exacte commando's: npm test, niet "voer de tests uit."
• Conventies. Naamgeving, bestandsindeling, foutafhandeling, de patronen die je daadwerkelijk afdwingt in de review.
• Een directorykaart. Twee regels over waar dingen zich bevinden, zodat de agent stopt met blindelings greppen.
• Lees-voor-aanraakregels. "Lees docs/payments.md voordat je iets onder billing/ bewerkt." Deze enkele gewoonte voorkomt veel schade.
• Strikte verboden. "Maak nooit een branch zonder gevraagd te worden." "Geen absolute machinepaden in gecommitteerde bestanden."

De fouten waardoor agents het negeren

Een contextbestand faalt stilletjes. De agent geeft geen foutmelding, het dwaalt gewoon af. De gebruikelijke oorzaken:

1. Te lang. Een bestand van 600 regels verbergt de vijf regels die ertoe doen. Knip alles weg wat de agent zelf uit de code kan afleiden.
2. Tegenstrijdigheden. "Schrijf altijd tests" in één sectie, "sla tests over voor prototypes" in een andere. De agent kiest er willekeurig een.
3. Machine-specifieke paden. /Users/you/project/... in een gecommitteerd bestand werkt niet voor elke teamgenoot, en voor elke agent op elke andere machine. Houd paden relatief.
4. Verouderde commando's. Het testcommando is zes maanden geleden veranderd, het bestand niet. Nu voert de agent het verkeerde uit met volle overtuiging.
5. Geen prioriteiten. Alles is "belangrijk," dus niets is dat. Zet de niet-onderhandelbare zaken eerst en label ze.
6. Documentatiedumping. Dit zijn instructies, geen wiki. Verwijs naar je documentatie, plak ze niet erin.

Eén context behouden over providers

Hier is het praktische deel dat de meeste gidsen overslaan. Als jij, of je team, meer dan één agent CLI uitvoert, wil je niet drie afdrijvende kopieën van dezelfde regels.

Twee schone benaderingen:

• Eén AGENTS.md, verder niets. Als niemand regels nodig heeft die alleen voor Claude gelden, houd dan één AGENTS.md: Codex, Antigravity CLI en Claude Code 2.1.277 of nieuwer lezen het allemaal. Het addertje is stil: een CLAUDE.md, of een persoonlijke CLAUDE.local.md, die later wordt toegevoegd, zorgt ervoor dat Claude Code AGENTS.md niet meer leest.
• Eén canoniek bestand, één import. Houd alles in AGENTS.md, begin CLAUDE.md met de regel @AGENTS.md en schrijf daaronder de regels die alleen voor Claude gelden. Claude leest eerst het geïmporteerde bestand. Onze eigen repository werkt zo: de CLAUDE.md bestaat uit alleen die ene regel. Een symlink (ln -s AGENTS.md CLAUDE.md) werkt ook, maar niet goed op Windows, waar je voor het aanmaken ervan beheerdersrechten of de ontwikkelaarsmodus nodig hebt, en waar een clone zonder core.symlinks een tekstbestand van één regel krijgt in plaats van je instructies.

Hoe dan ook, de regel is hetzelfde: schrijf de context één keer, niet één keer per provider. Dat is ook de enige manier waarop het correct blijft, omdat een enkel bestand het enige bestand is dat mensen daadwerkelijk onderhouden.

Wanneer je meerdere agents tegelijk uitvoert

Een repo-niveau AGENTS.md beantwoordt "wat is dit project." Het beantwoordt niet "wie is deze agent." Wanneer je een Backend-agent, een Frontend-agent en een QA-agent parallel op dezelfde code uitvoert, heeft elk de gedeelde projectcontext plus zijn eigen rol nodig.

Dat is de laag die AgentsRoom bovenop je AGENTS.md toevoegt. Elke agent krijgt een toegewijde rol met zijn eigen systeemprompt (DevOps, Frontend, Security en meer), zodat het gedeelde bestand slank blijft terwijl elke agent nog steeds zijn taak kent. Het is provider-agnostisch van ontwerp, zodat dezelfde setup Claude, Codex of Antigravity naast elkaar draait, en je herhaalbare instructies leven in een Prompt Library in plaats van in elke sessie opnieuw te worden getypt.

Wanneer je dat punt bereikt, is de methode voor meerdere agents parallel uitvoeren zonder de draad kwijt te raken de natuurlijke volgende lezing.

De conclusie

Schrijf één AGENTS.md. Houd het kort, houd het actueel, houd het draagbaar. Richt elke tool erop in plaats van een bestand per agent te onderhouden. Je context stopt met gebonden zijn aan welke CLI je toevallig begon, en je agents, welke je ook uitvoert, beginnen vanaf dezelfde pagina.

Wil je elke agent op één scherm, elk met zijn eigen rol en je gedeelde context? Download AgentsRoom, verbind je provider, en zet je vloot aan het werk.

Veelgestelde vragen

Wat is AGENTS.md?

Een Markdown-bestand, meestal in de root van een repository, dat code-agents laden als vaste instructies voordat ze aan het werk gaan: wat het project is, hoe je het bouwt en test, de conventies om te respecteren en de valkuilen om te vermijden. Het is een open conventie die tools met elkaar delen, niet het bestand van één tool, en wordt gelezen door Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp en, sinds versie 2.1.277, Claude Code.

Leest Claude Code AGENTS.md?

Ja, sinds Claude Code 2.1.277, maar alleen als er geen CLAUDE.md, .claude/CLAUDE.md of CLAUDE.local.md in je werkmap of daarboven staat. Dan laadt het elke AGENTS.md vanaf de werkmap naar boven, en de AGENTS.md van een submap zodra het daar een bestand opent. Bestaat er een CLAUDE.md, dan leest Claude alleen dat bestand, tenzij je Project instructions in /config op claude-md-and-agents-md zet. Zet bij oudere versies de regel @AGENTS.md bovenaan een CLAUDE.md.

Gebruikt Antigravity AGENTS.md of GEMINI.md?

Allebei. Antigravity leest een AGENTS.md, een GEMINI.md of een map .agents/rules/ in de root van de repository of in elke submap, plus globale regels uit ~/.gemini/. De regels tellen bij elkaar op in plaats van elkaar te vervangen, en als twee ervan elkaar tegenspreken, wint de regel van de meest specifieke map.

Moet ik AGENTS.md of CLAUDE.md houden?

Houd AGENTS.md als het enige bestand dat je onderhoudt. Heb je ook regels nodig die alleen voor Claude gelden, voeg dan een CLAUDE.md toe waarvan de eerste regel @AGENTS.md is en schrijf die regels eronder: Claude leest eerst het geïmporteerde bestand. Heb je ze niet nodig, dan volstaat AGENTS.md alleen voor Claude Code 2.1.277 of nieuwer. Vermijd twee volledige kopieën van dezelfde regels: de kopie die niemand bewerkt, raakt verouderd.

Waar moet AGENTS.md staan?

In de root van de repository, voor de regels die overal gelden. Claude Code en Antigravity lezen ook AGENTS.md-bestanden in submappen, dus een package of een service met eigen commando's kan een eigen bestand hebben, dat gelezen wordt wanneer de agent in die map werkt.