Begrijpen is de nieuwe bottleneck

Dit is de uitgeschreven versie van een presentatie die ik in juli 2026 gaf op de AI Engineer-conferentie, evenals een reeks tweets.

Pittige stelling: ik denk dat het nog steeds essentieel is om de code te begrijpen die onze agents schrijven! In deze tekst leg ik uit waarom dat zo is en deel ik enkele ideeën over hoe je code efficiënt kunt doorgronden. Laten we beginnen.

Agents schrijven steeds meer code voor ons, en we merken allemaal dat het moeilijker wordt om bij te blijven. Het goede nieuws is dat er veel manieren zijn om code te begrijpen; het regel voor regel lezen van diffs is niet de enige methode.

Het grootste deel van dit artikel gaat over technieken die ik nuttig heb gevonden om systemen te begrijpen die door mijn agents zijn gebouwd:

• Code-uitlegdocumentatie (explainer docs)
• Quizzen om mijn begrip te controleren
• Micro-werelden waarmee ik kan spelen om het systeem te begrijpen

Maar eerst moeten we een fundamentelere vraag stellen...

Waarom begrijpen?

Waarom zouden we nog willen begrijpen? Moeten we onszelf niet juist uit de loop halen en de agents hun eigen gang laten gaan? Naarmate agents slimmer worden, wordt het toch minder belangrijk dat wij tot in de details op de hoogte zijn?

Ik denk dat veel mensen — zelfs zij die voorstander zijn van begrip — hier een onvolledig antwoord op hebben.

Eén mogelijk antwoord is: we begrijpen om te verifiëren. We controleren het werk van de agent en kijken of het correct is. "Correct" kan veel betekenen: voldoet het aan de specificaties, is de architectuur goed... maar fundamenteel is dit een vraag met een ja/nee-antwoord.

Het punt is dat agents steeds beter worden in het verifiëren van hun eigen werk. En dat is goed; ik ben blij als mijn agent geen fouten maakt. Maar waar laat dat ons als mensen?

Hier komt een ander antwoord: we begrijpen om te participeren.

Je leert wat de agent doet, zodat je een actieve deelnemer kunt blijven in het creatieve proces. Dit is waarom dit ertoe doet: een project bestaat nooit uit slechts één loop, maar uit vele loops met de agent. Het begrip dat je van het systeem hebt, bepaalt mede je vermogen om het volgende idee te bedenken om het systeem verder te ontwikkelen.

Je hebt een rijke set concepten in je hoofd nodig om creatief en vloeiend na te denken over hoe je iets vooruit helpt. Als je die vloeiendheid mist, is je vermogen om aan het project bij te dragen meaningful beperkt.

Dit hangt nauw samen met het idee van cognitieve schuld (cognitive debt), gepopulariseerd door Margaret Storey en Simon Willison. Het lijkt op technische schuld: op de korte termijn kun je wegkomen met het feit dat je niet begrijpt wat er aan de hand is, maar uiteindelijk zal het je inhalen.

Nu we weten dat begrijpen belangrijk is, rijst de volgende vraag: hoe? Hoe bouwen we dit menselijke begrip op terwijl we met AI werken en in een hoog tempo bewegen?

Het blijkt dat dit niet de eerste keer is dat er wordt nagedacht over hoe we begrip communiceren. Ik denk dat we inspiratie kunnen putten uit het onderwijs. Kunnen we de beste ideeën uit de pedagogiek stelen en toepassen op dit probleem?

Techniek 1: Uitleggingen

Ik wil drie technieken delen waarmee we dit kunnen aanpakken. De eerste is: uitleggingen. Wat maakt een uitleg goed?

Telkens wanneer een agent een taak voltooit, is dat een kans voor een uitleg — een artefact. In de meest naïeve vorm kunnen we een code diff lezen: het ruwe materiaal dat is gewijzigd. Maar wat als we onszelf afvragen: wat zou de best mogelijke uitleg zijn? Als je een team had — menselijk of AI — dat zich echt zou inspannen om iets goed aan je uit te leggen, hoe zou dat dan voelen?

