Onlangs zag ik de prestaties van een agent duidelijk achteruitgaan.

Een ontwikkeltaak die naar verwachting twintig tot dertig minuten zou kosten, nam uiteindelijk bijna drie uur in beslag. De agent liep niet vast op één bijzonder moeilijk probleem. De tijd verdween in lezen, beoordelen, controleren en opnieuw controleren.

Ik ben daarom de werkomgeving van de agent gaan ontleden.

Voordat de agent trager werd, was de omgeving al zwaarder geworden

Ik vond drie soorten problemen.

Ten eerste was de repository opgeblazen. Er stonden meerdere bronbestanden van meer dan 3.000 regels in, plus een tijdelijk evidence-bestand van ongeveer 110.000 regels. De .git-map was inmiddels 72 MB groot.

Die cijfers bewijzen op zichzelf niet hoeveel vertraging elk onderdeel veroorzaakte. Het echte waarschuwingssignaal was de hoeveelheid ruis waar de agent doorheen moest bij iedere zoekactie, bij het leggen van afhankelijkheden en bij het bepalen van de verantwoordelijkheid van een bestand. Zodra een tijdelijk resultaat eruitziet als een formeel feit, moet de agent bovendien tijd besteden aan de vraag of het wel betrouwbaar is.

Ten tweede waren er de Skills die ik eerder door AI had laten genereren. Ze werden steeds langer en bevatten veel stapsgewijze instructies, aangevuld met uitzonderingen voor historische problemen. Elke regel was afzonderlijk goed te verdedigen, maar samen begonnen ze de agent te micromanagen.

Ten derde waren er de veiligheidsmechanismen. Om de kans op fouten te verkleinen had ik steeds meer gates toegevoegd aan ontwikkeling en CI/CD. Daardoor werd de validatieketen langer en kwamen er meer mogelijke faalpunten bij. De agent was vaak niet meer bezig met het oorspronkelijke probleem, maar met nevenproblemen die door de validatiemechanismen zelf waren ontstaan.

Deze drie problemen hadden hetzelfde patroon: bij ieder nieuw risico voegden we iets toe. Code, documentatie en gates groeiden elk een beetje, totdat ze samen allemaal op het uitvoeringspad van de agent lagen.

Ik begon met schrappen

Voor de repository onderzocht ik eerst de verdeling van het aantal regels code. Ik zocht uitzonderlijk grote bestanden op en beoordeelde daarna per bestand of het moest worden opgesplitst, gearchiveerd, verwijderd of behouden.

Een groot bestand is niet automatisch een slecht bestand. Eerst controleer ik de werkelijke gebruikers, de gezaghebbende bron en de herstelmogelijkheid. Tijdelijke evidence-bestanden kunnen weg, historische feiten moeten soms worden gearchiveerd en alleen grote modules met een duidelijke verantwoordelijkheid komen in aanmerking voor refactoring. Bij code van meer dan 1.000 regels kijk ik of er meerdere verantwoordelijkheden in zitten die afzonderlijk beoordeeld en getest kunnen worden.

Ik ben ook de abstracties en mechanismen gaan reviewen die ooit zijn gebouwd om toekomstige risico’s af te dekken. Onlangs installeerde ik Ponytail, om te zien of het me kan helpen over-engineering consistenter te herkennen. Een tool kan het oordeel alleen ondersteunen. De kernvraag blijft: welk reëel risico keert terug als we deze laag verwijderen?

De grotere verandering vond plaats in Skills en AGENTS.md.

Van how-to naar what, where en why

Voorheen vertelde ik een agent:

  1. welk commando eerst moest worden uitgevoerd;
  2. welk bestand daarna moest worden gelezen;
  3. welke route bij een bepaalde status moest worden gevolgd;
  4. met welke stappen het resultaat uiteindelijk moest worden gevalideerd.

Op het moment dat ik zulke instructies opschreef, klopten ze meestal. Maar een how-to is zeer gevoelig voor externe veranderingen: tools krijgen updates, mappen verhuizen, branches veranderen en ook de runtime-status verandert. Het juiste uitvoeringspad van gisteren kan vandaag al een omweg zijn.

Nu wil ik liever dat een Skill vier soorten vragen beantwoordt:

  • What is there: welke entiteiten bestaan er in dit domein en waarvoor is elk daarvan verantwoordelijk;
  • Where are they: waar staan de gezaghebbende feiten, de runtime-status en de outputs;
  • What you might miss: welke grenzen, uitzonderingen en foutstatussen gemakkelijk over het hoofd worden gezien;
  • Why: waarom deze beperkingen bestaan en wat ze beschermen.

Voor één sessie beschrijft een Goal het gewenste resultaat, de acceptatiecriteria en de grenzen van de autorisatie. Met die relatief stabiele informatie kan de agent op basis van de actuele omgeving zelf bepalen hoe hij verdergaat.

Goal
  Wat moet deze keer worden bereikt, en wanneer is het klaar?

