Een AGENTS.md-bestand schrijven in 2026 (kort, handgeschreven, onderbouwd met data)

Een AGENTS.md-bestand is een "README voor je codeeragent" in gewone Markdown die in de root van je repo staat en tools zoals Claude Code, Codex en Cursor vertelt hoe ze binnen je project moeten bouwen, testen en zich gedragen. De beste zijn kort, specifiek en handgeschreven: ze noemen je exacte commando's, benoemen je stack met versies en trekken harde grenzen rond wat de agent nooit mag aanraken. De slechtste zijn lang, vaag en automatisch gegenereerd — en er is nu gemeten bewijs dat ze agents trager en minder nauwkeurig maken.

Wij bouwen TechRiseUps met Claude Code, en het ene bestand dat het meest veranderde hoe betrouwbaar het correct werk oplevert, was het bestand met agent-instructies. Dit is de praktische gids die we graag zelf hadden gehad: wat je moet schrijven, wat je moet schrappen, en waarom minder meer is.

Wat is een AGENTS.md-bestand?

AGENTS.md is een open, tool-onafhankelijk formaat om codeeragents te sturen — "een specifieke, voorspelbare plek om de context en instructies aan te leveren die AI-codeeragents helpen aan je project te werken." Zie het als de tegenhanger van je README voor mensen: bouwstappen, testcommando's en conventies die de README zouden vervuilen, maar die een agent echt nodig heeft.

Het formaat werd geïntroduceerd door OpenAI voor Codex, en in december 2025 werd het geschonken aan de Agentic AI Foundation onder de Linux Foundation, zodat het niet langer de conventie van één leverancier is. Het wordt inmiddels erkend door meer dan 60.000 opensourceprojecten en ondersteund door meer dan 28 tools, waaronder Codex, Cursor, Aider, Devin, Google Jules en VS Code. Claude Code leest zijn eigen CLAUDE.md en houdt zich steeds vaker ook aan AGENTS.md; het inhoudelijke advies hieronder geldt voor beide. Eén bestand, veel agents — dat is precies de bedoeling.

Wat je in een AGENTS.md-bestand zet

GitHub analyseerde meer dan 2.500 echte agents.md-bestanden (gepubliceerd op 19 november 2025) en vond een duidelijke scheidslijn tussen bestanden die helpen en bestanden die genegeerd worden. De falende bestanden delen één eigenschap: ze zijn te vaag. Persona's als "behulpzame codeerassistent" deden niets; exacte commando's en harde grenzen deden het werk.

Dit is wat zijn plek verdient — en wat je weg moet laten:

Opnemen (verdient zijn tokens)	Schrappen (verspilt ze)
Exacte commando's met vlaggen: pnpm test, pytest -v	"Draai de tests" zonder commando
Stack met versies: "React 18, TS 5, Vite, Tailwind"	"Moderne webstack"
Een echt codefragment dat je stijl toont	Alinea's die je stijl beschrijven
Grenzen in drie niveaus: Altijd / Eerst vragen / Nooit	Een algemene "wees voorzichtig"-regel
Niet voor de hand liggende valkuilen (monorepo-eigenaardigheden, env-setup)	Een volledige mappenboom die de agent zelf kan lezen
"Commit nooit geheimen" en beschermde paden	Taaldocumentatie herhalen die het model al kent

De meest voorkomende, écht nuttige beperking in de 2.500 repo's was botweg: "Commit nooit geheimen." Die ene regel is de goedkoopste verzekering die je kunt schrijven, en hij sluit direct aan op de bredere lessen over toeleveringsketens uit de npm Shai-Hulud-crisis — agents met shell-toegang kunnen inloggegevens net zo snel lekken als een gecompromitteerd pakket.

Waarom een kortere AGENTS.md het wint van een langere

Dit is het deel dat de meeste gidsen overslaan, en het is het belangrijkste. Elke regel in je AGENTS.md wordt in elke agentsessie geïnjecteerd, dus elke regel concurreert om het beperkte aandachtsbudget van het model. Het opvullen ervan helpt de agent niet — het schaadt hem juist.

