AI-codedocumentatie

Wat is AI-codedocumentatie?

AI-codedocumentatie is de praktijk van documentatie genereren en onderhouden, inclusief commentaar, READMEs, API-referenties, en architectuurnotities, met AI-modellen die de broncode direct lezen. Omdat de documentatie afgeleid is van de code zelf, kan hij opnieuw gegenereerd worden telkens wanneer de code verandert, wat het oudste probleem in documentatie aanpakt: drift tussen wat de documentatie zegt en wat de code doet. Developers hebben dit sneller omarmd dan bijna elk ander AI-gebruik: in het Stack Overflow Developer Survey van 2025 zei 30,8% AI meestal te gebruiken voor het documenteren van code en gebruikt nog eens 30,3% het gedeeltelijk [1].

De belangrijkste punten

• De duurzame winst is versheid, geen eerste versies. Iedereen kan één keer een README schrijven; hem waar houden na tweehonderd merges is wat AI-regeneratie daadwerkelijk oplost.
• AI kan documenteren wat code doet maar nooit waarom hij zo geschreven is. Intentie die nergens is vastgelegd, kan niet uit de bron worden teruggehaald.
• Documentatie wordt nu voor twee doelgroepen geschreven: mensen, en coding-agents die bestanden zoals AGENTS.md of CLAUDE.md lezen om te leren hoe een project werkt.
• Gegenereerde documentatie heeft review nodig zoals gegenereerde code, want een zelfverzekerde foute uitleg is erger dan geen uitleg.

Hoe het werkt

Op de kleinste schaal leest een model een functie en produceert een docstring: parameters, returnwaarden, foutgevallen, een gebruiksvoorbeeld. Op moduleschaal vat het verantwoordelijkheden samen en hoe onderdelen verbonden zijn. Op repositoryschaal kan een agent door de boom lopen en een README, een architectuuroverzicht, of een onboardinggids produceren, en voor publieke interfaces kan hij API-referenties genereren uit route-definities en typesignaturen. De mechaniek is eenvoudig omdat broncode precies het soort dichte, gestructureerde tekst is dat taalmodellen goed lezen.

Het interessante engineeringwerk zit in de onderhoudslus. Teams bedraden documentatiechecks in CI: wanneer een pull request een module aanraakt, vergelijkt een agent de diff met de documentatie die eraan refereert, signaleert tegenstrijdigheden, en stelt updates voor die meerijden in dezelfde PR of als vervolgstap landen voor review. Documentatie stopt een artefact te zijn dat iemand in maart schreef en wordt een output die continu wordt afgestemd op de code, op dezelfde manier waarop gegenereerde tests worden afgestemd op gedrag. De winst komt terug in de data: het DORA-rapport van 2024 vond dat een stijging van 25% in AI-adoptie samenhing met een stijging van 7,5% in documentatiekwaliteit, de grootste kwaliteitswinst van AI die DORA mat [2].

Er is ook een nieuwer publiek. Agent-instructiebestanden zoals AGENTS.md en CLAUDE.md zijn documentatie waarvan de lezer een machine is: buildcommando's, conventies, verboden mappen, deploystappen. Deze bestanden schrijven en snoeien is documentatiewerk met een directe feedbacklus, want een coding-agent met een accuraat instructiebestand maakt minder verkeerde zetten, en een die verouderde instructies leest, herhaalt zelfverzekerd de fouten van vorig kwartaal.

Voorbeeld

Een platformteam erft een monorepo met 60 services waarvan de helft van de service-READMEs dateert van vóór een grote frameworkmigratie. Ze draaien een agent over elke service met dezelfde opdracht: verifieer elke README-bewering tegen de huidige code, corrigeer wat fout is, signaleer wat niet te verifiëren is, en voeg een standaardsectie voor draaien-en-testen toe. De agent opent 41 pull requests over twee dagen. Reviewers wijzen er zes af wegens subtiele onnauwkeurigheden, mergen de rest, en het team voegt een CI-job toe die de check opnieuw draait op elke PR die het publieke oppervlak van een service aanraakt. Vragen van nieuwe medewerkers in het teamkanaal dalen merkbaar de maand erna, en de READMEs stoppen iets te zijn dat niemand vertrouwt.

Veelvoorkomende misvattingen

De misvatting is geloven dat AI de documentatiekloof volledig sluit. Hij sluit de mechanische helft. De waardevolle helft van documentatie is intentie: waarom de betalingsretry jitter gebruikt, waarom het team hier voor eventual consistency koos, welk alternatief werd geprobeerd en verlaten. Niets daarvan leeft in de bron, dus geen enkel model kan het extraheren, en een agent die gevraagd wordt zulke code uit te leggen, produceert een vlotte beschrijving van het wat terwijl hij stilzwijgend het waarom weglaat. Erger nog, gegenereerde documentatie kan zelfverzekerd fout zijn over afgeleid doel, en lezers geven gepolijst proza meer vertrouwen dan het verdiend heeft, een kleine dosis automation bias toegepast op paragrafen in plaats van code. Mensen zijn de codebase nog steeds hun besluitvormingsgeschiedenis verschuldigd.

FAQ

Moet door AI gegenereerde documentatie gereviewd worden voor het mergen? Ja, met dezelfde poort als gegenereerde code. Verifieer feitelijke beweringen tegen de bron, en controleer of afgeleide verklaringen van doel daadwerkelijk waar zijn in plaats van aannemelijk. Foute documentatie misleidt elke toekomstige lezer, mens en agent gelijk.

Wat is het verschil tussen code documenteren met AI en documentatie schrijven voor AI? Richting. De eerste gebruikt een model om code aan mensen uit te leggen. De tweede, bestanden zoals AGENTS.md, legt het project uit aan coding-agents zodat ze er correct in werken. Gezonde teams onderhouden in 2026 beide, en de tweede betaalt zich elke agentsessie opnieuw uit.

Vervangt AI-documentatie technisch schrijvers? Voor referentiemateriaal dat de code weerspiegelt, grotendeels ja. Voor tutorials, conceptuele gidsen, en besluitvormingsgeschiedenis, nee, want die vereisen de lezer kennen en de geschiedenis kennen, en geen van beide staat in de repository.

Bronnen

1. Stack Overflow Developer Survey. "30,8% van de developers gebruikt AI meestal voor het documenteren van code en nog eens 30,3% gebruikt het gedeeltelijk." https://survey.stackoverflow.co/2025/ai. Geraadpleegd augustus 2026.
2. Google Cloud DORA. "Een stijging van 25% in AI-adoptie hing samen met een stijging van 7,5% in documentatiekwaliteit, de grootste aan AI gekoppelde kwaliteitswinst die DORA mat." https://cloud.google.com/blog/products/devops-sre/announcing-the-2024-dora-report. Geraadpleegd augustus 2026.