Dokumentation als Code: versionssynchrone technische Dokumentation
Wie Dokumentation als Code hilft, die technische Dokumentation nach der KI-Verordnung bei jeder Codeänderung auf dem neuesten Stand zu halten.
Wichtigste Erkenntnisse
- 1.Anbieter von Hochrisiko-KI-Systemen müssen die technische Dokumentation auf dem neuesten Stand halten (Artikel 11 Absatz 1).
- 2.Dokumentation als Code hält die technische Dokumentation in der Versionskontrolle neben dem Code.
- 3.Teile lassen sich aus Code und Pipeline-Daten erzeugen. Ermessensentscheidungen brauchen Menschen.
- 4.Die Versionskontrolle zeigt, was sich wann geändert hat, nicht, ob der Inhalt richtig ist.
Die Pflicht gilt für Anbieter, die Hochrisiko-KI-Systeme in der EU in Verkehr bringen oder dort in Betrieb nehmen (Artikel 2 Absatz 1 Buchstabe a). Anhang IV listet auf, was die Dokumentation enthalten muss. Anhang III ist die Liste der Hochrisiko-Einsatzbereiche in der Verordnung, etwa Personalauswahl. Anhang I betrifft KI in Produkten, für die EU-Sicherheitsvorschriften gelten. Abschnitt A von Anhang I listet Produktvorschriften auf, etwa zu Spielzeug und Medizinprodukten. Abschnitt B listet andere Produktvorschriften auf. Für Systeme nach Anhang III gilt die Pflicht ab dem 2. Dezember 2027. Für Systeme nach Abschnitt A von Anhang I gilt sie ab dem 2. August 2028 (Verordnung (EU) 2026/1744). Für Systeme, die vor diesen Daten in Verkehr gebracht oder in Betrieb genommen wurden, gilt Artikel 111 Absatz 2. Er wurde durch die Verordnung (EU) 2026/1744 ersetzt. Abgesehen von den Systemen in Artikel 111 Absatz 1 gilt die Verordnung für sie nur, wenn ihre Konzeption ab dem maßgeblichen Datum erheblich geändert wird. Für Systeme zur Verwendung durch Behörden verlangt Artikel 111 Absatz 2 die notwendigen Schritte zur Einhaltung bis zum 2. August 2030.
Für Hochrisiko-KI-Systeme in Produkten nach Abschnitt B von Anhang I begrenzt Artikel 2 Absatz 2, welche Bestimmungen gelten. Es gelten nur Artikel 6 Absatz 1 (Einstufungsvorschriften), Artikel 60a (Tests unter Realbedingungen außerhalb von Reallaboren) und die Artikel 102 bis 112 (Schlussbestimmungen). Die Artikel 57 bis 59 (KI-Reallabore) gelten nur, soweit diese Produktvorschriften die Anforderungen der Verordnung an Hochrisiko-KI-Systeme integriert haben. Artikel 11 steht dort nicht.
Die Anbieterpflichten stehen in Artikel 16. Nach Artikel 99 Absatz 4 kann ein Verstoß bis zu 15 Millionen EUR oder, bei einem Unternehmen, bis zu 3 % des weltweiten Jahresumsatzes kosten. Es gilt der höhere Betrag. Für Kleinstunternehmen sowie kleine und mittlere Unternehmen (KMU, Artikel 3 Nummer 14a) gilt der niedrigere Betrag (Artikel 99 Absatz 6).
Bei Dokumentation als Code werden Änderungen in Pull Requests geprüft, und jede Version ist mit einem Release verknüpft. Nächster Schritt: Prüfen Sie anhand der Tabelle unten, welche der neun Punkte von Anhang IV sich aus Ihrem Repository erzeugen lassen.
Warum Dokumente außerhalb des Repositorys auseinanderlaufen
Dokumente in Word-Dateien, PDFs oder Wikis sind vom Code getrennt, den sie beschreiben.
Ein Dokument kann eine alte Version beschreiben
Aktualisieren ist Handarbeit
Was Dokumentation als Code in der Praxis bedeutet
Dokumentation als Code wendet Methoden der Softwareentwicklung auf die technische Dokumentation an:
Versionskontrolle
Die technische Dokumentation liegt im selben Git-Repository wie der Code. Jede Änderung ist ein Commit mit Autor, Datum und Diff, sodass Sie eine Dokumentversion einer Codeversion zuordnen können.
Erzeugung, wo möglich
Manche Abschnitte lassen sich aus der Codebasis erzeugen, wie die Tabelle unten zeigt. Abschnitte, die Ermessen erfordern, schreiben Menschen.
Prüfungen in der Pipeline
Ihr Team kann eine Pipeline-Regel schreiben, die einen Pull Request fehlschlagen lässt, wenn sich das Modell ändert, der passende Abschnitt des Dokuments aber nicht. Die Verordnung schreibt das nicht vor.
Release-Pakete
Jedes Release bündelt die Dokumente mit der Softwareversion, sodass Sie die Dokumentation erzeugen können, die zu einem bestimmten Release gehörte.
Die Erzeugung hilft bei manchen Punkten von Anhang IV mehr als bei anderen
Die Erzeugung hilft bei 4 der 9 Punkte von Anhang IV etwas, bei 4 wenig und bei 1 gar nicht. Die beiden rechten Spalten sind unsere Einschätzung, nicht die der Verordnung.
KMU und kleine Midcap-Unternehmen (SMC, Artikel 3 Nummer 14b) dürfen die Angaben nach Anhang IV vereinfacht machen. Das folgt aus Artikel 11 Absatz 1 in der Fassung der Verordnung (EU) 2026/1744. Wer das tut, muss das vereinfachte Formular verwenden, das die Kommission erstellen soll. Der niedrigere Bußgeldbetrag gilt auch für SMC (Artikel 99 Absatz 6a).
| Punkt von Anhang IV | Möglicher Ansatz | Erzeugung hilft |
|---|---|---|
| 1. Allgemeine Beschreibung des KI-Systems | Namen und Versionen aus Manifest, README und Release-Metadaten | Teilweise |
| 2. Elemente des Systems und sein Entwicklungsprozess | Architektur- und Pipeline-Beschreibungen aus dem Code; Begründung des Designs von Menschen geschrieben | Teilweise |
| 3. Überwachung, Funktionsweise und Kontrolle | Genauigkeitswerte aus Testergebnissen; Einschränkungen und Maßnahmen der menschlichen Aufsicht von Menschen geschrieben | Teilweise |
| 4. Angemessenheit der Leistungskennzahlen | Kennzahlen aus Evaluierungs-Pipelines; die Begründung, dass sie passen, schreiben Menschen | Wenig |
| 5. Risikomanagementsystem (Artikel 9) | Risikoregister als versionierte Datei; die Risikoanalyse führen Menschen durch | Wenig |
| 6. Relevante Änderungen im Lebenszyklus | Git-Historie und Changelog liefern die Rohliste; der Anbieter wählt die relevanten Änderungen aus | Teilweise |
| 7. Angewandte Normen | Eine gepflegte Liste im Repository | Wenig |
| 8. Kopie der EU-Konformitätserklärung | Die unterzeichnete Erklärung, zusammen mit dem Release abgelegt | Nicht |
| 9. System zur Beobachtung nach dem Inverkehrbringen (Artikel 72) | Der Plan als versioniertes Dokument; die Überwachungsdaten stammen aus dem Betrieb | Wenig |
Beispielaufbau: Dokumentationsdateien neben dem Code
Dieser Aufbau ist ein Beispiel, keine vorgeschriebene Struktur.
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.ymlEine Pipeline kann die Dokumente bei jedem Pull Request prüfen
Scan: die Codebasis analysieren
Ein Scan-Schritt kann ein Werkzeug nutzen, das Standardmuster von ML-Frameworks im Code erkennt. Eigene Wrapper und verschleierter Code können übersehen werden.
Erzeugen: die Entwürfe aktualisieren
Die Pipeline baut erzeugte Abschnitte aus aktuellen Eingaben neu auf, sodass der Diff zeigt, was sich in den Dokumenten geändert hat.
Validieren: Vollständigkeit prüfen
Regeln prüfen, ob die erforderlichen Abschnitte vorhanden sind und den erforderlichen Inhalt haben. Eine Inhaltsprüfung ist keine Wahrheitsprüfung: Menschen prüfen die Richtigkeit.
Berichten: das Ergebnis im Pull Request anzeigen
Der Pull Request zeigt, welche Prüfungen bestanden oder nicht bestanden wurden, sodass ein Prüfer die Auswirkungen auf die Dokumentation sieht, bevor die Änderung zusammengeführt wird.
Reiner Text erlaubt die Prüfung Zeile für Zeile, und Branch-Schutz sichert die Historie
Pull Requests zeigen die geänderten Zeilen
Die Historie schützen
Weiterführende Lektüre
Quellen & Referenzen
- Regulation (EU) 2024/1689 (EU AI Act) — Artikel 2, 3, 11, 16, 43 und 99 sowie die Anhänge I, III und IV (Anhang IV: neun Punkte der technischen Dokumentation).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — Anwendungsdaten (Artikel 113) und Änderungen an Artikel 2 Absatz 2, Artikel 3, Artikel 11 Absatz 1, Artikel 99 und Artikel 111 Absatz 2 sowie der neue Artikel 60a.
- GitHub Docs — About protected branches — Schutzregeln für Branches legen fest, ob Mitwirkende per Force Push in einen Branch schreiben dürfen.
- Pro Git — Viewing the Commit History — der Commit-Verlauf listet jeden Commit mit Autor, Datum und Nachricht auf; mit der Patch-Option zeigt er den Diff.
Häufig gestellte Fragen
Was ist Dokumentation als Code für die Dokumentation nach der KI-Verordnung?
Dokumentation als Code hält die technische Dokumentation in der Versionskontrolle, ändert sie über Pull Requests und erzeugt Teile davon in einer Pipeline. Ziel ist, dass die technische Dokumentation zum freigegebenen System passt.
Warum laufen Dokumente außerhalb des Repositorys auseinander?
Word-Dateien und PDFs sind vom Code getrennt, deshalb aktualisiert eine Codeänderung sie nicht. Jemand muss sie aktualisieren, denn Artikel 11 Absatz 1 verlangt, die technische Dokumentation auf dem neuesten Stand zu halten.
Erfüllt Dokumentation als Code Anhang IV?
Keine Praxis erfüllt Anhang IV für sich allein. Anhang IV legt den Inhalt in neun Punkten fest. Dokumentation als Code hilft, diesen Inhalt aktuell und nachvollziehbar zu halten. Der Anbieter muss sicherstellen, dass das System die Anforderungen von Kapitel III Abschnitt 2 erfüllt, zu denen Artikel 11 gehört (Artikel 16 Buchstabe a).
Welche Werkzeuge werden für Dokumentation als Code verwendet?
Sie können Git, Markdown- oder YAML-Dateien und eine CI-Pipeline für Prüfungen und Erzeugung kombinieren. Ein Scanner oder Generator kann die Abschnitte erzeugen, die sich aus dem Code ableiten lassen.
Wie oft sollte die technische Dokumentation eines KI-Systems aktualisiert werden?
Artikel 11 Absatz 1 verlangt, die technische Dokumentation zu erstellen, bevor das System in Verkehr gebracht oder in Betrieb genommen wird, und sie auf dem neuesten Stand zu halten. Artikel 11 Absatz 1 legt kein festes Intervall fest. Unser Vorschlag ist, sie bei jedem Release zu prüfen und nach jeder Änderung am Modell, an den Trainingsdaten oder an der Zweckbestimmung. Eine wesentliche Veränderung erfordert eine neue Konformitätsbewertung (Artikel 43 Absatz 4). Eine wesentliche Veränderung ist eine Änderung nach dem Inverkehrbringen oder der Inbetriebnahme, die in der ersten Konformitätsbewertung nicht vorgesehen oder geplant war. Sie berührt die Einhaltung der Anforderungen an Hochrisiko-KI-Systeme in Kapitel III Abschnitt 2 oder ändert die Zweckbestimmung (Artikel 3 Nummer 23). Eine Konformitätsbewertung ist das Verfahren, mit dem nachgewiesen wird, ob diese Anforderungen erfüllt sind (Artikel 3 Nummer 20).
Scanara bereitet Nachweise aus Ihren Repositorien vor
Scanara liest Ihre verbundenen GitHub-Repositorien und führt regelbasierte Scans auf gängige KI- und Machine-Learning-Muster durch. Unübliche Codemuster kann es übersehen. Getrennt davon erzeugt es aus Vorlagen und Ihren Antworten in der Bewertung Dokumentationsentwürfe als Nachweise für Ihre Compliance-Arbeit. Die Einstufung entscheiden Sie.