Wie wir unsere technische Dokumentation mit KI-Agenten automatisiert haben

Die meisten Menschen machen jedes Jahr tausende Fotos und schauen sich die meisten nie wieder an. Popsa hilft dabei, die wichtigen zu finden und daraus etwas Greifbares zu machen, das man behält und immer wieder anschaut.

Unsere mobilen Apps nutzen Machine Learning direkt auf den Geräten der Kunden, um Fotos zu analysieren, ohne sie in die Cloud hochzuladen. Sie erkennen die Menschen und Momente, die wirklich zählen, und gestalten daraus ein Layout, das die Geschichte dahinter erzählt. Von außen wirkt das einfach – und genau darum geht es.

Hinter dem, was nach außen so einfach wirkt, steckt eine komplexe technische Infrastruktur: iOS-, Android- und Web-Apps, Backend-Services für Zahlungen und Bestellabwicklung sowie Systeme für Bildverarbeitung und Auslieferung in über 50 Ländern. Diese Systeme verwalten die persönlichsten Fotos der Menschen und verarbeiten ihre Zahlungen. Sie müssen zuverlässig und sicher bleiben – und das Verständnis im Team dafür, wie alles zusammenhängt, darf nicht verloren gehen.

Dieses Verständnis steckt in der Dokumentation: Sie erklärt, wie die Systeme zusammenhängen, welche Konventionen gelten und wo sensible Grenzen verlaufen. Sie macht es möglich, dass Teams komplexe Systeme warten, absichern und weiterentwickeln können, ohne von einzelnen Personen abhängig zu sein, die bestimmte Teile entwickelt haben. Diese Dokumentation aktuell zu halten, ist allerdings ein Problem, mit dem jedes Engineering-Team früher oder später zu kämpfen hat – auch wir.

Ich habe in genug Engineering-Teams gearbeitet, um diesen Ablauf zu kennen. Irgendwann sagt jemand: „Dieses Mal halten wir die Dokumentation wirklich aktuell.“ Es folgt ein kurzer Energieschub. Seiten werden angelegt, Konventionen festgehalten, Architekturdiagramme erstellt. Manchmal wechseln Teams sogar das ganze System (GitHub, Confluence, Coda), einfach um neu zu starten. Für ein paar Wochen, vielleicht ein paar Monate, sieht alles gut aus.

Dann veraltet die Dokumentation.

Nicht, weil es niemanden mehr interessiert, sondern weil sich Software nicht linear verändert. Viele kleine Änderungen lassen sich noch gut mittragen, ohne dass die Dokumentation stark abweicht. Aber dann wird die Authentifizierung umgebaut, ein neues Framework eingeführt oder eine API neu strukturiert. Die Dokumentation war korrekt, als sie geschrieben wurde, aber der Code hat sich weiterentwickelt. Wir haben zum Beispiel gerade unsere iOS-App von einer linearen Navigation auf eine Navigation mit Tabs umgestellt. Nach so einer Veränderung können ganze Abschnitte der Dokumentation plötzlich ein System beschreiben, das es so nicht mehr gibt.

Die meisten Entwickler wissen, dass dies ein Problem sein kann, daher hat sich unser Team kürzlich gefragt, wie man es lösen kann, indem man Dokumentation als System versteht, nicht als Aufgabe.

Die Lücke, die nie geschlossen wurde

Natürlich wurde schon vorher versucht, das Problem zu lösen. Tools wie Javadoc, Swagger oder Doxygen erzeugen Dokumentation direkt aus dem Code. Das ist nützlich für das, was sie leisten – API-Referenzen, Funktionssignaturen oder Endpunkte. Aber die Ergebnisse bleiben technisch und nüchtern. Sie zeigen, was eine Funktion erwartet und zurückgibt, nicht warum ein System so aufgebaut ist, welche Konventionen gelten oder wie alles zusammenpasst. Gerade die Dokumentation, die von Menschen geschrieben wird, veraltet – Architekturüberblicke oder Konventionsdokumente. Genau diese Lücke wurde nie geschlossen.