Skill / Context
  Wat bestaat er → waar staat het → wat wordt snel gemist → waarom is het belangrijk?

Agent
  Lees de actuele status → bepaal de aanpak voor deze keer → valideer aan de hand van het resultaat

Dat betekent niet dat operationele instructies helemaal verdwijnen. Gevaarlijke, onomkeerbare handelingen en acties die consequent moeten worden uitgevoerd, vragen nog steeds om expliciete regels. Het verschil zit in het niveau: regels beschrijven invarianten en beslisgrenzen. Een draaiboek hoort alleen thuis waar daadwerkelijk één juiste route bestaat.

Ik ben niet de enige die dit ziet

Later ontdekte ik dat de sector onder verschillende namen een vergelijkbare verandering beschrijft.

Anthropic noemt dit Context Engineering: context is een beperkt aandachtsbudget, dus het doel is de kleinste verzameling informatie met een hoge signaalwaarde te vinden die het gewenste gedrag oplevert. Het gedrag van een agent te strak coderen levert broze prompts op die moeilijk te onderhouden zijn. Het werkt beter om een niveau te vinden dat specifiek genoeg is en tegelijk ruimte laat voor eigen afwegingen.

Voor zijn SWE-bench-agent gebruikte Anthropic ook een minimal scaffold: geef het model de taak, de repository en enkele basistools, en laat het zelf bepalen hoe het verdergaat, in plaats van de workflow vast te leggen als strikte statusovergangen.

OpenAI noemt de praktijk aan de kant van de codebase sinds kort Harness Engineering. Eén principe vat precies samen wat ik probeer te bereiken: dwing grenzen centraal af en behoud autonomie daarbinnen. Mensen bepalen doelen, prioriteiten en acceptatie. De repository maakt architectuur, tools en feiten vindbaar voor de agent. De agent kiest het concrete uitvoeringspad.

“Minder how-to schrijven” is dus maar de helft van het verhaal. Effectief schrappen vraagt om twee dingen tegelijk:

  1. processturing verwijderen die snel veroudert;
  2. feiten over de omgeving, verantwoordelijkheidsgrenzen en acceptatievoorwaarden beter vindbaar maken.

Anders wordt een korte Skill simpelweg een Skill met te weinig informatie.

Eerste resultaten

Ik verwijderde de how-to uit een reeks Skills en behield de verantwoordelijkheden, locaties, gemiste aandachtspunten en achterliggende redenen. De hoofdtekst van die Skills werd meer dan 50% korter.

Ik heb nog niet genoeg betrouwbare data om te stellen hoeveel de productiviteit is gestegen. Mijn subjectieve indruk is dat agents minder vaak oude stappen mechanisch blijven uitvoeren en taken sneller afronden. Als volgende stap moet ik de taakduur, nutteloze toolaanroepen, herhaalde validaties en menselijke interventies vastleggen. Pas dan kan ik van die indruk een geloofwaardige conclusie maken.

De veiligheidsgates zijn nog niet opgelost

Code en Skills kunnen geleidelijk slanker worden door te verwijderen, archiveren en refactoren. Veiligheidsgates zijn moeilijker. De kosten van wachten zijn direct zichtbaar, terwijl de incidenten die een gate voorkomt meestal niet plaatsvinden en dus moeilijker meetbaar zijn.

Ik wil ze daarom op een andere manier gaan beoordelen. Per gate vraag ik niet meer alleen of hij het systeem veiliger maakt, maar:

  • Welk concreet vastgesteld risico beschermt deze gate?
  • Begrenst hij het resultaat en de invarianten, of schrijft hij het implementatieproces voor?
  • Hoeveel echte defecten heeft hij onderschept, en hoeveel valse meldingen en wachttijd heeft hij veroorzaakt?
  • Kan hij parallel worden uitgevoerd, alleen bij een passend risiconiveau worden geactiveerd of dichter bij de uiteindelijke grens worden geplaatst?
  • Kunnen bestaande tests, rechten of rollbackmechanismen hetzelfde risico afdekken als we hem verwijderen?

OpenAI’s praktische gids voor AI-agents adviseert guardrails geleidelijk toe te voegen op basis van risico’s die in de praktijk zijn vastgesteld, en daarbij zowel veiligheid als gebruikerservaring te optimaliseren. Voor mij betekent dit dat ook veiligheidsmechanismen bewijs en een levenscyclus nodig hebben. Het label “veiligheid” maakt ze niet permanent vrijgesteld van beoordeling.

Mijn huidige kijk op samenwerking met agents is:

Geef een agent doelen, realiteit en grenzen. Laat hem op basis van de realiteit van dit moment het pad voor dit moment bepalen.

Naarmate agents sterker worden, ligt het waardevolste menselijke werk misschien steeds minder in het uitschrijven van gedetailleerde stappen. Het ligt in het zichtbaar maken van de feiten die er echt toe doen, en in het moeilijker maken om cruciale grenzen te overschrijden.