Technische Samenvatting: Evaluatie van AGENTS.md

Probleemstelling

De software engineering-industrie heeft snel de overstap gemaakt naar coding agents, waarbij een algemene aanbeveling van model- en agent-ontwikkelaars is om deze agents af te stemmen op specifieke repositories met behulp van contextbestanden (bijv. AGENTS.md of CLAUDE.md). Deze bestanden bevatten doorgaans overzichten van de repository, instructies voor tooling en stijlgidsen bedoeld om navigatie, de uitvoering van builds en taakresolutie te verbeteren. Ondanks de brede adoptie—gerapporteerd in meer dan 60.000 open-source repositories—en sterke industriële aanmoediging, is er geen rigoureuze, grootschalige onderzoek uitgevoerd naar de vraag of deze contextbestanden de prestaties van coding agents op real-world taken daadwerkelijk verbeteren. Eerdere benchmarks zoals SWE-bench missen contextbestanden, en populaire repositories die in dergelijke benchmarks worden gebruikt, vertegenwoordigen vaak niet de codebases waarin contextbestanden daadwerkelijk worden ingezet.

Methodologie

Om dit gat te dichten, hebben de auteurs een uitgebreide evaluatie uitgevoerd in twee complementaire settings:

1. Nieuwe Benchmark (CTXBENCH): De auteurs hebben een nieuwe benchmark geconstrueerd bestaande uit 138 instanties afgeleid van echte GitHub-issues in 12 niche, Python-gebaseerde repositories die al door ontwikkelaars gecommitteerde contextbestanden bevatten. In tegenstelling tot SWE-bench, dat leunt op populaire repositories, richt CTXBENCH zich op repositories waar contextbestanden een actieve praktijk zijn. De generatie van de dataset omvatte:

   • Het filteren van repositories met AGENTS.md of CLAUDE.md en ten minste 400 Pull Requests (PR's).
   • Het selecteren van PR's die deterministische, testbare gedragingen introduceren.
   • Het gebruik van LLM-agents om gestandaardiseerde taakbeschrijvingen en nieuwe unit tests te genereren waar de originele PR's deze misten, waarbij de tests slagen op de gefixeerde code maar falen op de basiscode.
   • Het valideren dat door ontwikkelaars geleverde contextbestanden verschillen van door LLM's gegenereerde bestanden (korter, lagere AI-detectiescores).

2. Experimentele Opstelling: De studie evalueerde vier coding agents (CLAUDE CODE, CODEX, QWEN CODE) gekoppeld aan diverse modellen (SONNET-4.5, GPT-5.2, GPT-5.1 Mini, QWEN3-30B-CODER) op twee datasets:

   • SWE-BENCH Lite: 300 taken uit populaire repositories zonder door ontwikkelaars geleverde contextbestanden.
   • CTXBENCH: 138 taken uit repositories met door ontwikkelaars geleverde contextbestanden.

3. Evaluatiecondities: Voor elke taak werden agents getest in drie settings:

   • None: Geen contextbestand verstrekt.
   • LLM: Een contextbestand automatisch gegenereerd door de aanbevolen initialisatiecommand van de agent.
   • DEV: Het werkelijke door de ontwikkelaar gecommitteerde contextbestand (alleen beschikbaar voor CTXBENCH).

4. Metrieken: Prestaties werden gemeten aan de hand van het succespercentage (percentage taken waarbij de gegenereerde patch alle tests doorstaat), het aantal interactiestappen en de totale inferentiekosten. Trace-analyse werd uitgevoerd om gedragsveranderingen te begrijpen, inclusief de frequentie van toolgebruik en het verbruik van reasoning tokens.

Belangrijkste Bijdragen

1. CTXBENCH: Een nieuwe benchmark specifiek ontworpen om de impact van actief gebruikte, door ontwikkelaars geleverde contextbestanden op coding agents te evalueren, met 138 instanties uit 12 repositories.
2. Uitgebreide Evaluatie: Een uitgebreide studie over meerdere modellen en agents op zowel SWE-BENCH als CTXBENCH, die aantoont dat contextbestanden de succespercentages van taken niet significant verbeteren.
3. Gedragsanalyse: Een gedetailleerde investigatie van agent-traces die aantoont dat hoewel agents de instructies in contextbestanden strikt opvolgen (wat leidt tot meer testen en exploratie), deze bestanden er niet in slagen effectieve overzichten van de repository te dienen en de operationele kosten verhogen.

Resultaten

De studie levert verschillende contra-intuïtieve bevindingen op met betrekking tot de effectiviteit van contextbestanden:

• Geen Prestatiewinst: Het verstrekken van contextbestanden verbetert de succespercentages van taken over het algemeen niet.
  • Op SWE-BENCH resulteerden door LLM gegenereerde contextbestanden in een marginale, statistisch insignificante daling van de succespercentages (gemiddeld -0,5%).
  • Op CTXBENCH vertoonden door LLM gegenereerde bestanden ook geen significante verbetering (gemiddeld -2%).
  • Door ontwikkelaars gecommitteerde bestanden vertoonden een marginale verbetering van 2,4% gemiddeld ten opzichte van de "None"-setting, maar dit was niet statistisch significant ($p=0,21$). Echter, ontwikkelaarsbestanden presteerden significant beter dan door LLM gegenereerde bestanden ($p=0,038$).
• Verhoogde Kosten en Stappen: Contextbestanden verhogen consistent de kosten en de complexiteit van taakresolutie.
  • Door LLM gegenereerde bestanden verhoogden de inferentiekosten gemiddeld met meer dan 20% over beide benchmarks.
  • Door ontwikkelaars gecommitteerde bestanden verhoogden de kosten met maximaal 19%.
  • Het aantal interactiestappen nam significant toe in alle settings met contextbestanden.
• Gedragsmechanismen:
  • Instructie-opvolging: Agents volgen instructies in contextbestanden strikt op. Wanneer specifieke tools (bijv. uv, pytest) worden genoemd, neemt het gebruik ervan dramatisch toe. Dit leidt tot grondiger testen, bestandsexploratie en repository-specifiek toolgebruik.
  • Ineffectieve Overzichten: Ondanks de aanbevelingen om codebase-overzichten op te nemen, helpen deze secties agents niet om relevante bestanden sneller te lokaliseren. In feite besteden agents vaak extra stappen aan het zoeken naar en opnieuw lezen van contextbestanden die al in hun contextvenster aanwezig zijn.
  • Reasoning Overhead: De aanwezigheid van contextbestanden verhoogt het aantal gebruikte reasoning tokens door adaptieve modellen (bijv. +22% voor GPT-5.2 met door LLM gegenereerde bestanden), wat suggereert dat de aanvullende instructies de taak cognitief moeilijker maken zonder noodzakelijke informatie te bieden.
• Redundantie: Contextbestanden fungeren vaak als redundante documentatie. Wanneer bestaande documentatie (README's, docs-mappen) wordt verwijderd, verbeteren door LLM gegenereerde contextbestanden de prestaties daadwerkelijk, wat suggereert dat hun primaire waarde in standaardsettings eerder redundantie is dan unieke inzichten.

Betekenis en Conclusie

Het paper concludeert dat de huidige industriële praktijk van het automatisch genereren of breed opnemen van contextbestanden zoals AGENTS.md niet wordt ondersteund door empirisch bewijs voor het verbeteren van de prestaties van coding agents. Hoewel agents de instructies binnen deze bestanden opvolgen, wat leidt tot een grondiger (en duurdere) exploratie, falen de bestanden er over het algemeen in effectieve overzichten van de repository te bieden die de taakresolutie versnellen.

De auteurs betogen dat contextbestanden gereserveerd moeten worden voor het specificeren van niet-standaard programmeerpraktijken of specifieke conventies die niet al aanwezig zijn in de README van de repository. Ze raden aan dat ontwikkelaars elke poging om contextbestanden te gebruiken grondig evalueren voordat ze worden uitgerold, in plaats van te vertrouwen op automatische generatie of brede aanbevelingen. Dit werk benadrukt een kloof tussen de aanbevelingen van agent-ontwikkelaars en de geobserveerde resultaten, wat motiveert voor toekomstig onderzoek naar principiële, beknopte en taakrelevante generatie van begeleiding voor coding agents.