Ein Betriebshandbuch, das mitschreibt

Die Lage in einem unserer Kundenprojekte war so, wie sie in vielen gewachsenen Unternehmen aussieht. Eine Plattform, die über Jahre entstanden war, kaum dokumentiert und ständig kaputt. Das Geschäft hing an ihr, also musste sie weiterlaufen. Gleichzeitig sollte die neue Welt in AWS entstehen, damit die alte irgendwann abgelöst werden kann. Unsere Aufgabe war beides: den Betrieb stabilisieren, um das Geschäft am Leben zu halten, und Raum schaffen für die Migration.

Schnell war klar, dass beides zugleich nicht geht, jedenfalls nicht so, wie wir anfangs vorgingen. Wir behoben jede Störung, stellten die offensichtliche Ursache so gut es ging ab und machten weiter. Nach einigen Wochen kamen ähnliche Probleme wieder, aber jedes Mal etwas anders, weil wir die naheliegende Ursache ja beseitigt hatten. Die Stabilisierung fraß die Zeit, die wir für den Aufbau gebraucht hätten, und wir verbrannten dabei.

Die alte Welt verstehen, um sie abzulösen

Für die neue Welt gab es allerhand zu tun. Es gab kein Monitoring und keine Backups. Die Anwendung war nicht containerisiert, und ein sicheres Deployment existierte nicht: Neue Versionen kamen per git pull und PHP-Compile-Skript auf den Server, was so niemals in Produktion hätte gehen dürfen, aber nun einmal so war. Die Anwendung konnte außerdem nicht auf mehreren Instanzen laufen, und sie dafür auseinanderzuoperieren war eine Herausforderung für sich.

Dafür mussten wir das Bestandssystem verstehen, und zwar besser, als es irgendwo aufgeschrieben war. Jede Störung verriet etwas darüber, wie die Plattform wirklich funktionierte, welche Teile voneinander abhingen und welche Annahmen nicht stimmten. Dieses Wissen war für die Migration genauso wertvoll wie für den Betrieb, doch es ging verloren, sobald die Störung behoben war. Es brauchte also ein vernünftiges Betriebshandbuch, in dem wir jede neue Erkenntnis über die Plattform festhalten.

Ein Handbuch im eigenen Git

Damit das Schreiben leichtfällt, wählten wir Markdown als Format und ein eigenes Repository im Git des Kunden. Die Struktur ergab sich schnell: eine Architekturübersicht, die zeigt, welche Teile es gibt und wie sie zusammenhängen, und ein Glossar für die fachlichen Begriffe, die in der Domäne alle benutzen, aber nicht alle gleich verstehen. Beides half schnell, ein gemeinsames Bild zu entwickeln, zwischen uns und dem Team des Kunden.

Statt die Rückblicke nach Störungen in irgendwelchen Mails festzuhalten, legten wir sie im selben Repository ab. Jede Störung bekam eine eigene Datei, mit Symptomen, Ursache, Behebung und den offenen Punkten. Damit lag alles an einem Ort: wie die Plattform aufgebaut ist, was die Begriffe bedeuten und was in der Vergangenheit schiefgegangen ist.

betriebshandbuch/
├── README.md
├── architektur/
│   ├── uebersicht.md
│   └── datenfluss.md
├── glossar.md
├── betrieb/
│   ├── deployment.md
│   └── backup-und-restore.md
└── stoerungen/
    ├── 2025-03-04-checkout-timeout.md
    └── 2025-03-18-db-verbindungen.md

Die KI schreibt mit

Und hier kommt die KI ins Spiel. Die Dokumentation schrieben wir mit Kiro, einer auf VS Code basierenden Entwicklungsumgebung mit KI-Assistent, aus unserem Input. Jedes andere VS Code mit einem Sprachmodell, etwa Claude oder GitHub Copilot, funktioniert ähnlich. Wir beschrieben, was wir herausgefunden hatten, und die KI formulierte es aus, sortierte es an die richtige Stelle und ergänzte die Architekturübersicht.

