Wat is de impact van agents.md files op de kwaliteit van AI output
AI coding agents gebruiken een bestand in de root van je repository dat de agent vertelt hoe hij moet werken. Welke tools hij moet gebruiken, welke conventies hij moet volgen, wat hij absoluut niet mag doen. Voor Claude Code heet het CLAUDE.md, voor andere agents gewoon AGENTS.md. De gedachte erachter is intuïtief. Geef de agent context, en hij presteert beter.
Maar klopt dat ook? Onderzoekers van ETH Zurich en LogicStar.ai besloten die aanname grondig te testen. De paper Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? is een van de eerste gecontroleerde studies die de werkelijke impact van deze contextbestanden meet. De conclusies zijn genuanceerd, soms verrassend.
Wat zijn agents.md files precies?
Een AGENTS.md bestand is in essentie een systeem-prompt op repositoryniveau. Wanneer een coding agent een repository opent en zo’n bestand aantreft, leest hij het automatisch in en past zijn gedrag aan op basis van de inhoud. Dat kan gaan over codeerstijl, verboden bibliotheken, verplichte tools, testprocedures of projectspecifieke conventies.
Ervaren gebruikers van Claude Code, Cursor of Aider weten dat een goed geconfigureerd contextbestand het verschil kan maken tussen een agent die nuttige code produceert en een die eindeloos de verkeerde richting opgaat. Praktijkervaring suggereert dat dit soort bestanden cruciaal zijn. Maar anekdotisch bewijs is geen bewijs. Vandaar de studie.
De onderzoekers evalueerden vier coding agents op 438 taken, verdeeld over twee bekende benchmarks: SWE-bench Lite en AGENTbench. De agents die getest werden, zijn Claude Code, Codex, en Qwen Code. Voor elke taak werd gemeten of de aanwezigheid van een AGENTS.md bestand de slaagkans verhoogde, verlaagde of geen effect had.
Wat werd er precies getest?
De opzet van het onderzoek was methodisch. De onderzoekers maakten onderscheid tussen verschillende soorten contextbestanden en verschillende soorten inhoud. Niet alle AGENTS.md bestanden zijn gelijk. Sommige bevatten projectspecifieke informatie die de agent nergens anders kan vinden, andere herhalen simpelweg wat al zichtbaar is in de codebase zelf.
Dat onderscheid bleek cruciaal. De centrale vraag was niet alleen helpt een agents.md bestand, maar ook welk type informatie helpt, en welk type schaadt?
De tests werden uitgevoerd met bestanden van verschillende lengtes en inhoudstypes. Sommige bestanden waren beknopt en gefocust op niet-voor-de-hand-liggende projectconventies. Andere waren uitgebreid en bevatten ook informatie die de agent zelf had kunnen ontdekken door de repository te verkennen. Die variatie was bewust. Het liet de onderzoekers meten wat het effect is van redundante versus unieke context.
Meer is niet altijd beter
De resultaten van de studie zijn genuanceerd, maar er tekent zich een duidelijk patroon af.
Goede agents.md bestanden helpen, maar het effect is beperkt
Wanneer een AGENTS.md bestand uitsluitend informatie bevat die de agent niet zelf kan ontdekken, is er een positief effect op de outputkwaliteit.
Het effect is echter kleiner dan veel gebruikers verwachten. De verbetering in slaagkans op taken is meetbaar, maar niet spectaculair. Een goed geconfigureerd contextbestand is geen wondermiddel dat een zwakke agent plots sterk maakt.
Slechte agents.md bestanden schaden de prestaties
Dit is de meest opvallende bevinding van de studie. Contextbestanden die informatie bevatten die de agent ook zelf had kunnen vinden door de repository te lezen, leiden tot slechtere resultaten. De onderzoekers meten een daling van gemiddeld 3% in taakvoltooiing wanneer een AGENTS.md bestand gevuld is met redundante informatie.
De verklaring is logisch als je nadenkt over hoe taalmodellen werken. Elke token in de context kost rekenkracht en aandacht. Wanneer een agent zijn contextvenster moet verwerken, besteedt hij aandacht aan alles wat erin staat. Informatie die hij ook zelf had kunnen ophalen door een bestand te lezen, neemt ruimte in die beter gebruikt had kunnen worden voor de eigenlijke taak. Bovendien kan redundante context verwarring veroorzaken als ze niet perfect overeenkomt met wat de agent in de code aantreft.
De kostprijs van te veel context
Naast de kwaliteitsdaling meten de onderzoekers ook een kosteneffect. Uitgebreide AGENTS.md bestanden verhogen het tokenverbruik met gemiddeld 20%. Voor teams die op schaal met AI agents werken, is dat een significante extra kost zonder dat daar een evenredige kwaliteitsverbetering tegenover staat.
De combinatie van 3% slechtere prestaties en 20% hogere kosten bij overvolle contextbestanden is een duidelijk signaal: minder is meer. Een beknopt, goed doordacht contextbestand presteert beter dan een uitgebreid bestand dat alles probeert te documenteren.
Wat maakt een agents.md bestand effectief?
Op basis van de bevindingen in de paper tekent zich een duidelijk profiel af van wat een effectief contextbestand onderscheidt van een ineffectief of schadelijk bestand.
Alleen wat de agent niet zelf kan vinden
De gouden regel die uit het onderzoek naar voren komt, is simpel: neem alleen op wat de agent niet kan ontdekken door de repository zelf te verkennen. Als de informatie zichtbaar is in package.json, pyproject.toml, een Makefile of bestaande documentatie, hoort het niet in de AGENTS.md.
Wat wel thuishoort in een contextbestand zijn zaken als niet-voor-de-hand-liggende testprocedures, projectspecifieke conventies die nergens anders gedocumenteerd zijn, beveiligingsregels die strikt nageleefd moeten worden, of specifieke toolkeuzes die afwijken van de standaard voor een bepaalde taal of framework.
Beknoptheid als kwaliteitsmaatstaf
De onderzoekers stellen dat een contextbestand van vijf regels dat uitsluitend relevante, niet-redundante informatie bevat, beter presteert dan een bestand van vijftig regels dat ook allerlei voor de hand liggende zaken documenteert. De doelstelling bij het schrijven van een AGENTS.md zou moeten zijn: zo kort mogelijk, zo informatief mogelijk.
Een praktische vuistregel die uit de studie volgt. Als je een regel schrijft en je denkt de agent kan dit ook zelf zien als hij de code leest, schrap die regel. Elke regel die je toevoegt, kost tokens en aandacht. Die investering moet renderen in de vorm van informatie die de agent nergens anders vandaan kan halen.
Structuur en precisie
Naast beknoptheid speelt ook de kwaliteit van de formulering een rol. Vage instructies zoals schrijf goede code of volg best practices hebben geen meetbaar positief effect. Concrete, specifieke instructies zoals gebruik altijd uv in plaats van pip voor pakketbeheer” of sla API-sleutels uitsluitend op in .env en zorg dat .env in .gitignore staat zijn wel effectief omdat ze gedrag sturen dat de agent anders niet zou vertonen.
Wat zegt dit over context engineering?
De bevindingen van deze studie sluiten aan bij een breder inzicht dat zich de laatste tijd aftekent in het onderzoek naar AI agents: context engineering is een vak apart, en meer context is zelden beter dan minder context.
Coding agents zoals Claude Code, Codex en Qwen Code zijn in staat om zelf informatie op te halen uit een repository. Ze kunnen bestanden lezen, de structuur verkennen, configuratiebestanden analyseren. Wanneer een AGENTS.md bestand informatie herhaalt die de agent ook zelf had kunnen vinden, ondermijnt dat de autonome verkenningscapaciteit van de agent en voegt het ruis toe aan de context.
Dit is een fundamenteel ander perspectief dan de intuïtieve aanname dat meer context altijd beter is. De studie laat zien dat de kwaliteit van de context belangrijker is dan de kwantiteit. Een agent die zijn contextvenster moet verwerken, doet dat het best wanneer elke token in die context unieke, relevante informatie draagt.
Praktische implicaties voor teams die met AI agents werken
De bevindingen van de ETH Zurich studie hebben directe praktische gevolgen voor iedereen die AGENTS.md bestanden gebruikt of overweegt te gebruiken.
Ten eerste is het de moeite waard om bestaande contextbestanden kritisch te evalueren. Welke regels bevatten informatie die de agent ook zelf had kunnen vinden? Verwijder ze.
Ten tweede suggereert de studie dat het zinvol is om contextbestanden te behandelen als levende documenten die groeien op basis van concrete problemen. Wanneer een agent een fout maakt die voorkomen had kunnen worden met een specifieke instructie, is dat het moment om die instructie toe te voegen. Niet als preventieve maatregel voor alle denkbare problemen, maar als een correctie voor een probleem dat je bent tegengekomen.
Ten derde is het relevant om te weten dat het effect van contextbestanden verschilt per agent en per type taak. De studie meet gemiddelde effecten over 438 taken en vier agents, maar er is variatie. Voor sommige agents en sommige taken is het effect groter, voor andere kleiner. Dat betekent dat het de moeite waard is om te experimenteren en te meten in je eigen context, in plaats van blindelings een uitgebreid contextbestand te kopiëren van iemand anders.
Het onderzoek is niet universeel
Het is eerlijk om ook de beperkingen van het onderzoek te benoemen. De studie meet prestaties op SWE-bench Lite en AGENTbench, twee gestandaardiseerde benchmarks. Die benchmarks zijn representatief voor een bepaald type coderingstaken, maar ze dekken niet alle scenario’s af waarvoor coding agents in de praktijk worden ingezet.
Bovendien meet de studie de impact van contextbestanden op taakvoltooiing, niet op andere dimensies zoals codeerkwaliteit, leesbaarheid of naleving van projectspecifieke conventies. Het is denkbaar dat een uitgebreid contextbestand de taakvoltooiingsgraad licht verlaagt maar tegelijkertijd de kwaliteit van de geproduceerde code verbetert op dimensies die de benchmark niet meet.
De studie is ook een momentopname. De agents die getest werden, zijn specifieke versies van Claude Code, Codex en Qwen Code. Toekomstige versies van deze agents kunnen anders omgaan met contextbestanden, mogelijk efficiënter of met een beter begrip van wat relevante versus redundante informatie is.
De les die telt
De paper “Evaluating AGENTS.md” levert een waardevolle bijdrage aan het begrip van hoe context engineering werkt voor coding agents. De centrale les is helder: een AGENTS.md bestand is geen plek om alles te documenteren wat je weet over je project. Het is een plek voor informatie die de agent nergens anders kan vinden en die zijn gedrag op een concrete, meetbare manier stuurt.
