Context engineering vereist een feedbacklus

Context engineering is de discipline waarbij een AI-agent de juiste informatie, in de juiste vorm en op het juiste moment krijgt — zodat deze goed werk verricht in plaats van te moeten gissen. In de praktijk betekent dit voor de meeste teams dat er bestanden zijn: eenCLAUDE.md in de hoofdmap van de repository, een AGENTS.md, een map met regels en conventies, en een systeemprompt die iemand ooit eenmaal heeft afgestemd. U legt vast hoe uw project werkt, zodat de agent dit niet bij elke sessie opnieuw hoeft te ontdekken.

Het is werkelijk de meest effectieve maatregel die u kunt nemen om agents bruikbaar te maken. En bijna iedereen die dit doet, kampt met hetzelfde onuitgesproken probleem: die bestanden raken verouderd, en niemand weet welke delen precies. U hebt de context één keer opgesteld, de codebase is verder ontwikkeld, en nu is de helft ervan stilletjes onjuist geworden. Deze werkwijze kent een input – het schrijven van context – maar geen onderhoudscyclus. Dat is de leemte waar dit bericht over gaat.

Context is code, en code veroudert

We weten al dat documentatie verouderd raakt. De bouwstap die u hebt gedocumenteerd, wordt vervangen, de map die u hebt beschreven, krijgt een andere naam, de conventie die u hebt vastgelegd, wordt achterhaald — en de documentatie blijft vol vertrouwen de oude situatie beschrijven. Contextbestanden zijn in dit opzicht nog erger dan gewone documenten, en wel om twee redenen.

Ten eerste leest een agent deze instructies letterlijk en voert ze uit. Een mens bladert door een verouderde README, merkt dat er iets niet klopt en vraagt het aan iemand. Een agent neemtCLAUDE.mdhet letterlijk. Als er staat „run make setup“ en dat doel is vorig kwartaal verwijderd, haalt de agent niet zijn schouders op — hij verspilt tijd met pogingen om het verkeerde te laten werken, of hij bedenkt een tijdelijke oplossing en gaat verder, waarbij hij de verkeerde instructie in zijn uitvoer meeneemt.

Ten tweede: een onjuiste context is erger dan een ontbrekende context. Een leemte kan het systeem soms omzeilen of signaleren. Een zelfverzekerd, maar onjuist statement neemt het echter voor waar aan. De duurste regels in uw contextbestanden zijn niet de ontbrekende regels — het zijn juist de regels die vroeger waar waren.

U hebt dus een onderhoudscyclus nodig. Het probleem is dat de gebruikelijke oplossingen niet werken. U gaatCLAUDE.mdde code niet regel voor regel controleren volgens een vast schema — dat doet niemand. Van buitenaf merkt u niet dat de code verouderd is, omdat deze prima leesbaar blijft. De veroudering komt pas aan het licht op het moment van gebruik, voor degene die er gebruik van maakt. En steeds vaker is degene die er gebruik van maakt geen mens.

De enige getuige die het weet

Hier zit de verandering. De agent die zojuist een sessie met betrekking tot uw project heeft uitgevoerd, is de enige deelnemer die concreet weet welke delen van uw context nuttig waren en welke delen onjuiste informatie bevatten. Het heeft alleen de bestanden gebruikt. Het heeft de verouderde build-opdracht uitgevoerd. Het heeft de map gevonden die niet bestaat. Het heeft het patroon gevolgd dat uiteindelijk uit drie patronen bleek te bestaan. Die kennis bestaat — ongeveer zolang de sessie duurt, en daarna is ze verdwenen.

Niemand vertelt u welke context ontbreekt of onjuist is, behalve het systeem dat er zojuist last van heeft gehad. Dat is de feedbacklus, die daar gewoon ligt, onbenut. Het enige wat u hoeft te doen, is de agent vragen om op te schrijven wat hij heeft geleerd voordat de sessie wordt afgesloten — en de vraag zo te formuleren dat de uitvoer rechtstreeks verwijst naar de bestanden die moeten worden bewerkt.

Het retro-logboek van de sessie is de onderhoudscyclus

Dit is precies wat een AI-terugblik aan het einde van een sessie oplevert. Aan het einde van een werksessie schrijft de agent een kort, eerlijk verslag: wat ging er goed, waar ontstonden er knelpunten, en — het deel dat hier van belang is — elk knelpunt wordt gelabeld met een van de tien vaste labels voor de onderliggende oorzaak en eindigt met een „→ Oplossing:“ ter grootte van een ticket. Twee van die tien labels verwijzen rechtstreeks naar uw contextbestanden:

• missing-documentation**** — de medewerker had iets nodig dat in het project had moeten worden gedocumenteerd, maar dat was niet gebeurd. Dit is de te schrijven-lijst van uw contextbestand. Elk van deze punten is een regel die u aanCLAUDE.md uw documentatie moet toevoegen.
• incorrect-documentation**** — de documentatie bestond wel, maar was onjuist of verouderd. Dit is de te corrigeren-lijst van uw contextbestand. Elk van deze regels is een verouderde regel die de agent op de enige mogelijke manier heeft opgemerkt: door deze te gebruiken en tegen een probleem aan te lopen.