Schnell nutzten wir das auch bei der Behandlung von Störungen. Statt nebenbei Notizen zu machen, ließen wir die KI die Erkenntnisse protokollieren und im Hintergrund Daten sammeln: aus Cloudflare, aus Grafana, aus der Datenbank und aus weiteren Metriken. Mit jedem Schritt der Migration nach AWS wurde das noch wirkungsvoller, weil über die AWS CLI immer mehr Metriken und Details abrufbar waren. Auch das IaC-Repository und das Code-Repository ließen sich so schnell miteinander in Verbindung bringen, sodass sichtbar wurde, welche Änderung an welcher Stelle der Infrastruktur wirkt.

Genauso wichtig war, dass die KI nichts direkt ins Handbuch schrieb. Jede Änderung kam als Pull Request, und ein Mensch prüfte sie, bevor sie übernommen wurde. Das kostet wenig Zeit, weil man nur prüft und nicht selbst formuliert, und es verhindert, dass eine plausibel klingende, aber falsche Erklärung zum vermeintlichen Wissen der Plattform wird.

Nein, die KI hat nicht unsere Arbeit gemacht. Die Ursachen fanden und behoben wir selbst. Aber gerade in stressigen Situationen ist es nicht das Wichtigste, gute Sätze zu formulieren, und im Nachhinein hat man die Details nicht mehr im Kopf. Die KI schließt genau diese Lücke: Sie hält fest, während man arbeitet, und am Ende steht eine saubere Notiz statt eines halb ausgefüllten Dokuments, das niemand mehr fertig schreibt.

Gold wert: Störungen in Beziehung setzen

Den größten Wert hatte etwas, das wir anfangs gar nicht geplant hatten. Weil alle Störungen im selben Repository lagen, konnte die KI bei einer neuen Störung die früheren heranziehen. Sie erkannte, dass die Symptome einer früheren Störung ähnelten, welche Ursache damals gefunden wurde und welche Behebung geholfen hatte. Genau das hatte uns zu Beginn gefehlt, als wir dieselben Probleme in leicht veränderter Form immer wieder von vorn untersuchten.

So wurde jede Behebung schneller, und die nächsten Schritte der Migration ließen sich gezielter planen. Wenn drei Störungen auf dieselbe Schwachstelle zeigten, wussten wir, welcher Teil der alten Plattform zuerst abgelöst werden sollte. Nebenbei wurde die Architekturübersicht Stück für Stück detaillierter, weil jede Störung ein weiteres Detail ans Licht brachte, das sonst nur in den Köpfen einzelner Personen gelegen hätte.

Was so entsteht, ist eine Wissensbasis, die sich fast von selbst pflegt und erweitert. Sie veraltet nicht, weil sie genau dann aktualisiert wird, wenn sich etwas Neues zeigt, und sie ist nicht von einer einzelnen Person abhängig, die alles im Kopf hat. Für uns ist das eine der wirkungsvollsten Arten, die heutigen Möglichkeiten von KI im Betrieb zu nutzen.

Ein Bericht für das Team, einer für die Geschäftsführung

Eine Störung hat mehr als ein Publikum. Das Tech-Team braucht die Details: Zeitleiste, Ursache, betroffene Komponenten, Bezüge zu früheren Störungen und die nächsten Schritte. Die Geschäftsführung braucht etwas anderes. Der CEO des Kunden sah mit jedem Ausfall das Geschäft in Gefahr, und gleichzeitig ging die Migration nicht schnell genug voran, weil das Team Nacht für Nacht damit beschäftigt war, Brände zu löschen, um das Geschäft am Leben zu halten. Für die Geschäftsführung zählt nicht, welcher Cronjob Verbindungen offen hielt, sondern was die Störung gekostet hat und was als Nächstes passiert.

Weil alles Wissen über eine Störung schon im Handbuch lag, entstanden beide Fassungen aus derselben Quelle. Die KI schrieb daraus einen technischen Bericht für das Team und eine kurze Zusammenfassung für die Geschäftsführung. Gerade bei dieser Übersetzung ist sie stark: Sie macht aus „Verbindungspool erschöpft“ eine Aussage darüber, was Kunden erlebt haben und was das für das Geschäft bedeutet, ohne dass jemand nach einer langen Nacht noch zwei Texte schreiben muss.