Een antwoord hierop is een tool die ik heb gemaakt genaamd /explain-diff, die ik dagelijks gebruik en die ook waardevol is gebleken voor collega's. Deze tool genereert zorgvuldig gestructureerde code-uitleggen in HTML, Markdown of Notion-documenten. (Disclaimer: ik werk bij Notion, dus ik ben bevooroordeeld).

Laten we kijken naar de opbouw van zo'n uitleg, aan de hand van een voorbeeld waarbij het perspectief van een videogame wordt aangepast:

1. Eerst het basisprincipe: leer me achtergrondinformatie. Voordat we naar de wijzigingen kijken, moet ik begrijpen wat er al was. In dit geval: uitleg over de game engine.
2. Intuïtie vóór details. Voordat er code aan te pas komt, wordt het doel gesteld — "maak de tuin driedimensionaal met 2D-tekentrucs" — en worden gerelateerde concepten uitgelegd, zoals wat isometrische projectie precies is.

Dit alles bouwt mijn intuïtie op voor de essentie van de wijziging. Het brengt mij als mens bijsturen, zodat ik een gelijkwaardige deelnemer kan zijn in het begrip. Je kunt intuïtie ook opbouwen met interactieve figuren. Zo kon ik isometrisch perspectief begrijpen door stenen in de tuin te verslepen en te zien hoe hun coördinaten bewogen (mogelijk gemaakt door een functie van Notion om interactieve HTML in pagina's in te sluiten).

Uiteindelijk komen we bij de code. Een typische diff is vaak een stapel bestanden die op alfabetische volgorde zijn bewerkt, zonder uitleg. Wat ik een "literate diff" noem, is gestructureerd als proza: het loopt door de wijzigingen in een logische volgorde, met omringende uitleg en ingebedde codefragmenten. Dit is sneller te reviewen dan een ruwe diff.

Het resultaat is een compleet uitlegpakket. Ik lees nog steeds de code diff, maar ik lees altijd eerst dit pakket. Soms print ik deze uit en neem ik ze mee naar een café, omdat dat minder afleidt. Het is prachtig ironisch: AI verandert een interactieve activiteit in een statisch papieren rapport waar ik me diep op kan concentreren.

Er is echter één probleem: lezen is hard werken. Zoals Andy Matuschak zegt: "boeken werken niet"! Het is te makkelijk om jezelf voor te liegen dat je de stof hebt gelezen, terwijl je de informatie in werkelijkheid niet hebt onthouden of begrepen.

Hoe lossen we dit op? Ik liet me inspireren door het werk van Andy Matuschak en Michael Nielsen over het inbedden van spaced repetition-quizzen in essays. Ik doe nu iets soortgelijks met mijn code-uitleggen. Onderaan elke uitleg staat een interactieve quiz met vijf vragen over de wijziging.

Mijn regel is: ik verstuur geen code naar anderen totdat ik de quiz kan halen, en hetzelfde doe ik bij het reviewen van andermans code. Een quiz werkt als een snelheidsregelaar. Bij het werken met AI is het makkelijk dat de loop sneller draait dan de snelheid van menselijk begrip. De quiz is een tegenkracht: ik vraag me mechanisch af "begrijp ik dit echt?", zodat ik een volledige creatieve deelnemer kan blijven.

Techniek 2: Micro-werelden

Het tweede idee zijn micro-werelden, geïnspireerd door de visionaire pedagoog Seymour Papert. Papert had het prachtige idee van het "leven in Mathland": als je wiskunde wilt leren, moet je in Mathland gaan wonen — net zoals je naar Frankrijk gaat als je Frans wilt leren. Hij vroeg zich af of we een omgeving konden bouwen waarin kinderen wiskunde op natuurlijke wijze leerden als gevolg van hun nieuwsgierigheid.

Hoe passen we dat toe op code? Kunnen we werelden bouwen die we bewonen, waardoor we intuïtief begrijpen hoe het systeem werkt en hoe het verandert?

Vorig jaar werkte ik aan een Prolog-interpreter en had ik moeite om te intuïteren wat er binnenin gebeurde. Samen met een agent bouwde ik een debugger waarmee ik door de uitvoering van mijn logische taal kon stappen: terugspoelen in de tijd, zien wat er op de stack stond en welke regels bij elke stap werden geëvalueerd. Ik kon zelfs opmerkingen voor mezelf achterlaten ("mooi, die regel is correct toegepast").

Er is een groot verschil tussen het maken van een tool om te debuggen en de agent laten debuggen; door het zelf te doen, ontwikkel ik gaandeweg mijn begrip.

Een ander voorbeeld: ik migreerde mijn persoonlijke website naar een ander framework en Claude schreef daar een script voor. Het was echter erg moeilijk om te reviewen omdat ik niet bekend was met het nieuwe framework; ik kon alleen maar zeggen "ik gok dat het ongeveer klopt".

Dus vroeg ik Claude om een videogame voor me te maken: een commandocentrum waarin ik de migratie zelf stap voor stap uitvoerde, terwijl ik de zichtbare effecten en de evolutie van de mappenstructuur zag. Er ontstond een interface waarin ik op knoppen klikte om de port stap voor stap uit te voeren, met mijn oude site en nieuwe site naast elkaar.

In dit commandocentrum zag ik de nieuwe site incrementeel tot leven komen. Hierdoor kreeg ik hetzelfde begrip als wanneer ik het handmatig had gedaan, maar dan veel sneller omdat de hele ervaring voor mij was uitgezet. Het punt is dat agents stukjes code kunnen schrijven die ons als mensen helpen om andere code te begrijpen. Dit is een cruciale ontwikkeling.

Techniek 3: Gedeelde ruimtes

De laatste techniek: gedeelde ruimtes. Tot nu toe ging dit over individueel begrip, maar wanneer je in een team werkt, moet je samen begrijpen. Wanneer jij en iemand anders hetzelfde mentale model delen, kun je efficiënt communiceren. Je hebt een gedeeld vocabulaire dat dezelfde beelden oproept, waardoor je creatief kunt sparren. Zonder die gedeelde structuren zijn die gesprekken veel moeilijker.

Ik ben erg enthousiast over het creëren van gedeelde omgevingen waar teams dat begrip samen opbouwen. Dat is in essentie ook waar Notion om draait. Recentelijk hebben we bij Notion veel nieuwe functies geïmplementeerd zodat mensen en agents samen kunnen werken, waardoor het hele team een gedeeld begrip ontwikkelt in plaats van dat iedereen in een silo werkt.

Een klein voorbeeld: je kunt nu Claude- en Cursor-agents direct in Notion draaien. Ik doe veel van mijn programmeren nu op die manier. Wanneer deze agents een technisch plan maken in Notion, gebeurt dit standaard op een collaboratieve pagina. Hierdoor kan ik het onmiddellijk met mijn team bespreken en becommentariëren. Samen denken, niet alleen.

Augmenteren in plaats van automatiseren

Laten we afronden. We hebben technieken besproken voor het begrijpen van code, maar eigenlijk is dit een veel breder probleem. Het blijft belangrijk voor mensen om in het algemeen te begrijpen hoe dingen werken — niet alleen om te verifiëren, maar om te participeren.

En verrassend genoeg is dit geen nieuw idee. Het gaat terug naar de oorsprong van de informatica. Vijftig jaar geleden voorzag Alan Kay dat computers een nieuw medium konden zijn, beter dan het boek, om mensen (vooral kinderen) te leren hoe ze over de wereld moeten nadenken.

In die visie zag je kinderen geen YouTube-filmpjes kijken op een iPad; ze speelden een interactief spel en pasten de code aan terwijl ze speelden om een beter begrip van natuurkunde te krijgen. Dit was vijftig jaar geleden!

Het doel was altijd om te augmenteren (aanvullen/versterken), niet alleen om te automatiseren. Het is prachtig dat AI het creëren van simulaties nu zo toegankelijk maakt. AI die ons onderwijst, is een van de grootste mogelijkheden die computing ooit heeft geopend.

Dit maakt me zeer optimistisch over de toekomst. Als we de juiste tools bouwen, kunnen we de wereld nu beter begrijpen dan ooit tevoren. We hoeven onszelf niet simpelweg uit de loop te halen; we kunnen juist dieper in de loop stappen. Dat is aan ons.