Lange Zeit wäre der Aufwand, etwas Besseres zu bauen, größer gewesen als die Dokumentation einfach von Hand zu pflegen. Mit KI hat sich das geändert. Die Lücke zwischen „Ich wünschte, das würde sich selbst aktuell halten“ und „Ich kann tatsächlich etwas bauen, das genau das macht“ hat sich geschlossen.

Unser Team arbeitet schnell und tauscht Informationen effizient aus, arbeitet neue Entwickler ohne Engpässe ein und sorgt dafür, dass alle verstehen, wie die Systeme funktionieren. Eine gut ausgearbeitete Dokumentation macht dies möglich. Als wir unsere kürzlich überprüft haben, war das Bild jedem Entwicklerteam vertraut: Ein Teil war gut, ein anderer beschrieb Codebasen von vor Monaten, und an manchen Stellen fehlte die Dokumentation ganz – das Wissen existierte nur in den Köpfen einzelner.

Wie viele andere Teams nutzen wir inzwischen immer mehr KI-Agenten in unseren Repositories – und auch sie brauchen genau das. Mit einer gut strukturierten Dokumentation können wir Agenten genauso in das Team einbinden wie neue Entwickler: so hängen die Systeme zusammen, das sind die Konventionen, das ist wichtig. Doch sowohl Menschen als auch Maschinen stoßen auf dasselbe Problem – eine Dokumentation, die einmal geschrieben und nie aktualisiert wurde.

Menschen und Maschinen

Diese zweite Zielgruppe (KI-Agenten) hat unsere Sicht darauf verändert. Dokumentation war lange etwas, das wir für Menschen gepflegt haben: hilfreich, aber oft vernachlässigt. Seit KI-Agenten ins Spiel kamen, ist daraus eine Infrastruktur geworden.

Weil wir gemerkt haben, dass sich Konventionen an vielen Stellen wiederholen, haben wir dieses Wissen zentral gebündelt. Heute führen wir in all unseren wichtigen Repositories Dateien wie AGENTS.md, CLAUDE.md oder .cursorrules ein. Sie basieren auf Templates und enthalten jeweils einen Header, der auf unser zentrales Dokumentations-Repository verweist.

Wenn ein KI-Agent an einer beliebigen Popsa-Codebasis arbeitet, stößt er als Erstes auf einen Verweis auf unsere lebendige Dokumentation. Dort findet er die Konventionen, Muster, das Glossar, Architekturentscheidungen – und ganz entscheidend – das Produktwissen. Ohne dieses Wissen könnte ein Agent nicht verstehen, dass ein PBK-7 ein mittelgroßes Fotoalbum im Querformat ist oder dass TIL-2b eine schwarze Fotokachel mit glänzender Oberfläche bezeichnet.

So entsteht ein stimmiger Kreislauf:

• Entwickler erledigen die Arbeit

• Agenten prüfen diese Arbeit und nutzen die Dokumentation, um fundierteres, kontextbezogenes Feedback zu geben

• dieses Feedback führt zu Änderungen im Code

• diese Änderungen lösen Pull Requests für die Aktualisierung der Dokumentation aus – bereit zur Überprüfung und Zusammenführung.

Die aktualisierte Dokumentation steht dann direkt der nächsten Person oder dem nächsten Agenten zur Verfügung, der eine Aufgabe übernimmt. Das System erhält sich selbst und wirkt über mehrere Repositories hinweg weiter. Wenn Produktnamen, Feature-Flags und Analytics-Events in die zentrale Dokumentation aufgenommen werden, steht dieses Wissen auch Agenten zur Verfügung, die in ganz anderen Codebasen arbeiten.

Das Android-Team veröffentlicht ein neues Feature. Wenn ein Agent Wochen später den entsprechenden iOS-Pull-Request prüft, hat er genug Kontext, um zu erkennen, dass der Feature-Name nicht übereinstimmt oder Analytics-Events anders benannt sind. Zentrale Dokumentation wird so zu einem gemeinsamen Gedächtnis für die gesamte Organisation – nicht nur zu einer Referenz für das Repository, für das sie ursprünglich geschrieben wurde.