Een ETH Zurich-studie uit 2026 zette er cijfers op. Automatisch gegenereerde, opgeblazen contextbestanden verlaagden het slagingspercentage van taken in 5 van de 8 geteste situaties, lieten agents 2,45 tot 3,92 extra stappen per taak zetten en dreven de inferentiekosten 20–23% omhoog — en dat alles zonder meetbare kwaliteitswinst. Door mensen samengestelde bestanden presteerden daarentegen voor elke geteste agent beter dan door een LLM gegenereerde, met ongeveer 4 procentpunten op de AGENTbench-benchmark. Toen onderzoekers overbodige documentatie volledig verwijderden, verbeterde de prestatie van de automatisch gegenereerde bestanden zelfs, wat bevestigde dat ze grotendeels dingen dubbelden die het model al wist.

De praktische regel van professionals sluit aan bij de data: hou het kort. De algemene consensus is minder dan 300 regels, en teams als HumanLayer houden die van hen onder de 60. Schrijf het zelf, bewust, want "een slechte regel in AGENTS.md cascadeert door naar slechte plannen, slechte code en slechte resultaten in elke sessie."

Zo schrijf je je AGENTS.md, stap voor stap

Je kunt in tien minuten een werkend bestand hebben. Doe het in deze volgorde:

1. Maak AGENTS.md in de root van de repo. Begin leeg. Weersta de neiging om een "genereer mijn AGENTS.md"-commando uit te voeren — je weet nu dat de data zegt dat handgeschreven wint.
2. Schrijf eerst de commando's. De exacte regels die je zou typen om te installeren, draaien, testen en linten. Neem vlaggen op. Dit is de sectie met de hoogste waarde, dus die staat bovenaan.
3. Benoem de stack met versies. Eén regel: talen, framework, pakketmanager, belangrijke bibliotheken en hun grote versies. Onduidelijkheid hier veroorzaakt de meeste verspilde agentstappen.
4. Voeg één echt codefragment toe dat je conventies laat zien — een echte functie of component uit je repo, geen beschrijving ervan.
5. Stel grenzen in drie niveaus in. Altijd (bijv. "draai de linter voordat je afrondt"), Eerst vragen (bijv. "voordat je het DB-schema wijzigt"), Nooit (bijv. "commit nooit geheimen, raak /vendor nooit aan, doe nooit git push"). Hier codeer je het oordeel dat het model niet kan afleiden.
6. Noteer alleen wat niet voor de hand ligt. De pakketindeling van een monorepo, een vereiste env-variabele, een instabiele test om te negeren. Sla alles over wat de agent kan ontdekken door de boom te lezen.
7. Test het en snoei dan. Draai een echte taak, kijk waar de agent verkeerd gokt, voeg een regel toe om dat op te lossen, en verwijder elke regel die zijn plek nooit heeft verdiend.

Eén contra-intuïtieve opbrengst: tools die je in AGENTS.md noemt, worden ongeveer 160× vaker gebruikt dan tools die je niet noemt. Wil je dat de agent je eigen script of een specifieke MCP-server gebruikt, benoem het dan expliciet — anders bestaat het feitelijk niet. Ben je nog aan het kiezen op welke agent je wilt standaardiseren, dan behandelt onze vergelijking van Cursor, Copilot, Windsurf en Claude Code in 2026 hoe elk de projectcontext inlaadt.

AGENTS.md, CLAUDE.md en .cursorrules — heb je alle drie nodig?