Den größten Unterschied machten echte Zahlen. Über den Lesezugriff auf die Daten konnte die KI den Umsatz rund um jede Störung automatisch auswerten und den tatsächlichen Business Impact zeigen, statt ihn zu schätzen. Dabei zeigte sich ein Muster: Während einer Störung ging der Umsatz erwartungsgemäß zurück, nach ihrem Ende stieg er aber überproportional wieder an, weil Kunden nachholten, was sie vorher nicht abschließen konnten.

Mit diesen Zahlen ließ sich die Lage ehrlich darstellen: was eine Störung das Geschäft wirklich kostet, wie oft sie vorkam und wie viel Zeit des Teams jedes Mal in die Brandbekämpfung statt in die neue Welt floss. Daraus wurde deutlich, wie wichtig es war, alle Ressourcen auf den schnellstmöglichen Umzug zu setzen, statt die alte Plattform weiter zu flicken. Aus einem Bauchgefühl wurde eine Entscheidung, die sich mit Zahlen begründen ließ, und die Geschäftsführung konnte sie mittragen, weil sie sie verstand.

Was ist passiert?
  Ein Satz, ohne Fachbegriffe.

Was hat es gekostet?
  Umsatz während der Störung,
  Nachholeffekt danach, Saldo.

Was tun wir dagegen?
  Sofortmaßnahme und Stand der Ablösung.

Was heißt das für die Migration?
  Welcher Teil jetzt Vorrang bekommt.

So fängst du an

Für den Einstieg brauchst du kein großes Projekt. Leg ein Repository im eigenen Git an und gib ihm eine einfache Struktur: eine Architekturübersicht, ein Glossar und einen Ordner für Störungen. Die erste Übersicht darf grob sein, ein paar Kästen und Pfeile genügen, sie wird mit der Zeit genauer.

Ab der nächsten Störung schreibt ihr dort mit, und zwar mit der KI in eurer Entwicklungsumgebung. Erzähl ihr, was du siehst und was du tust, und lass sie daraus eine Notiz machen. Richte ihr nach und nach Lesezugriffe auf die Datenquellen ein, die ihr bei Störungen ohnehin anschaut, und verlange für jede Änderung am Handbuch einen Pull Request. Nach ein paar Störungen merkst du, dass die KI Verbindungen herstellt, an die du selbst nicht gedacht hättest.

# 2025-03-18 Datenbankverbindungen erschöpft

## Symptome
Checkout bricht ab, Fehler 502 ab ca. 14:10.

## Ursache
Verbindungspool voll, ein Cronjob hält
Verbindungen offen.

## Behebung
Cronjob gestoppt, Pool neu gestartet.

## Bezüge
Ähnlich wie 2025-03-04 (Checkout-Timeout).

## Offen
Cronjob in der neuen Welt als eigenen Dienst
mit begrenzten Verbindungen betreiben.

Was das für dich heißt

Ein Betriebshandbuch scheitert selten am guten Willen, sondern daran, dass niemand Zeit hat, es zu schreiben, schon gar nicht mitten in einer Störung. Eine KI, die mitschreibt, Daten sammelt und frühere Störungen heranzieht, nimmt genau diese Last ab, solange sie nur lesen darf und Menschen jede Änderung prüfen. So schließt sich der Abstand zwischen dem, was ein System tatsächlich tut, und dem, was ihr darüber wisst, ein Abstand, den wir im Artikel Gestern war’s noch sicher, oder? aus Sicht der Sicherheit beschreiben. Und weil dasselbe Wissen auch die Sprache der Geschäftsführung sprechen kann, wird aus jeder Störung ein Argument mit echten Zahlen. Wenn du vor einer ähnlichen Plattform stehst oder euer Betriebswissen endlich an einem Ort haben willst, gehen wir das gern gemeinsam an.