Es gibt auch einen finanziellen Aspekt. Ohne gute Dokumentation muss ein KI-Agent, der mit einem Repository arbeitet, sich die Codebasis von Grund auf erschließen: Dateien durchsuchen, Quellcode lesen, nach Mustern suchen. Diese Erkundung kostet bei jeder einzelnen Interaktion Zeit und Tokens. Mit einer gepflegten, aktuellen Dokumentation reicht eine einzige Datei, um den Gesamtzusammenhang zu verstehen. Wenn Dokumentation verlässlich ist, sinken die Kosten pro Interaktion im gesamten Unternehmen.

So funktioniert es

Wir haben eine Pipeline aufgebaut. Das Prinzip ist einfach, auch wenn die Details sorgfältig durchdacht sind.

Wenn ein Entwickler Code in unsere primären Codebasen (Backend-Services, Web-, iOS- oder Android-Apps, IaC-Repository) einbindet, wird eine schlanke GitHub Action gestartet. Sie sammelt die geänderten Dateipfade und die Commit-Referenz und sendet ein Ereignis mit dem Namen „repository_dispatch“ an unser zentrales Dokumentations-Repository.

Dort greift ein weiterer Workflow das Ereignis auf und geht gezielt vor:

Entscheidend ist, dass nicht alles neu generiert wird. Eine YAML-Konfigurationsdatei ordnet jedem Quell-Repository die konkreten Dokumentationsdateien zu, die davon betroffen sein können, ergänzt durch Muster, die festlegen, welche Dateipfade berücksichtigt werden. Eine Änderung an Terraform-Modulen führt nicht zu einem Update der Go-Standards, genauso wenig wie Änderungen in Swift-Dateien die TypeScript-Konventionen betreffen. Es wird nur die Dokumentation geprüft, die tatsächlich mit der Codeänderung zusammenhängt.

Der Workflow startet Claude Code mit einem sorgfältig formulierten Prompt. Claude liest die bestehende Dokumentation, analysiert das Quell-Repository genau auf dem Commit, der die Aktualisierung ausgelöst hat, vergleicht die Dokumentation mit dem tatsächlichen Code und schlägt Änderungen vor. Entscheidend ist, dass er auch melden kann, dass keine Änderungen erforderlich sind. Der Prompt gibt klar vor, was Claude tun soll und was nicht: die bestehende Dokumentenstruktur beibehalten, britisches Englisch verwenden, bei Beispielen Dateipfade angeben, weiterhin korrekte Inhalte nicht entfernen und keine spekulativen Ergänzungen machen. Wir bitten um „gezielte Überarbeitungen“ statt um „vollständige Neufassungen“.

Ein paar Details zur Umsetzung. Das Dokumentations-Repository arbeitet weder mit Polling noch mit festen Zeitplänen. Stattdessen senden die Quell-Repositories bei Änderungen eine Benachrichtigung. Neue Repositories lassen sich so einfach einbinden – mit einem kleinen Workflow und einem Eintrag in der Konfigurationsdatei. Pro Quell-Repository läuft immer nur eine Dokumentationsaktualisierung gleichzeitig. Wenn zwei PRs kurz hintereinander zusammengeführt werden, wartet die zweite Aktualisierung, bis die erste abgeschlossen ist, statt verworfen zu werden. Und wenn Claude feststellt, dass keine Änderungen nötig sind („NO_CHANGES_NEEDED“), wird die Pipeline sauber beendet. Nicht jede Codeänderung betrifft die dokumentierten Konventionen – und genau das berücksichtigt das System.

Ein Detail, das uns besonders gut gefällt, ist, dass Cursors Bugbot (ein KI-Code-Prüfer) während der Entwicklung sechs Fehler in der ersten Implementierung der Pipeline entdeckt hat. Eine KI prüft den Code, mit dem eine andere KI betrieben wird. „Turtles all the way down“ (Schicht für Schicht).

