Fremde Codebase verstehen: Mit KI in Stunden statt Wochen

Sich in eine fremde Codebase einzuarbeiten war jahrelang eine Frage von Wochen — mit einem KI-Assistenten, der das ganze Repo lesen kann, ist es eine Frage von Stunden. Vorausgesetzt, du gehst systematisch vor, statt planlos Fragen in einen Chat zu tippen.

Ich übernehme regelmäßig fremde Projekte: Kunden-Codebases, die jemand anderes gebaut hat, Legacy-Systeme, offene Repos, zu denen ich beitragen will. Der Workflow, den ich dabei entwickelt habe, hat meine Einarbeitungszeit drastisch verkürzt. Hier ist er Schritt für Schritt — inklusive der Stellen, an denen KI dich in die Irre führt.

Warum der alte Weg so langsam war

Klassisches Codebase-Onboarding lief so: README lesen (veraltet), durch Ordner klicken, Einstiegspunkt suchen, Aufrufketten von Hand verfolgen, Kollegen mit Fragen löchern — falls es welche gibt. Das Kernproblem: Du musst Code linear lesen, aber Verständnis entsteht aus Zusammenhängen. Die Frage “Wo wird eine Bestellung storniert und was passiert dann alles?” zwingt dich durch fünf Dateien, drei Indirektionen und einen Event-Bus.

Genau diese Zusammenhangs-Fragen sind die Stärke von KI-Tools mit Repo-Zugriff — Claude Code, Cursor und ähnliche Agents durchsuchen den Code selbstständig, verfolgen Referenzen und fassen Ketten zusammen. Sie lesen schneller quer, als du scrollen kannst. Aber der Nutzen hängt komplett davon ab, welche Fragen du stellst und in welcher Reihenfolge.

Phase 1: Die Landkarte (30 Minuten)

Bevor du irgendeine Detailfrage stellst, verschaffst du dir das Großbild. Meine Standard-Prompts für den Einstieg:

• “Gib mir einen Überblick über dieses Repo: Was macht die Anwendung, welche Haupttechnologien, wie ist der Code organisiert?”
• “Was sind die Einstiegspunkte? Wo startet die Anwendung, welche Prozesse/Services gibt es?”
• “Zeig mir das Datenmodell: die wichtigsten Entitäten und ihre Beziehungen.”
• “Welche externen Abhängigkeiten gibt es — Datenbanken, APIs, Queues, Cron-Jobs?”

Wichtig dabei: Lass dir die Antworten mit Dateipfaden belegen und öffne die genannten Dateien stichprobenartig selbst. In dieser Phase geht es nicht um Details, sondern darum, eine mentale Landkarte zu bauen, gegen die du alles Weitere einordnest. Ich schreibe die Erkenntnisse in eine eigene Notiz-Datei — nicht weil die KI sie vergisst, sondern weil ich sie sonst vergesse.

Phase 2: Den Kern-Flow einmal komplett verfolgen (1–2 Stunden)

Jede Anwendung hat einen Flow, der ihr Herz ist: die Bestellung im Shop, der Trade in der Trading-App, der Upload im Dokumenten-Tool. Diesen einen Flow lässt du dir End-to-End erklären: vom HTTP-Request über Validierung, Business-Logik, Datenbank-Writes bis zu Events und Nebenwirkungen.

Hier kommt der wichtigste Trick des ganzen Workflows: Stell Verifikationsfragen. Lass dir nicht nur erzählen, wie es funktioniert — lass dir die konkreten Codezeilen zeigen und prüfe an zwei, drei Stellen nach, ob die Erzählung stimmt. LLMs produzieren bei Architektur-Fragen gelegentlich plausible Geschichten, die im Detail falsch sind: eine Middleware, die es so nicht gibt, ein Event-Handler, der längst tot ist. Wenn die Landkarte stimmt, sind Detailfehler harmlos; wenn du sie ungeprüft übernimmst, baust du dein ganzes Verständnis auf Sand.

