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

Op dit moment is het landschap verdeeld per tool:

• CLAUDE.md is wat Claude Code zoekt.
• GEMINI.md is de conventie van Antigravity CLI.
• AGENTS.md is de cross-tool standaard, gelezen door Codex en anderen, ontworpen om de neutrale te zijn.

De inhoud is bijna identiek in alle drie: projectcontext, commando's, conventies. Het enige echte verschil is de bestandsnaam die elke tool standaard leest. 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).

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 canoniek bestand, dunne verwijzingen. Houd alles in AGENTS.md en maak CLAUDE.md en GEMINI.md eenregelige bestanden die zeggen "zie AGENTS.md," of symlink ze. Eén bron van waarheid, elke tool gevoed.
• Eén bestand, gedeeld door conventie. Als je tools naar een aangepast pad kunnen worden gericht, richt ze allemaal op AGENTS.md en verwijder de rest.

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.