Documentatie als code: technische documentatie gesynchroniseerd met versies
Hoe praktijken voor documentatie als code helpen om technische documentatie voor de AI Act bij elke codewijziging actueel te houden.
Belangrijkste inzichten
- 1.Aanbieders van hoogrisico-AI-systemen moeten de technische documentatie actueel houden (artikel 11, lid 1).
- 2.Documentatie als code houdt de technische documentatie in versiebeheer naast de code.
- 3.Delen kunnen worden gegenereerd uit code en pijplijngegevens. Beslissingen die beoordeling vragen, vragen om mensen.
- 4.Versiebeheer toont wat er wanneer is gewijzigd, niet dat de inhoud juist is.
De plicht geldt voor aanbieders die hoogrisico-AI-systemen in de EU in de handel brengen of er in gebruik stellen (artikel 2, lid 1, onder a). Bijlage IV noemt wat de documentatie moet bevatten. Bijlage III is de lijst van hoogrisicotoepassingen in de verordening, zoals werving en selectie. Bijlage I gaat over AI in producten onder Europese veiligheidswetgeving. Afdeling A van bijlage I somt productwetgeving op, zoals die voor speelgoed en medische hulpmiddelen. Afdeling B somt andere productwetgeving op. Voor systemen uit bijlage III geldt de plicht vanaf 2 december 2027. Voor systemen uit afdeling A van bijlage I geldt zij vanaf 2 augustus 2028 (Verordening (EU) 2026/1744). Systemen die vóór die data in de handel zijn gebracht of in gebruik zijn gesteld, vallen onder artikel 111, lid 2. Dat lid is vervangen bij Verordening (EU) 2026/1744. Behalve de systemen in artikel 111, lid 1, vallen ze er alleen onder als hun ontwerp vanaf de toepasselijke datum aanzienlijk wijzigt. Voor systemen die bedoeld zijn voor overheidsinstanties vereist artikel 111, lid 2, de nodige stappen om aan de regels te voldoen uiterlijk 2 augustus 2030.
Voor hoogrisico-AI-systemen die verband houden met producten uit afdeling B van bijlage I beperkt artikel 2, lid 2, welke bepalingen gelden. Alleen artikel 6, lid 1 (classificatieregels), artikel 60a (testen onder reële omstandigheden buiten testomgevingen) en de artikelen 102 tot en met 112 (slotbepalingen) gelden. De artikelen 57 tot en met 59 (AI-testomgevingen voor regelgeving) gelden alleen voor zover die productwetgeving de eisen van de verordening voor hoogrisico-AI-systemen heeft opgenomen. Artikel 11 staat daar niet bij.
De plichten van aanbieders staan in artikel 16. Een overtreding kan tot 15 miljoen EUR of, voor een onderneming, 3 % van de wereldwijde jaaromzet kosten (artikel 99, lid 4). Het hoogste bedrag geldt. Voor micro-, kleine en middelgrote ondernemingen (mkb, artikel 3, punt 14a) geldt het laagste bedrag (artikel 99, lid 6).
Bij documentatie als code worden wijzigingen beoordeeld in pull requests en is elke versie gekoppeld aan een release. Volgende stap: controleer met de tabel hieronder welke van de negen punten van bijlage IV u uit uw repository kunt genereren.
Waarom documenten buiten de repository achterlopen
Documenten in Word-bestanden, pdf’s of wiki’s staan los van de code die ze beschrijven.
Een document kan een oude versie beschrijven
Bijwerken is handwerk
Wat documentatie als code in de praktijk betekent
Documentatie als code past softwareengineering-praktijken toe op de technische documentatie:
Versiebeheer
De technische documentatie staat in dezelfde Git-repository als de code. Elke wijziging is een commit met auteur, datum en diff, zodat u een documentversie aan een codeversie kunt koppelen.
Genereren waar mogelijk
Sommige onderdelen kunnen uit de codebase worden gegenereerd, zoals de tabel hieronder laat zien. Onderdelen die beoordeling vragen, worden door mensen geschreven.
Controles in de pijplijn
Uw team kan een pijplijnregel schrijven die een pull request laat mislukken wanneer het model wijzigt maar het bijbehorende onderdeel van het document niet. De verordening vereist dit niet.
Release-bundels
Elke release bundelt de documenten met de softwareversie, zodat u de documentatie kunt opleveren die bij een bepaalde release hoorde.
Genereren helpt bij sommige punten van bijlage IV meer dan bij andere
Genereren helpt enigszins bij 4 van de 9 punten van bijlage IV, weinig bij 4 en helemaal niet bij 1. De twee rechterkolommen zijn onze eigen inschatting, niet die van de verordening.
Mkb en kleine midcap-ondernemingen (SMC’s, artikel 3, punt 14b) mogen de elementen van bijlage IV in vereenvoudigde vorm aanleveren. Dat volgt uit artikel 11, lid 1, zoals gewijzigd bij Verordening (EU) 2026/1744. Wie dat doet, moet het vereenvoudigde formulier gebruiken dat de Commissie moet opstellen. Het laagste boetebedrag geldt ook voor SMC’s (artikel 99, lid 6a).
| Punt van bijlage IV | Mogelijke aanpak | Genereren helpt |
|---|---|---|
| 1. Algemene beschrijving van het AI-systeem | Namen en versies uit het manifest, de README en de releasemetadata | Gedeeltelijk |
| 2. Elementen van het systeem en het ontwikkelproces | Architectuur- en pijplijnbeschrijvingen uit de code; ontwerpmotivering geschreven door mensen | Gedeeltelijk |
| 3. Monitoring, werking en controle | Nauwkeurigheidscijfers uit testresultaten; beperkingen en maatregelen voor menselijk toezicht geschreven door mensen | Gedeeltelijk |
| 4. Geschiktheid van de prestatiemaatstaven | Maatstaven uit evaluatiepijplijnen; het betoog dat ze passend zijn, wordt door mensen geschreven | Weinig |
| 5. Risicobeheersysteem (artikel 9) | Risicoregister als bestand met versies; de risicoanalyse wordt door mensen gedaan | Weinig |
| 6. Relevante wijzigingen tijdens de levenscyclus | De Git-geschiedenis en het changelog geven de ruwe lijst; de aanbieder selecteert de relevante wijzigingen | Gedeeltelijk |
| 7. Toegepaste normen | Een bijgehouden lijst in de repository | Weinig |
| 8. Kopie van de EU-conformiteitsverklaring | De ondertekende verklaring, bewaard bij de release | Geen |
| 9. Systeem voor monitoring na het in de handel brengen (artikel 72) | Het plan als document met versies; monitoringgegevens komen uit de operatie | Weinig |
Voorbeeldopzet: documentatiebestanden naast de code
Deze opzet is een voorbeeld, geen verplichte structuur.
your-ai-system/
├── src/
├── docs/
│ └── compliance/
│ ├── annex-iv/
│ │ ├── 01-general-description.md
│ │ ├── 02-development-process.md
│ │ └── ...
│ ├── risk-register.yaml
│ └── oversight.md
├── tests/
│ └── docs/
└── .github/
└── workflows/
└── docs-check.ymlEen pijplijn kan de documenten bij elke pull request controleren
Scannen: de codebase analyseren
Een scanstap kan een tool gebruiken die gangbare patronen van ML-frameworks in de code herkent. Eigen wrappers en verhulde code kunnen worden gemist.
Genereren: de concepten vernieuwen
De pijplijn bouwt gegenereerde onderdelen opnieuw op uit actuele invoer, zodat de diff toont wat er in de documenten is veranderd.
Valideren: de volledigheid controleren
Regels controleren of de vereiste onderdelen bestaan en de vereiste inhoud bevatten. Een inhoudscontrole is geen waarheidscontrole: mensen beoordelen de juistheid.
Rapporteren: het resultaat tonen bij de pull request
De pull request toont welke controles zijn geslaagd of mislukt, zodat een beoordelaar het effect op de documentatie ziet voordat de wijziging wordt samengevoegd.
Platte tekst maakt controle regel voor regel mogelijk, en branchebescherming bewaakt de geschiedenis
Pull requests tonen de gewijzigde regels
Bescherm de geschiedenis
Gerelateerde lectuur
Bronnen & referenties
- Regulation (EU) 2024/1689 (EU AI Act) — artikelen 2, 3, 11, 16, 43 en 99 en bijlagen I, III en IV (bijlage IV: negen punten van technische documentatie).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — toepassingsdata (artikel 113) en wijzigingen van artikel 2, lid 2, artikel 3, artikel 11, lid 1, artikel 99 en artikel 111, lid 2, en het nieuwe artikel 60a.
- GitHub Docs — About protected branches — regels voor branchebescherming bepalen of medewerkers een force push naar een branch mogen doen.
- Pro Git — Viewing the Commit History — de commitgeschiedenis toont elke commit met auteur, datum en bericht; met de patch-optie toont ze de diff.
Veelgestelde vragen
Wat is documentatie als code voor AI Act-documentatie?
Documentatie als code houdt de technische documentatie in versiebeheer, wijzigt haar via pull requests en genereert delen ervan in een pijplijn. Het doel is dat de technische documentatie overeenkomt met het systeem zoals het is uitgebracht.
Waarom lopen documenten buiten de repository achter?
Word-bestanden en pdf’s staan los van de code, dus een codewijziging werkt ze niet bij. Iemand moet ze bijwerken, want artikel 11, lid 1, vereist dat de technische documentatie actueel wordt gehouden.
Voldoet documentatie als code aan bijlage IV?
Geen enkele werkwijze voldoet op zichzelf aan bijlage IV. Bijlage IV bepaalt de inhoud in negen punten. Documentatie als code helpt die inhoud actueel en traceerbaar te houden. De aanbieder moet ervoor zorgen dat het systeem voldoet aan de eisen van hoofdstuk III, afdeling 2, waartoe artikel 11 behoort (artikel 16, onder a)).
Welke tools worden gebruikt voor documentatie als code?
U kunt Git, Markdown- of YAML-bestanden en een CI-pijplijn voor controles en generatie combineren. Een scanner of generator kan de onderdelen produceren die uit code zijn af te leiden.
Hoe vaak moet technische AI-documentatie worden bijgewerkt?
Artikel 11, lid 1, vereist dat de technische documentatie wordt opgesteld voordat het systeem in de handel wordt gebracht of in gebruik wordt gesteld, en actueel wordt gehouden. Artikel 11, lid 1, stelt geen vast interval. Onze suggestie is om haar bij elke release te beoordelen en na elke wijziging van het model, de trainingsgegevens of het beoogde doel. Een substantiële wijziging vereist een nieuwe conformiteitsbeoordeling (artikel 43, lid 4). Een substantiële wijziging is een verandering na het in de handel brengen of in gebruik stellen die de eerste conformiteitsbeoordeling niet had voorzien of gepland. Ze raakt de naleving van de eisen voor hoogrisico-AI-systemen in hoofdstuk III, afdeling 2, of wijzigt het beoogde doel (artikel 3, punt 23). Een conformiteitsbeoordeling is de procedure die aantoont of aan die eisen is voldaan (artikel 3, punt 20).
Scanara bereidt bewijs voor vanuit uw repositories
Scanara leest uw gekoppelde GitHub-repositories en voert regelgebaseerde scans uit op gangbare AI- en machine-learningpatronen. Niet-standaardcode kan het missen. Daarnaast genereert het conceptdocumentatie op basis van sjablonen en uw antwoorden in de beoordelingen, als bewijs voor uw compliancewerk. De indeling bepaalt u zelf.