Was muss Onboarding-Dokumentation enthalten, damit ein KI-Agent daraus bis zur ersten gemergten Änderung kommt?

Offene Frage

Die Onboarding-Dokumentation eines Projekts soll eine Neue von einer leeren Maschine bis zur ersten gemergten Änderung führen. Das Kapitel über Dokumentation im Buch «Software Engineering at Google» empfiehlt dafür ein «Hello World»-Dokument, das nichts voraussetzt, und nennt den Eintritt ins Team als besten Zeitpunkt, ein solches Tutorial zu schreiben; Diátaxis ordnet es als lernorientiertes Tutorial ein. Beides ist für Menschen gedacht. Zunehmend arbeitet aber auch ein Agent denselben Pfad ab – und stolpert an anderen Stellen: über einen Schritt «im Browser anmelden», über «frag im Kanal nach», über einen Befehl, der auf Tastatureingabe wartet, über ein Diagramm ohne Textfassung, über eine Regel, die alle kennen und niemand aufgeschrieben hat. Konkret offen ist:

• Welche Schritte typischer Onboarding-Pfade scheitern für Agenten am häufigsten, und lassen sich die Fehlschläge in wenige Klassen einteilen (interaktive Eingabe, fehlende Berechtigung, implizites Wissen, Abhängigkeit von einer Person)?
• Reicht eine Liste nicht-interaktiver Befehle mit erwarteter Ausgabe, oder brauchen Agenten zusätzlich eine explizite Verbotsliste (nicht deployen, nichts löschen, niemanden anschreiben) und eine Angabe, was «fertig» bedeutet?
• Wie hält man eine Agentenvariante des Pfads mit der Menschenvariante synchron – ein Dokument mit markierten Abschnitten, zwei Dokumente, oder ein Pfad, der für beide funktioniert, weil jeder Schritt ohnehin ein prüfbarer Befehl ist?
• Gibt es Beobachtungen oder Protokolle dazu, wie oft ein Agent einen Onboarding-Pfad ohne menschliches Eingreifen bis zum Merge durchläuft, und was die Abbrüche auslöste?
• Sollten die Stolpersteine, die ein Agent findet, wie bei Menschen als erste Beiträge in die Dokumentation zurückfliessen – und wer prüft solche Änderungen?

Was eine brauchbare Antwort enthält

Die Art des Projekts und der Agent-Umgebung (Werkzeuge, Rechte, ob ein Mensch Fragen beantwortet); den Pfad oder seine Struktur; die Liste der Schritte, an denen es hakte, mit Fehlerklasse; welche Ergänzung geholfen hat und ob sie die Menschenvariante verschlechtert hat; bei Zählungen die Zahl der Durchläufe und der Abbrüche. Erfahrungsberichte einzelner Projekte sind willkommen, wenn sie als solche gekennzeichnet sind.