Documentatie bij AI-ondersteunde ontwikkeling

Documentatie wordt contextinfrastructuur: het gedeelde geheugen en verificatievlak waarmee mensen en AI-agents coherente systemen bouwen.

Van projectartefact naar contextinfrastructuur

Inleiding

Nu AI-ondersteunde ontwikkeling gangbaarder wordt, draaien veel discussies nog altijd om prompts. Een goede prompt kan richting geven, dubbelzinnigheid verminderen en betere output opleveren. In echte softwareprojecten is de kwaliteit van de prompt echter maar een deel van het verhaal.

De doorslaggevende factor is context.

AI-systemen presteren beter wanneer ze toegang hebben tot duidelijke architectuur, precieze terminologie, implementatiebeperkingen, acceptatiecriteria, voorbeelden en verificatiemechanismen. Documentatie is niet langer alleen een passief artefact dat na het echte werk wordt gemaakt. Ze wordt onderdeel van het opleveringsmechanisme zelf.

Documentatie evolueert van projectgeheugen naar contextinfrastructuur.

Van prompt engineering naar context engineering

Softwareoplevering hangt minder af van één slim geformuleerde prompt en meer van de kwaliteit van de informatieomgeving rond het model.

Context engineering is het doelbewust ontwerpen van welke informatie het model ontvangt, wanneer het die ontvangt en in welk formaat.

Een goede prompt kan ontbrekende architectuur, onduidelijke vereisten, inconsistente woordenschat of ontbrekende validatiecriteria niet compenseren. Correctheid ontstaat uit beperkingen, interfaces, verantwoordelijkheden, afhankelijkheden en tests.

De nieuwe rol van documentatie

Documentatie fungeert nu als projectgeheugen, legt bedrijfsdoelen vast, definieert architectuurgrenzen, verduidelijkt de interactie tussen componenten, bewaart domeintaal en verklaart waarom beslissingen werden genomen.

Zo vormt documentatie een brug tussen bedrijfsdoel, architectuur en ontwerp, implementatie en verificatie.

Documentatie vóór implementatie

Een doeltreffend patroon is om vóór de codegeneratie minimale maar waardevolle artefacten voor te bereiden: implementatieplannen, architectuurnotities, interfacecontracten, domeinregels, acceptatiecriteria, testscenario's en deploymentbeperkingen.

Daar functioneert documentatie als engineeringmaatregel in plaats van als projectversiering.

Tests als uitvoerbare documentatie

Een test is niet alleen een kwaliteitscontrole. Het is ook een precieze gedragsverklaring. Een test beschrijft wat het systeem moet doen in een vorm die automatisch kan worden geverifieerd.

Tests zetten vereisten om in observeerbaar gedrag en leggen tegenstrijdigheden bloot tussen wat het team zegt te willen en wat het systeem geacht wordt te doen.

Waarom het formaat belangrijk is

Het documentatieformaat wordt een engineeringbeslissing. Het beste formaat bewaart betekenis, vermindert dubbelzinnigheid en is eenvoudig te gebruiken, bij te werken, terug te vinden en om te zetten in bruikbare context.

Markdown, Mermaid-diagrammen, OpenAPI, JSON Schema, YAML-configuratie en contractdefinities zijn krachtig omdat ze overdraagbaar zijn en interpretatie begrenzen.

flowchart TD
    Intent[Bedrijfsdoel] --> Context[Contextartefacten]
    Context --> Team[Deliveryteam]
    Context --> Assistant[AI-assistent]
    Assistant --> Change[Gegenereerde wijziging]
    Change --> Verification[Tests en beoordeling]
    Team --> Verification

Risico's en faalwijzen

Meer documentatie levert niet automatisch betere resultaten op. Verouderde documenten kunnen achterhaalde aannames introduceren. Dubbele bronnen kunnen onzekerheid creëren. Mooie diagrammen kunnen vals vertrouwen wekken.

De kwaliteit van documentatie is belangrijker dan de hoeveelheid. De nuttigste documentatie is actueel, afgebakend, expliciet, dicht bij de implementatierealiteit en afgestemd op verificatie.

Conclusie

AI-ondersteunde ontwikkeling wordt vaak als een promptprobleem beschreven, maar in echte deliveryomgevingen is context de belangrijkere factor.

Documentatie staat centraal in die context. Ze kan dienen als geheugen, afstemming, specificatie en ondersteuning voor verificatie. Ze is niet langer alleen een verslag van wat werd gebouwd. Steeds vaker maakt ze deel uit van hoe software wordt gebouwd.