Bij te veel (AI)-tekst haakt de mens af en wordt je agent dommer

Sinds AI meeschrijft, groeit elke doc, elk ticket en elke overdracht, en haakt je lezer na drie alinea’s af.

In het kort

• Langere teksten en dus te veel context maken (AI)-modellen aantoonbaar slechter, en mensen haken nog eerder af.
• Schrijf in twee lagen: bovenaan het doel voor de mens, daaronder de feiten voor de agent en de nieuwsgierige lezer.
• Schrap opvulling, herhaling en beleefdheidsfrases. Hou het kort en bondig.
• Voeg diagrammen toe aan je tekst, liefst met tekst of Mermaid. Een diagram zegt meer dan duizend woorden.

Ook voor een (AI)-model is langer slechter

Een AI-agent leest alles, dus geef je het alles. Chroma liet in hun onderzoek naar context rot zien dat achttien (AI)-modellen slechter presteren naarmate de input of tekst langer wordt.

Onderzoekers van Stanford vonden eerder al iets vergelijkbaars. In Lost in the Middle gebruikten modellen informatie aan het begin en het eind van de context goed, en informatie in het midden een stuk slechter. Een beslissing halverwege een ticket van twee pagina’s vindt je agent dus net zo slecht als je collega.

Anthropic noemt context daarom een eindige hulpbron met afnemende meeropbrengst: elk overbodig token kost aandacht.

Mijn ervaring is dat een mens bij lange, mede door AI gegenereerde teksten afhaakt. Wie een overdracht van drie pagina’s krijgt, scant, mist de kern en vraagt je morgen om het persoonlijk toe te lichten.

Schrijf in lagen en hou het kort

Schrap opvulling, herhaling en beleefdheidsfrases: je model heeft er niets aan, en je collega ook niet. Feiten schrap je niet, want de agent heeft ze nodig en sommige collega’s willen ze ook. Die zet je in een tweede laag.

De eerste laag volgt BLUF: bottom line up front. Wat is het doel, wat is er besloten, wat moet er gebeuren. Een mens die na drie zinnen stopt, weet genoeg, en een agent weet meteen waar het over gaat.

De tweede laag bevat de feiten, bijvoorbeeld: hoe je het reproduceert, de oorzaak, de afwegingen. Daar mag het volledig zijn, want wie hier leest, heeft ervoor gekozen. Probeer het zelf:

Doel: uitloggen op iOS moet de sessie echt wissen. Nu ben je na een herstart weer ingelogd. De fix zit in SessionStore, er is geen migratie nodig.

Details

• Reproduceren: inloggen, uitloggen, de app geforceerd sluiten en opnieuw openen.
• Oorzaak: het token staat in de Keychain, en logout() wist alleen de sessie in het geheugen.
• Fix: SessionStore.clear() verwijdert ook het Keychain-item.
• Risico: klein. Wie nu ingelogd is, blijft dat; alleen uitloggen verandert.
• Buiten scope: Android, daar wist uitloggen het token al.

Wat niet in het document past, link je: het ADR, de logs, de specificatie. Anthropic noemt dit context engineering. Een agent houdt lichte verwijzingen vast, zoals bestandspaden en links, en laadt de inhoud pas als hij die nodig heeft.

Agent Skills werken precies zo. Een agent ziet eerst alleen de naam en beschrijving van een skill. De instructies leest hij pas als de skill relevant is, en extra bestanden alleen als de taak erom vraagt. Dat heet progressive disclosure, en zo richt je bijvoorbeeld ook een goede wiki in. Progressive disclosure kun je dus ook voor de mens toepassen.

Elk teksttype heeft een kern en een laag eronder

• Docs: de eerste alinea zegt wat het systeem doet en voor wie; architectuur, keuzes en randgevallen staan op gelinkte pagina’s.
• Tickets: het gewenste gedrag en de acceptatiecriteria bovenaan; logs, screenshots en achtergrond eronder.
• Overdrachten: begin met de status en wat er nu moet gebeuren; de geschiedenis staat in de commits en het ticket.
• PR’s: de titel zegt wat er verandert, de eerste regel waarom; het hoe staat in de diff, dus beschrijf je het niet nog een keer. Wel zet je bovenaan waar de reviewer op moet letten.
• Meetingnotes: besluiten en acties met een eigenaar bovenaan; de discussie eronder, voor wie wil weten hoe jullie daar kwamen.

Laat je AI deze teksten schrijven? Geef die structuur dan mee in je prompt of in een skill. Anders vult een model maar al te graag aan, soms tot het onleesbaar wordt voor je collega.

Een diagram liefst in tekst

Bij visuals lopen mens en agent het vaakst uit elkaar. Een foto van het whiteboard of een export uit een tekentool zegt je collega iets. Je agent kan het plaatje ook lezen, maar dat kost veel meer tokens dan tekst, en een plaatje is lastig bij te werken als de code verandert.

Mermaid lost dat op, als je in Markdown schrijft en je tool het ondersteunt. Je schrijft het diagram als tekst, tools als GitHub, GitLab en Notion tekenen het voor je lezer, en je agent leest de bron:

flowchart LR
    Bron[Markdown in git] --> Docs[Gerenderde docs]
    Bron --> Agent[AI-agent]
    Bron --> Demo[HTML-animatie]

Een HTML-animatie of interactieve view mag ook, zolang je die behandelt als view op de tekstbron en nooit als de bron zelf. Het diagram hierboven is er een voorbeeld van. Met AI kun je voor de mens interactieve elementen toevoegen, zodat je punt nog beter overkomt. Hou er wel rekening mee dat alleen AI het onderhoud zal doen: voor een mens is het echt te veel werk.

Wat niemand mist, kan weg

Kun je een zin schrappen zonder dat je collega of je agent iets mist? Weg ermee. En hou het beknopt, zonder fluff.

Bronnen

• Kelly Hong, Anton Troynikov en Jeff Huber (Chroma), Context Rot: How Increasing Input Tokens Impacts LLM Performance, juli 2025.
• Nelson F. Liu e.a. (Stanford), Lost in the Middle: How Language Models Use Long Contexts, 2023.
• Anthropic, Effective context engineering for AI agents, september 2025.
• Anthropic, Equipping agents for the real world with Agent Skills, oktober 2025.
• Matt Ström-Awn, Bottom Line Up Front.
• Mermaid, diagrammen als tekst.