AGENTS.md

Wat is AGENTS.md?

AGENTS.md is een gewoon markdown-bestand dat in een repository wordt geplaatst om AI-coding-agents te vertellen hoe het project werkt: build- en testcommando's, codeconventies, architectuurnotities en regels om te volgen. Het is een leveranciersneutrale conventie, beschreven als een README voor agents, en wordt sinds 2026 automatisch gelezen door de meeste coding-agents.

De belangrijkste punten

• Eén bestand bedient veel tools. Het punt van AGENTS.md is dat Codex, Cursor, Gemini CLI, Jules en tientallen andere agents allemaal dezelfde instructies lezen in plaats van elk zijn eigen configuratiebestand te eisen.
• Het bevat wat een README weglaat. Mensen halen context uit onboarding en teamchat; agents hebben exacte commando's, conventies en verboden nodig, zwart op wit.
• Plaatsing is hiërarchisch. Een AGENTS.md in de root dekt de repo, en bestanden in submappen overschrijven die voor hun eigen subboom, wat past bij monorepo's.
• Het is gewoon markdown zonder verplicht schema. De conventie standaardiseert de bestandsnaam en locatie, en elk team beslist over de inhoud.
• Kwaliteit komt direct terug in agentoutput. Vage of verouderde instructies leveren agents op die gokken, en agents die gokken leveren overdoen op.

Hoe het werkt

Wanneer een coding-agent een sessie start in een repository, zoekt hij naar AGENTS.md in de projectroot en laadt de inhoud in zijn context voordat hij aan het werk gaat, op dezelfde manier waarop een nieuwe bijdrager eerst de README zou lezen. Het bestand vormt vervolgens elke beslissing die de agent neemt: welke package manager aan te roepen, hoe de testsuite te draaien, welke naamgevingsconventies te volgen, welke mappen met rust te laten. In monorepo's passen agents de dichtstbijzijnde AGENTS.md toe, omhoog in de mappenboom vanaf de bestanden die worden bewerkt, zodat een Python-service en een TypeScript-frontend elk hun eigen regels kunnen dragen terwijl ze repo-brede standaarden delen. OpenAI gaat hierin verder dan de meesten: zijn eigen monorepo onderhoudt 88 AGENTS.md-bestanden, en de officiële agents.md-site vermeldt ongeveer 25 ondersteunende agents en tools, waaronder Codex, Gemini CLI, Cursor en GitHub Copilots coding agent [1].

Het formaat ontstond in 2025 uit een door OpenAI geleide poging om de stapel per-tool-instructiebestanden te consolideren die zich had opgehoopt, en de adoptie verspreidde zich snel omdat de kosten één markdown-bestand zijn en de winst geldt voor elke agent die de repo aanraakt. Er is bewust geen schema. Effectieve bestanden convergeren toch vaak naar dezelfde secties: setup- en buildcommando's, testcommando's met de verwachting dat agents ze draaien, codestijlregels, commit- en PR-conventies, en beveiligingsgrenzen zoals bestanden die nooit gewijzigd mogen worden. Een empirische studie uit 2025 van 2.303 agent-contextbestanden over 1.925 repositories bevestigde het patroon, met testprocedures in 75,9% van de bestanden, implementatiedetails in 70,8%, en architectuur in 68,1%, terwijl beveiligingsrichtlijnen slechts in 14,8% voorkwamen [2]. Sommige tools die de conventie voorafgaan, houden hun eigen bestandsnaam aan, met name Claude Code's CLAUDE.md, en teams onderhouden vaak één canoniek bestand met het andere als verwijzing of symlink.

Het bestand doet ertoe omdat het context engineering is in zijn goedkoopste vorm. Instructies in AGENTS.md bereiken de agent bij elke sessie zonder inspanning per taak, wat het de natuurlijke plek maakt voor alles wat je jezelf in prompts ziet herhalen.

Voorbeeld

Een team merkt dat hun coding-agent steeds npm gebruikt in een pnpm-workspace, het lockfile breekt, en tests in de verkeerde map schrijft. Ze voegen een AGENTS.md toe aan de root: gebruik alleen pnpm, draai pnpm test --filter <package> voordat je een taak afrondt, tests staan naast de bron als .spec.ts-bestanden, wijzig nooit gegenereerde bestanden onder src/gen/, en alle API-wijzigingen vereisen eerst het bijwerken van de OpenAPI-spec. De volgende sessie zet dezelfde agent een feature meteen correct op. De instructies maakten het model niet slimmer; ze verwijderden elke plek waar het voorheen moest gokken.

Veelvoorkomende misvattingen

De veelvoorkomende fout is AGENTS.md één keer schrijven en het laten verrotten. Agents volgen het bestand letterlijk, dus een verouderd buildcommando of een regel die naar een verwijderde map verwijst, misleidt ze actief, wat erger is dan niets zeggen. Behandel het bestand als code: werk het bij in dezelfde pull request die de workflow wijzigt die het beschrijft, en snoei regels die niet meer gelden. Een kort, actueel bestand verslaat altijd een lang, verouderd bestand.

FAQ

Is AGENTS.md een officiële standaard? Het is een open conventie met een publieke spec-achtige site en steun van meerdere leveranciers, geen formele specificatie van een standaardisatie-instituut. In de praktijk behandelt het ecosysteem het als de standaard: de officiële agents.md-site telt meer dan 60.000 open-sourceprojecten op GitHub die het formaat gebruiken [3].

Hoe verschilt AGENTS.md van een README? Publiek en precisie. Een README verkoopt en oriënteert: wat het project is, waarom het bestaat, hoe te beginnen. AGENTS.md instrueert een operator zonder institutionele kennis en met totale gehoorzaamheid, dus geeft het de voorkeur aan exacte commando's en harde regels boven verhaal.

Wat moet ik er als eerste in zetten? Begin met wat je een agent al twee keer hebt verteld: het juiste testcommando, de package manager, de ene map die hij niet mag aanraken. Voeg conventies toe naarmate overtredingen verschijnen. Tien accurate regels leveren het meeste van de waarde.

Bronnen

1. agents.md. "Aantal AGENTS.md-bestanden in OpenAI's monorepo en lijst van ondersteunende agents en tools." https://agents.md/. Geraadpleegd augustus 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, sectiefrequentie over 2.303 contextbestanden." https://arxiv.org/abs/2511.12884. Geraadpleegd augustus 2026.
3. agents.md. "Aantal open-sourceprojecten dat het AGENTS.md-formaat gebruikt." https://agents.md/. Geraadpleegd augustus 2026.