Wir haben die Pipeline als Open Source veröffentlicht, sodass du sie für deine eigenen Repositories anpassen kannst.

Prüfen statt blind absegnen

Auch wenn wir alles begrüßen, was uns schneller macht, gehen wir mit solchen Lösungen sorgfältig um. Der Auto-Docs-Workflow erstellt einen Pull Request, den Entwickler prüfen und beurteilen können, ob die vorgeschlagenen Änderungen tatsächlich dem Code entsprechen – „Ist es das, was der Code jetzt tatsächlich tut?“ Das Team kann den PR freigeben, Änderungen anfordern oder ihn komplett schließen. Dieser Schritt sorgt dafür, dass Menschen die Kontrolle behalten – wir sehen, wie sich die Dokumentation entwickelt, und bleiben mit den Konventionen vertraut. Das Wissen bleibt in unserer Hand, auch wenn wir die Pflege nicht mehr manuell erledigen.

Im Umgang mit KI sehen wir die Aufgabenverteilung zunehmend so:

Systeme bauen ist Aufgabe der Entwickler. Ergebnisse prüfen ebenfalls. Der wiederkehrende Teil dazwischen ist Aufgabe der KI. Diffs im Code durchgehen, erkennen, welche Dokumentation betroffen ist, Abschnitte aktualisieren, den Linter ausführen, einen PR erstellen – genau diese „mühsame Arbeit“ kann die KI inzwischen zuverlässig übernehmen.

Das zugrunde liegende Muster

Eigentlich wollten wir damit nur die Qualität unserer Dokumentation verbessern. Dabei sind wir auf ein Muster gestoßen, das sich auf viele Bereiche der Engineering-Arbeit übertragen lässt. Denk an Aufgaben, die jedes Team für wichtig hält, aber niemand wirklich übernehmen möchte:

• Testabdeckung sinnvoll aktuell halten, während sich der Code weiterentwickelt

• Changelogs pflegen, die tatsächlich beschreiben, was sich geändert hat

• sicherstellen, dass API-Verträge noch zur Implementierung passen

• Abhängigkeiten regelmäßig überprüfen

• Architekturentscheidungen dokumentieren und aktualisieren

All diese Aufgaben folgen derselben Struktur: Es gibt einen aktuellen Zustand und einen gewünschten Zustand – und die eigentliche Arbeit besteht darin, beides zu vergleichen und gezielt anzupassen. Den Ist-Zustand lesen, die Quelle der Wahrheit prüfen, Unterschiede erkennen und daraus konkrete Änderungen ableiten, die anschließend überprüft werden. Genau dieses Muster kann KI gut abbilden, und die Kosten liegen (nach der Einrichtung) bei nahezu null.

Damit sind wir wieder am Anfang. Menschen vertrauen Popsa ihre persönlichsten Fotos an – Erinnerungen an Menschen und Orte, die ihnen wichtig sind. Die Systeme dahinter müssen verstanden, gepflegt und sicher betrieben werden – nicht nur von denen, die sie entwickelt haben, sondern von allen, die später daran arbeiten. Dokumentation macht das möglich. Und zum ersten Mal haben wir eine Möglichkeit, sie aktuell zu halten, ohne dass sie zur Nebenaufgabe wird.

Das Ergebnis ist ein Team, das weniger Zeit in die Pflege von Wissen steckt und mehr Zeit in die Verbesserung des Erlebnisses: bessere Auswahl, mehr Privatsphäre, bessere Produkte. Entwickler konzentrieren sich auf das, was für Menschen wirklich zählt, nicht auf die Pflege im Hintergrund.

Darum ging es letztlich. Nicht um Dokumentation an sich, sondern um das, was sie möglich macht – etwas zu bauen, das den Erinnerungen gerecht wird, die Menschen uns anvertrauen.