Nee. AGENTS.md is de opkomende standaard voor alle tools, dus maak het je bron van waarheid. Claude Code zoekt nog steeds naar CLAUDE.md en Cursor gebruikte historisch gezien .cursorrules; de meest moeiteloze aanpak is om de echte inhoud in AGENTS.md te houden en, waar een tool zijn eigen bestandsnaam eist, ernaar te symlinken of te importeren in plaats van twee uiteenlopende kopieën te onderhouden. In een monorepo kun je bestanden ook nesten: agents lezen automatisch de dichtstbijzijnde AGENTS.md in de mappenboom, zodat een pakket de root kan overschrijven — OpenAI's eigen repo bevat er 88. Houd het rootbestand algemeen en laat elk pakket zijn eigen specifieke zaken bevatten. Met welke agent je het combineert, blijft van belang; zie onze overzicht van de beste AI-codeertools in 2026.

Veelgemaakte fouten om te vermijden

• Het hele bestand automatisch genereren. De snelste weg naar een tragere agent. Genereer hooguit een skelet en herschrijf het daarna met de hand.
• Je mappenboom erin plakken. Agents sommen zelf bestanden op; een statische boom veroudert alleen maar en verbrandt tokens.
• Het voor de hand liggende herhalen. Het model weet hoe Python werkt. Vertel het wat specifiek is voor jouw repo.
• Eén gigantisch bestand voor alles. Gebruik progressieve onthulling: houd taakspecifieke notities in aparte documenten (bijv. agent_docs/running-tests.md) en verwijs ernaar, zodat het rootbestand slank blijft.
• Het nooit meer bekijken. Het bestand loopt uit de pas naarmate je project verandert. Snoei het telkens wanneer de agent verkeerd gokt.

Veelgestelde vragen

Waar hoort het AGENTS.md-bestand te staan?

In de root van je repository. Voeg voor monorepo's extra AGENTS.md-bestanden toe binnen afzonderlijke pakketten; de agent leest het bestand dat het dichtst bij het bestand ligt waaraan hij werkt, en dat dichtstbijzijnde bestand krijgt voorrang.

Hoe lang hoort een AGENTS.md te zijn?

Kort. De gangbare consensus is minder dan 300 regels, en veel sterke voorbeelden blijven onder de 100. Omdat elke regel in elke sessie wordt geladen, heeft lengte een reële kostprijs in zowel nauwkeurigheid als tokens — schrijf alleen wat het gedrag van de agent verandert.

Moet ik een AI mijn AGENTS.md laten genereren?

Gebruik er zo nodig een om een ruw skelet op te stellen, maar lever het niet zo af. Het onderzoek van ETH Zurich vond dat automatisch gegenereerde bestanden het slagingspercentage van taken in de meeste situaties verlaagden en de kosten met 20–23% opdreven. Door mensen samengestelde bestanden versloegen de gegenereerde over de hele linie — het bestand is het waard om met de hand te schrijven.

Gebruikt Claude Code AGENTS.md?

Claude Code leest van nature CLAUDE.md en herkent steeds vaker AGENTS.md. De inhoudelijke principes zijn hoe dan ook identiek: exacte commando's, een stack met versies, harde grenzen en beknoptheid. Als je al een goede CLAUDE.md bijhoudt, ben je 90% op weg naar een goede AGENTS.md.

Wat is het ene ding dat elke AGENTS.md zou moeten bevatten?

Een "Nooit"-grens die "commit nooit geheimen" bevat. Het was de meest voorkomende nuttige beperking in meer dan 2.500 echte repo's, en het is de goedkoopste regel om een codebase te beschermen die een agent nu kan bewerken en draaien.

Bronnen

• agents.md — het open formaat en de spec: definitie, ondersteunde tools, monorepo-nesting en beheer door de Agentic AI Foundation / Linux Foundation.
• GitHub Blog — How to write a great agents.md: lessons from over 2,500 repositories: de op data gebaseerde secties die werken en de "te vaag"-faalmodus (19 nov. 2025).
• Philipp Schmid — Writing a Good AGENTS.md: de consensus "hou het onder 300 regels" en de bevinding dat tools 160× vaker worden genoemd.
• Augment Code — How to Build Your AGENTS.md: samenvatting van de ETH Zurich-studie die laat zien dat automatisch gegenereerde bestanden het slagingspercentage van taken verlagen en de kosten verhogen.