Stop met tijd verspillen aan instructies voor AI-agents. Ze maken dingen erger.

Je probeert je AI-coding assistent slimmer te maken. Je besteedt uren aan het schrijven van gedetailleerde AGENTS.md-bestanden, CONTEXT.md-bestanden of aangepaste instructies. Je denkt dat je de AI helpt om je codebase beter te begrijpen.

Je helpt niet. Je maakt het erger.

Het probleem dat je herkent

Je team investeert tijd in het maken van aangepaste instructiebestanden voor AI-hulpmiddelen zoals GitHub Copilot, Cursor of Claude Code. Je gelooft dat dit de prestaties verbetert. Het doet het niet. Het vertraagt je juist en kost je meer geld.

Wat onderzoekers ontdekten

Onderzoekers van de ETH Zurich voerden een uitgebreide studie uit, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?". Ze testten of die speciale instructiebestanden de AI-coding assistenten echt helpen bij het voltooien van taken.

De resultaten waren duidelijk en tegenintuïtief.

Gedetailleerde contextbestanden maken AI-agents slechter presteren.

Stel je voor dat je een nieuwe ontwikkelaar inhuurt en hem een 50 pagina's tellend handboek van "handige tips" over je codebase geeft. In plaats van hem productief te maken, verwarrend het handboek hem. Hij besteedt meer tijd aan het lezen van je notities dan aan het schrijven van code. Dat is exact wat er gebeurt met AI-agents.

De bovenstaande grafiek toont de harde gegevens. Over meerdere AI-modellen en benchmarktaken heen, verlagen toegevoegde contextbestanden (zowel AI-gegenereerd als door mensen geschreven) consistent de taakvoltooiingspercentages. De AI voltooit minder taken correct wanneer je hem die "handige" instructies geeft.

Deze bestanden verhogen de kosten ook met meer dan 20%.

Het is alsof een taxichauffeur een langere, schilderachtige route neemt omdat je hem te gedetailleerde instructies gaf. Je betaalt een hoger tarief voor een slechtere uitkomst. De AI gebruikt meer rekenbronnen ("tokens") om je instructies te verwerken, waardoor je API-kosten direct toenemen.

De gegevens tonen een duidelijke kostenstijging. Meer tokens betekenen hogere rekeningen van OpenAI, Anthropic of andere AI-aanbieders.

De AI verkent meer, maar bereikt minder.

De contextbestanden zorgen ervoor dat de AI zich gedraagt als een detective die wordt opgedragen "geen steen ongewend te laten" in een eenvoudige zaak. Het verspilt tijd aan het onderzoeken van irrelevante aanwijzingen in plaats van de misdaad op te lossen. De agent voert meer tests uit, controleert meer bestanden en neemt meer stappen, maar deze extra activiteit leidt niet tot betere resultaten.

Zoals hierboven wordt getoond, start de AI zonder contextbestanden sneller met het werken aan het eigenlijke probleem. Met contextbestanden duurt het langer voordat het begint met het werken aan de juiste bestanden.

Hoe je dit vandaag kunt toepassen

Stop onmiddellijk met het maken van gedetailleerde instructiebestanden. Hier is je actieplan voor deze week:

1. Audit je huidige AI-contextbestanden

Actie: Verzamel alle AGENTS.md, CONTEXT.md, .cursorrules of soortgelijke bestanden in je repositories.

Hoe je het doet:

• Voer een eenvoudige zoekopdracht uit in je codebase: find . -name "*AGENT*" -o -name "*CONTEXT*" -o -name "*.cursorrules*"
• Maak een spreadsheet met elk bestand, de lengte (woordtelling) en het team dat het gebruikt
• Bijvoorbeeld: /project-alpha/AGENTS.md (1.200 woorden), gebruikt door Frontend Team

Verwachte inspanning: 1-2 uur voor een teamleider. Dit geeft je basismateriaal.

2. Vervang gedetailleerde bestanden door minimale sjablonen

Actie: Vervang elk gedetailleerd contextbestand door een eenvoudig, 3-5 regels tellend sjabloon.

