Codebase verstehen in 44 Minuten:
Knowledge-Graph mit Understand-Anything

Im Grunde läuft eine kleine Fabrik. Zuerst inventarisiert ein Scanner alle Dateien des Projekts: welche Sprache, welche Größe, welche Verweise auf andere Dateien. Das dauert wenige Minuten und liefert eine Inhaltsliste, mit der die eigentliche Arbeit anfangen kann.

Danach bekommen mehrere spezialisierte KI-Helfer im Hintergrund jeweils ein Bündel von Dateien zugewiesen — und arbeiten parallel. Jeder Helfer beschreibt seinen Block in natürlicher Sprache: was tut diese Datei, welche Begriffe und Vorgänge tauchen darin auf, welche Verbindungen gibt es zu anderen Teilen des Projekts. Das ist der eigentlich rechenintensive Schritt und macht etwa die Hälfte der Gesamtzeit aus.

Wenn alle Helfer fertig sind, fügt ein weiterer Schritt die Einzelbeschreibungen zu einem Gesamtbild zusammen. Aus den parallel entstandenen Inseln wird ein zusammenhängendes Netz: Dateien als Knoten, ihre gegenseitigen Aufrufe als Verbindungen. Plus eine wichtige Zusatzleistung — das Werkzeug ordnet jede Datei einer von zehn fachlichen Schichten zu. Persistenz, Geschäftslogik, Oberfläche, Konfiguration und so weiter. In den meisten Projekten ist diese Schichten-Struktur nirgendwo explizit aufgeschrieben. Das Werkzeug rekonstruiert sie aus dem Code selbst.

Im letzten Schritt entsteht eine Lese-Tour: zwölf Schritte, in welcher Reihenfolge man die wichtigsten Stellen des Projekts anschauen sollte, wenn man neu einsteigt. Nicht alphabetisch, nicht nach Größe — sondern in einer didaktischen Reihenfolge, die das Werkzeug aus den vorigen Schritten ableitet. Das ist die für den Alltag praktischste Komponente.

Optional gibt es eine zweite Sicht obendrauf: einen sogenannten Domänen-Graph. Der zeigt nicht "welche Datei ruft welche", sondern "welche fachlichen Geschäftsabläufe durchziehen das Projekt". Bei meinem Pilot kam dabei eine Karte mit fünf Domänen und neun Geschäftsabläufen heraus — eine Sicht, die ein Geschäftsführer lesen kann, ohne Programmierer zu sein.

Ich kenne das Projekt seit Monaten. Trotzdem haben drei Befunde aus der Karte mir etwas Neues gegeben. Nicht im Sinne von "das wusste ich nicht", sondern im Sinne von "das war diffus vermutet, jetzt ist es belegt und zeigbar".

Der erste Befund betrifft die Größe einzelner Dateien. Im Code-Alltag wird "lange Datei" oft mit "schlechte Datei" verwechselt. Das Werkzeug unterscheidet sauberer: eine Datei ist groß, weil sie an einer zentralen Stelle viel Verantwortung trägt — die typische Persistenz-Schicht, also der Bereich, der mit der Datenbank spricht. Anderswo ist eine Datei groß, weil dort über die Jahre Code eingeflossen ist, der eigentlich verteilt gehörte. Die Karte zeigt diesen Unterschied an der Form: ein zentraler Knoten mit vielen ein­gehenden Verbindungen ist gesund. Ein Knoten mit vielen aus­gehenden Verbindungen ist verdächtig. Wer aufräumen will, hat damit eine erste Priorisierung.

Der zweite Befund hat mich tatsächlich überrascht. Im Projekt gibt es eine bewusst gesetzte Regel: bestimmte Hilfsfunktionen sollen nur an einer einzigen Stelle existieren und von dort aus wiederverwendet werden — nicht kopiert. Die Karte hat sichtbar gemacht, dass diese Regel im Code tatsächlich gelebt wird. Die Hilfsfunktionen tauchen an einer Stelle auf, und von dort gehen die Verweise an die richtigen Konsumenten. Ohne die Karte wäre das eine Hoffnung, gestützt auf Stichproben. Jetzt ist es ein Beleg, den man im Team-Gespräch zeigen kann.