Voeg daar nog een derde punt aan toe en u hebt het grootste deel van het onderhoud dat u ooit nodig zult hebben gedekt: ambiguous-instruction****, wanneer een instructie of een regel op meer dan één manier kan worden geïnterpreteerd. Dat is de vicieuze cirkel. U controleert uw contextbestanden niet volgens een vast schema; u laat de agenten die er gebruik van maken u op het moment van gebruik precies vertellen welke regels moeten worden gewijzigd — met het bijbehorende bewijsmateriaal, aangezien deze werkwijze uitsluitend op bewijs is gebaseerd.

En er is nog een vierde signaal dat gemakkelijk over het hoofd wordt gezien: de gissingen. Een goed verslag somt elk punt op waar de agent een leemte heeft opgevuld met een veronderstelling. Elke gissing is een plek waar uw context zo summier was dat de agent een antwoord moest verzinnen. Lees een week aan gissingen door en u beschikt over een takenlijst voor uw contextbestanden die u zelf nooit had kunnen opstellen — omdat u de antwoorden al kent en daardoor niet kunt zien waar ze ontbreken.

Dit is een voorbeeld van wat er wordt weergegeven — een illustratief voorbeeld, geen echte gegevens:

## Friction
- CLAUDE.md says "run `make setup`" but that target was removed; the
  actual setup is `pnpm install && pnpm db:migrate`. Lost ~10 min.
  (incorrect-documentation)
  → Fix: Update the "Getting started" block in CLAUDE.md to the pnpm commands.
- Nothing documents that integration tests need the worker running.
  Found it by reading the CI config. (missing-documentation)
  → Fix: Add a "Running tests" note naming `pnpm worker` as a prerequisite.

## Guesses I made
- Assumed the `api/` package is the public surface and `internal/` is not,
  because nothing states it. Please confirm before I rely on it again.

Elke regel bevat een specifieke wijziging in een specifiek bestand. Dat is een onderhoudscyclus die iemand daadwerkelijk zal uitvoeren, omdat het opsporen van het probleem — het meest tijdrovende deel — al is voltooid.

Waarom dit beter is dan handmatig controleren

U zou kunnen proberen de contextbestanden op de oude manier actueel te houden: een evaluatie inplannen, ze van begin tot eind doorlezen en elke bewering toetsen aan de werkelijkheid. Dit gebeurt echter niet, en zelfs als het wel gebeurt, is het niet het juiste instrument. Wanneer u een document in abstracto leest, kunt u niet zien welke regels verouderd zijn — ze klinken allemaal aannemelijk. De veroudering wordt pas zichtbaar bij gebruik. Het retro-logboek is contextonderhoud aangestuurd door daadwerkelijk gebruik: alleen de regels die daadwerkelijk een agent hebben geactiveerd, worden gemarkeerd, zodat u repareert wat echt kapot is in plaats van opnieuw te lezen wat al in orde is. Het is het verschil tussen een rookmelder en door het gebouw lopen om naar rook te snuffelen.

Dit effect versterkt zich bovendien. Als u deincorrect-documentationpunten deze week aanpakt, zullen de sessies van volgende week minder vaak tegen die muur aanlopen, waardoor het logboek korter wordt en de aandacht kan verschuiven naar diepere kwesties. Uw contextbestanden worden steeds nauwkeuriger, niet omdat iemand ze heeft gecontroleerd, maar omdat de mensen – en de agents – die ze gebruiken een eenvoudige, gestructureerde manier hadden om de afwijking te melden. Dat is een gezonde samenwerking tussen mens en AI: de agent brengt de afwijking aan het licht, de mens beslist over de aanpassing.

Start de lus

Als u al investeert in context engineering, dan is dit de ontbrekende helft — de onderhoudscyclus die ervoor zorgt dat de investering niet verloren gaat. Het is open source en valt onder de MIT-licentie:

• Download de vaardigheden en het promptpakket: github.com/TeamRetroHQ/teamretro-skills — een Claude Code-skill die het verslag aan het einde van de sessie opstelt, een skill die verslagen samenvat tot een korte samenvatting, en een tool-onafhankelijk promptpakket voor Cursor, GitHub Copilot of elke andere agent waaraan u prompts kunt geven.
• Bekijk de volledige werkwijze: hoe u feedback van uw AI-agenten kunt verzamelen behandelt alle tien labels, de controle door een mens en hoe de bijdragen worden meegenomen in een teamretrospective — niet alleen in uw contextbestanden.

Een nuance die het vermelden waard is: wanneer een medewerker aangeeft dat de documenten onjuist zijn, controleer dit dan eerst voordat u wijzigingen aanbrengt — soms zijn de documenten juist en heeft de medewerker ze verkeerd geïnterpreteerd. Dat is nog steeds een nuttige aanwijzing (een regel die gemakkelijk verkeerd kan worden gelezen, is een regel die het waard is om te herschrijven), maar het is een andere oplossing, en daarom blijft er een mens bij het proces betrokken. De agent is een deelnemer die aangeeft wat hem of haar opviel, nooit de autoriteit die bepaalt wat er in uw project moet staan.

Uw contextbestanden zijn slechts zo goed als hun laatste eerlijke correctie. De agenten die ze gebruiken, geven u die correcties aan het einde van elke sessie door — u hoeft ze alleen maar op te schrijven. En als uw team wil dat die verbeteringen terechtkomen op een plek waar mensen al kijken, kan de agent zijn aanbevelingen opstellen en deze zelf via de TeamRetro MCP-server op uw bord plaatsen — door u bevestigd, gemarkeerd [AI retro]met , naast de overige verbeteringen van uw team.