Sjabloon om te gebruiken:
```

Projectcontext

• Taal: [bijv. Python, JavaScript]
• Type: [bijv. webservice, mobiele app, bibliotheek]
• Sleutelbeperking: [ÉÉN zin, bijv. "Moet backward compatible zijn met API v2"]
  ```

Voorbeeldtransformatie:

• Voorheen: 500-woord AGENTS.md dat coderingsstandaarden, mapstructuur, testfilosofie, implementatieproces beschrijft
• Na: "Python-webservice. Moet backward compatible zijn met API v2."

Waarom dit werkt: De AI leest je daadwerkelijke code beter dan je beschrijvingen over je code. Geef hem de essentiële beperkingen en laat hem werken met de bronbestanden rechtstreeks.

3. Meet het effect

Actie: Volg twee metrieken gedurende één sprint (2 weken) na het verwijderen van gedetailleerde contextbestanden.

Metrieken om te volgen:

1. Taakvoltooiingspercentage: Hoeveel AI-ondersteunde coderingstaken worden met succes voltooid in één keer?
2. AI-gebruikskosten: Vergelijk je maandelijkse AI-API-rekeningen voor en na de wijziging.

Hulpmiddelen om te gebruiken:

• Voor taakvolgen: Je bestaande Jira, Linear of GitHub Issues
• Voor kosten volgen: OpenAI-gebruiksdashboard, Anthropic-console of de kostenanalysehulpmiddelen van je cloudprovider

Verwacht resultaat: Op basis van het onderzoek zou je binnen een maand verbeterde taakvoltooiing en lagere kosten moeten zien.

4. Train je team in de nieuwe aanpak

Actie: Voer een 30-minuten teamvergadering uit om de wijziging uit te leggen.

Agenda:

1. Deel de onderzoeksbevindingen (5 minuten)
2. Toon je auditresultaten (5 minuten)
3. Demonstreer het nieuwe minimale sjabloon (5 minuten)
4. Q&A en adresseer zorgen (15 minuten)

Sleutelboodschap: "We verwijderen geen AI-ondersteuning. We maken het effectiever door onhandige instructies te verwijderen."

5. Maak een beleid voor nieuwe projecten

Actie: Voeg een sectie toe aan je engineeringsonboardingsdocumentatie.

Beleidstekst:
"Voor AI-coding assistenten: Gebruik alleen minimale contextbestanden. Beschrijf het project in 1-2 zinnen maximaal. Maak geen gedetailleerde AGENTS.md-bestanden. De AI presteert beter wanneer deze rechtstreeks met code werkt in plaats van je beschrijvingen van de code te lezen."

Handhaving: Voeg dit toe aan je code-reviewchecklist. Wijs pull requests af die lange contextbestanden toevoegen.

Waar je op moet letten

1. Het onderzoek heeft beperkingen. De studie testte specifieke coderingstaken (SWE-bench en AGENTbench). De prestaties kunnen variëren bij geheel andere problemen, zoals complexe architectuurbeslissingen of beveiligingskritische code. Echter, voor dagelijkse coderingstaken zijn de bevindingen duidelijk.

2. Er kunnen zeldzame uitzonderingen zijn. Als je een echt unieke beperking hebt die niet in de code zelf zichtbaar is - zoals "deze functie moet binnen 10ms voltooid zijn voor regelgevingsredenen" - kan een korte notitie helpen. Maar dit moet de uitzondering zijn, niet de regel.

3. Teamterugkoppeling. Sommige ontwikkelaars geloven sterk in gedetailleerde documentatie. Presenteer de gegevens, niet meningen. Toon hen de onderzoeksgrafieken en je eigen metrieken na implementatie.

Je volgende stap

Begin met het auditen van één project deze week. Kies een repository waarin je team AI-assistenten frequent gebruikt. Vind en verwijder het AGENTS.md-bestand. Vervang het door het 3-regels sjabloon hierboven.

Volg vervolgens wat er gebeurt. Ziet de AI er effectiever uit? Worden taken sneller voltooid?

Deel je resultaten met je team. Als je verbeteringen ziet, breid het uit naar andere projecten.

Vraag voor jou: Hoeveel uren heeft je team besteed aan het schrijven van AI-instructiebestanden die je AI-hulpmiddelen mogelijk minder effectief maken? Deel je schatting in de comments hieronder.