KI-Codeänderungen nachvollziehbar dokumentieren

Das Problem

Vor drei Monaten hat jemand im Team mit KI-Hilfe eine Funktion in der Betriebsanwendung geändert. Heute tritt ein Fehler auf, der damit zusammenhängen könnte. Wer hat die Änderung gemacht? Was war der Auftrag? Wurde sie getestet? Was genau wurde geändert? Niemand weiss es mehr. Die Änderung steht im Code, aber ohne Erklärung.

Mit KI entstehen Änderungen oft schneller, als man sie dokumentieren kann. Ein Auftrag, ein Vorschlag, ein Klick auf «übernehmen», und der Code ist anders. Gerade weil das so schnell geht, wird vergessen, warum etwas geändert wurde und wie sicher man ist, dass es funktioniert.

Eine kurze, feste Dokumentation löst das. Sie kostet fünf Minuten pro Änderung und hilft bei Fehlersuche, Übergabe, Audits und beim Lernen. Wichtig ist, dass sie ehrlich festhält, was geprüft wurde und was nicht.

So lösen Sie es mit KI – Schritt für Schritt

1. Legen Sie eine Vorlage fest. Eine halbe Seite mit festen Feldern. Alle im Team verwenden dieselbe, damit Einträge vergleichbar sind.
2. Notieren Sie den Anlass. Warum wird geändert? Welcher Fehler, welche Anforderung, welche Aufgabe? Mit Verweis auf das Ticket, falls vorhanden.
3. Halten Sie den Auftrag an die KI fest. In ein bis zwei Sätzen: Was wurde verlangt? Welches Werkzeug wurde verwendet? Der vollständige Verlauf muss nicht archiviert werden, aber die Kernaussage.
4. Beschreiben Sie, was geändert wurde. Welche Dateien, welche Funktionen, welche Verhaltensänderung? Eine kurze Zusammenfassung, ergänzt durch die technische Änderungsliste des Versionsverwaltungssystems.
5. Dokumentieren Sie die Prüfung. Wer hat den Code gelesen? Welche Tests liefen? Welche Fälle wurden manuell geprüft? Gab es Auffälligkeiten?
6. Benennen Sie Risiken und offene Punkte. Was ist nicht getestet? Welche Annahmen gelten? Was sollte beobachtet werden?
7. Halten Sie den Rückweg fest. Wie lässt sich die Änderung rückgängig machen? Das ist oft eine einfache Angabe, die im Ernstfall Zeit spart.
8. Lassen Sie die KI beim Ausformulieren helfen. Aus Ihren Stichworten und der Änderungsliste kann sie einen Eintrag entwerfen. Prüfen Sie ihn, bevor er abgelegt wird.

Vorlage zum Kopieren

Geben Sie nur bereinigte Stichworte und Änderungslisten ein, ohne vertraulichen Code oder Zugangsdaten.

Erstelle aus den folgenden Stichworten einen Eintrag für unser Änderungsprotokoll (Deutsch, sachlich, höchstens 200 Wörter) für eine KI-gestützte Codeänderung in einem Schweizer KMU.
Angaben (bereinigt): Anlass: [z. B. Fehler bei der Berechnung der Rabatte]. Auftrag an die KI: [Kurzfassung]. Verwendetes Werkzeug und Datum: [Werkzeug, Datum]. Geänderte Dateien und Funktionen: [Liste]. Tests: [welche Tests liefen, welche Ergebnisse]. Manuelle Prüfung: [was, durch wen]. Bekannte Risiken oder offene Punkte: [Liste]. Rückgängig machen: [Vorgehen].
Gliedere in: Anlass, Auftrag, Änderung, Prüfung, Risiken und offene Punkte, Rückgängig machen, Verantwortliche. Verwende nur diese Angaben. Erfinde keine Tests, Prüfungen oder Ergebnisse. Markiere fehlende Angaben mit [fehlt].

Prüfen Sie den Eintrag gegen die tatsächliche Änderung, bevor Sie ihn ablegen.

Felder der Vorlage

Worauf Sie achten müssen

• Ehrlich dokumentieren: Wenn nichts getestet wurde, schreiben Sie das. Eine Doku, die mehr behauptet, als stattgefunden hat, ist gefährlich.
• Keine Geheimnisse in der Doku: Zugangsdaten und Schlüssel gehören weder in Einträge noch in KI-Eingaben. Siehe Quellcode und Daten in KI-Werkzeugen.
• Prüfung bleibt menschlich: Der Code wird von einer Person gelesen, die ihn versteht. Siehe Code-Review-Checkliste.
• Lizenz und Herkunft: Wenn grössere Teile von der KI stammen, notieren Sie das. Es kann bei Lizenzfragen helfen, siehe KI-Code und Open Source.
• Verhältnismässigkeit: Für Kleinigkeiten genügt ein Satz, für grössere Änderungen die ganze Vorlage. Legen Sie Schwellen fest.
• Auffindbarkeit: Die Doku gehört dorthin, wo man sie später sucht: bei der Änderung in der Versionsverwaltung oder im Ticket.

Ein Beispiel aus der Praxis

Ein Beispiel: Ein Handelsbetrieb in Olten betreibt eine eigene Bestellanwendung, die zwei Entwickler pflegen. Sie nutzen KI für Korrekturen und kleine Erweiterungen.

Vorher: Die Änderungen stehen in der Versionsverwaltung, aber die Beschreibungen lauten «Fix» oder «Anpassung». Als nach einem Monat Fehler bei Mengenrabatten auftreten, rätselt das Team, welche Änderung dafür verantwortlich ist und warum sie gemacht wurde.

Nachher: Das Team führt eine einseitige Vorlage ein. Jede KI-gestützte Änderung enthält Anlass, Auftrag, Tests und Risiken. Beim nächsten Fehler findet es nach wenigen Minuten den Eintrag, der auf einen nicht getesteten Sonderfall hinweist. Die Korrektur ist schnell gemacht, und das Team ergänzt den Test.

So hilft Ihnen Alpasana

Der Kurs KI für Developer mit Claude und Codex von absofort behandelt Codegenerierung, Debugging, Refactoring und Review, das Delegieren von Aufgaben und das Verifizieren von Ergebnissen. Als Kursgegenstände sind Claude, Claude Code, Claude API und Codex genannt, ebenso der kombinierte Workflow «Claude plant, Codex baut, Claude reviewt».

Das Entwickler-Playbook umfasst Prompts, Review-Regeln, Tests und Datenschutzgrenzen, dazu kommen ein Praxisprojekt, ein Abschlussquiz, eine KI-geprüfte Praxisaufgabe und ein verifizierbares Zertifikat.

Häufige Fragen

Muss ich den ganzen Chatverlauf mit der KI aufbewahren?

In der Regel nicht. Die Kernaussage des Auftrags genügt. Chatverläufe können vertrauliche Informationen enthalten und sind schwer durchsuchbar. Bewahren Sie sie nur auf, wenn eine Regel oder ein Auftraggeber das verlangt.

Wie ausführlich muss die Doku sein?

So ausführlich, dass eine andere Entwicklerin in fünf Minuten versteht, warum und wie geändert wurde und wie sicher die Änderung ist. Eine halbe Seite genügt meist.

Wer ist verantwortlich, wenn die KI Fehler macht?

Verantwortlich ist die Person oder der Betrieb, der die Änderung freigibt. Deshalb gehört die Prüfung durch einen Menschen in die Doku. Haftungsfragen im Einzelfall klären Sie mit Fachpersonen.