Waarom Documentatie Verandert in een On Controleerbare Chaos

Stel je voor: je begint aan een nieuw project met een leeg CLAUDE.md-bestand. Een paar handige tips. Een notitie over de context. Een waarschuwing voor dat ene gekke randgeval in je authenticatiestroom. Maanden later open je het bestand en het is veranderd in een roman vol tegenstrijdige instructies, achterhaalde herinneringen en wanhopige bijlagen waar niemand meer wijs uit wordt.

Dit overkomt niet alleen jou. Het overkomt iedereen.

Onderzoek naar 247.694 instructies in 1.867 repositories toont een opvallend patroon: instructies voor AI-assistenten groeien niet alleen — ze groeien eindeloos door, meer dan verdrievoudigd (+226%) over hun levensduur. Gemiddeld komen er +4,9 netto instructies bij met elke commit. Het bestand krimpt nooit. Het wordt alleen groter.

Maar hier wordt het echt interessant: hoe ouder een instructie wordt, hoe kleiner de kans dat iemand hem verwijdert. De data laat een log-hazard van -0,032 per commit zien. Instructies worden dus steeds onsterfelijker naarmate ze langer blijven staan. Het is niet zo dat niemand wil opruimen — niemand durft het risico te nemen om iets weg te halen.

Het Wiskundige Probleem

Waarom gebeurt dit? Onderzoekers noemen het "catastrophal remembering" — het tegenovergestelde van het bekende "catastrophic forgetting" probleem in machine learning. Maar je hebt geen PhD nodig om te begrijpen waarom het zo'n propbleem is.

Denk aan de kosten: een nieuwe instructie toevoegen is goedkoop. Je ziet een probleem, je schrijft een oplossing, je gaat door. De directe kosten zijn laag en het voordeel is direct duidelijk.

Maar een instructie verwijderen? Dat is een ander verhaal. Je moet begrijpen waar die instructie allemaal toe doet. Je moet nadenken over interacties met alle andere instructies. Je moet verifiëren dat verwijderen niets subtiels en belangrijks breekt. Onderzoekers berekenden deze cognitieve kost als O(2^|D|) — exponentieel groeiend met het aantal bestaande instructies.

Dus ontwikkelaars doen wat rationele mensen doen: ze stoppen met proberen. Nieuwe instructies worden toegevoegd. Oude blijven staan. Het bestand groeit.

Commentaar: De Onderschatte Held

Hier wordt het onderzoek echt spannend. De oplossing zit niet in betere prompting-technieken of slimmere modellen. Het zit in iets wat ontwikkelaars al gebruiken sinds het begin van het programmeren: commentaar.

De onderzoekers namen een slimme aanpak — ze keerden IFEval, een standaard benchmark, om tot "verifieerbare werelden" waar de optimale prompts bekend zijn. Toen ze commentaar met latente redenering toevoegden aan prompts, daalde de overmatige instructiegroei van +211,3% naar slechts +1,4%.

Dat is een reductie van 99,3%.

Maar het echte做不到? Dit commentaar controleerde niet alleen de groei — het verbeterde ook de daadwerkelijke instructie-opvolging met tot 23,1% bij echte taken. Commentaar is dus geen organisatorische rommel. Het zijn dragende structuren die AI-assistenten helpen om context correct te begrijpen.

Waarom Dit Nu Belangrijk Is

We leven in een fundamentele verschuiving in wat "code" betekent. De onderzoekers stellen een prikkelende vraag: "Als Engels de nieuwe code is, waarom hebben we dan nog geen commentaar?"

Het is een eerlijk punt. Ontwikkelaars begrijpen al decennia dat code zonder commentaar technische schuld is. Commentaar legt het "waarom" uit, niet alleen het "wat". Het vangt intentie, randgevallen en bedrijfskennis die je niet kunt afleiden uit syntaxis alleen.

Toch hebben we, in onze haast om steeds meer over te laten aan AI coding assistants, natuurlijke-taalinstructies behandeld alsof ze anders waren. We schrijven gebiedende wijzen — doe dit, doe dat niet, onthoud X te controleren — zonder onze redenering uit te leggen.

Het resultaat zien we in die uitdijende CLAUDE.md-bestanden: instructies die niemand volledig begrijpt, die mogelijk met elkaar conflicteren, en die groeien zonder enig mechanisme voor rationalisatie.

De Weg Vooruit

Als je een CLAUDE.md of vergelijkbaar agentic-promptbestand onderhoudt, hier is wat het onderzoek suggereert:

1. Voeg commentaar toe bij je instructies, niet alleen bij je code. Leg uit waarom een regel bestaat. Documenteer randgevallen. Vang de redenering achter beslissingen.

2. Omarm periodieke rationalisatie. Niet alleen toevoegen — herschrijven. Het onderzoek merkt op dat volledige herschrijvingen een van de weinige dingen zijn die de groei stoppen.

3. Behandel je AI-instructies zoals onboarding-documentatie. Zou je een nieuwe ontwikkelaar een 400-regel bestand met ongedifferentieerde regels geven? Je AI-assistent verdient dezelfde helderheid.

De koers waar we op zitten is niet houdbaar. Elk nieuw project begint met goede bedoelingen en eindigt in een onbeheersbare rommel. Maar de oplossing is misschien simpeler dan we dachten: schrijf voor de mens (of AI) die je instructies over zes maanden leest, niet alleen voor degene die vandaag je vraag beantwoordt.

Commentaar is geen rommel. Het is de architectuur van begrip.