Der dritte Befund ist ein konkretes Aufräum-Thema: eine bestimmte Datei im Frontend-Teil hat eine intern festgelegte Größen-Grenze überschritten. Das ist nicht dramatisch — aber es war ein Thema, das in der Tagesarbeit immer wieder verdrängt wurde. Die Karte hat es so deutlich markiert, dass es danach als konkretes Arbeitspaket im Backlog landete. Ohne Werkzeug hätte ich das gewusst, aber nicht so sauber vorzeigen können.

Dazu kam ein Nebeneffekt, der mich gefreut hat: ein größerer Umbau, der vor zwei Quartalen passiert war, ist auf der Karte als Erfolg sichtbar. Eine Datei, die vorher 3.400 Zeilen hatte, hat heute noch 1.200 — und die Karte zeigt die niedrigere Komplexität auch in der Form des Knotens. Wer einem Auftraggeber zeigen will, dass ein Refactor gewirkt hat, hat damit ein Argument, das nicht aus Bauchgefühl besteht.

Nach dem Lauf öffnet das Werkzeug eine kleine Web-Oberfläche im eigenen Browser. Kein Cloud-Login, kein Konto, kein Speichern in fremden Rechenzentren — alles läuft auf dem Rechner, auf dem auch der Lauf stattgefunden hat. Die Karte selbst liegt als Datei im Projekt­verzeichnis und kann weitergegeben werden wie jede andere Datei.

Die wichtigste Ansicht ist die nach Schichten geordnete. Zehn fachliche Schichten, von der Konfiguration ganz unten bis zur Benutzer­oberfläche ganz oben. Wer plant, was als nächstes angefasst wird, sieht hier auf einen Blick, wo der Eingriff sitzt und welche Schichten sonst noch berührt werden müssen. Im Team-Gespräch wird die Diskussion damit hörbar kürzer.

Direkt daneben liegt die Lese-Tour: zwölf nummerierte Schritte, in welcher Reihenfolge man die Stellen lesen sollte, wenn man neu einsteigt. Im Pilot war Schritt eins die zentrale Beschreibungs­datei des Projekts, Schritt zwei die Schnittstelle zwischen Backend und Oberfläche, Schritt zwölf ein Deep-Dive in den geschützten Kern, der nicht ohne Migrations­plan angefasst werden darf. Eine Reihenfolge, die man so auch handschriftlich entwerfen würde — wenn man die Zeit hätte, die man im Alltag selten hat.

Eine zweite Ansicht, die ich erwähnenswert finde, ist die fachliche Sicht: nicht "welche Datei ruft welche", sondern "welche Geschäfts­abläufe gehen durch das Projekt". Im Pilot wurden fünf Domänen identifiziert — von der Daten-Aufnahme über die Bild­erkennung bis zum Export. Das ist die Sicht, die man einem Geschäfts­führer oder einem fachlichen Auftrag­geber zeigen kann, ohne dass Programmierung erklärt werden muss. Das ist im Alltag selten — und entsprechend wertvoll.

Das Werkzeug ist solide gebaut, aber drei Stolperfallen sind beim ersten Anlauf fast garantiert. Alle drei haben mit der Art zu tun, wie das Plugin sich in die Werkzeug­kette einfügt — nichts, was die Anwendung selbst falsch macht, sondern Reibung an den Rändern.

Erstens: das Plugin braucht einen bestimmten Paket­manager der Web-Entwicklung. Wer mit dem Standard arbeitet, muss kurz nach­installieren. Eine Zeile auf der Kommando­zeile, danach ist es da. Zweitens: eine Konfigurations­datei des Plugins muss vor dem ersten Start einmal angepasst werden, weil die mit­gelieferten Werte nur Platz­halter sind. Wer das übersieht, bekommt eine Fehler­meldung, die nicht selbst­erklärend ist. Drittens: bei sehr großen Projekten kann es passieren, dass das Werkzeug einzelne Dateien beim ersten Lauf übergeht. Es gibt einen Mechanismus zum Nachholen — man muss ihn nur kennen.

Wer das vorher weiß, ist nach einer Stunde produktiv. Wer es nicht weiß, verliert wahrscheinlich einen halben Vormittag. Die Doku im Plugin-Repo ist solide, aber nicht im Vordergrund — Hinweise zu den drei Punkten finden sich, man muss sie suchen. Mein Tipp: vor dem ersten Lauf einmal komplett die Installations­anweisungen durchgehen, dann ist die Stunde Investition planbar.