Ein zweiter Kniff: Frag nach dem, was fehlt. “Welche Fehlerfälle behandelt dieser Flow nicht?” und “Wo würde dieser Code bei hoher Last brechen?” liefern oft mehr Einsicht als zehn Wie-funktioniert-das-Fragen.

Phase 3: Geschichte und Eigenheiten ausgraben

Code sagt dir, was ist — nicht warum. Für das Warum kombinierst du KI mit Git-Historie:

• “Fasse die Commit-Historie der Datei X zusammen: Was wurde wann grundlegend geändert?”
• “Dieses Modul wirkt inkonsistent zum Rest — gibt es Hinweise, dass hier mal ein anderer Ansatz verfolgt wurde?”
• “Suche nach TODO, FIXME, HACK und auskommentierten Blöcken und fasse zusammen, wo die Leichen liegen.”

Gerade übernommene Kundenprojekte haben fast immer solche Sedimentschichten: der halbfertige Umbau auf ein neues Auth-System, die zwei parallelen Wege, Mails zu versenden, der Feature-Flag, der seit einem Jahr auf “temporär” steht. Diese Stellen zu kennen, bevor du etwas änderst, bewahrt dich vor den klassischen Woche-eins-Unfällen.

Phase 4: Verständnis durch kontrollierte Eingriffe testen

Lesen allein erzeugt Scheinverständnis. Der Test ist immer ein Eingriff: Nimm dir eine kleine, echte Aufgabe — einen Mini-Bug, eine Textänderung, ein Log-Statement an der richtigen Stelle — und setz sie um. Dabei merkst du sofort, ob deine Landkarte trägt: Findest du die richtige Stelle auf Anhieb? Läuft das Projekt lokal überhaupt? Funktionieren die Tests?

Mit KI kannst du diesen Schritt absichern: “Ich will X ändern — welche Stellen sind betroffen und welche Nebenwirkungen sind zu erwarten?” Die Antwort gleicht du mit deiner eigenen Einschätzung ab. Wo beide übereinstimmen, sitzt dein Verständnis. Wo nicht, hast du deine nächste Lernstelle gefunden.

Die Grenzen, die du kennen musst

Damit das nicht nach Wundermittel klingt, die ehrlichen Einschränkungen aus der Praxis:

• Kontextfenster sind endlich. Bei großen Monoliths sieht das Tool nie alles gleichzeitig; es arbeitet mit Suche und Ausschnitten. Querbeziehungen zwischen weit entfernten Modulen übersieht es dadurch systematisch häufiger als lokale Details.
• Laufzeitverhalten bleibt unsichtbar. Race Conditions, echte Datenverteilungen, Performance unter Last, historisch gewachsene Produktionsdaten — davon weiß die KI nichts. Ein Blick in Logs, Metriken und die echte Datenbank ersetzt sie nicht.
• Konfiguration und Infrastruktur lügen gern. Welche Env-Variablen in Produktion wirklich gesetzt sind, welcher Cron wirklich läuft, steht selten im Repo. Hier hilft nur Zugriff auf die echte Umgebung.
• Menschen bleiben die beste Quelle für Politik. Warum eine Entscheidung so fiel, welche Bereiche heilig sind, wo ein Umbau schon zweimal gescheitert ist — das steht in keiner Datei.

Fazit: Der Workflow in einer Zeile

Landkarte bauen, Kern-Flow verifiziert durchsteigen, Geschichte ausgraben, Verständnis mit einem kleinen Eingriff testen — und jede KI-Aussage über Architektur einmal am echten Code gegenprüfen. Damit bist du in einer fremden Codebase nach ein, zwei Tagen handlungsfähig, wofür früher Wochen draufgingen. Die gesparte Zeit steckst du in das, was KI dir nicht abnimmt: Urteilsvermögen darüber, was der Code sein sollte.

Wenn du wissen willst, wie andere Devs ihre KI-Workflows aufgebaut haben: Im Discord der Community tauschen wir konkrete Setups und Prompts aus.