KI-gestützte Architektur-Entdeckung: Wie es funktioniert
Letztes Jahr habe ich eine Codebase ohne jegliche Dokumentation geerbt. 200.000 Zeilen Code über 15 Services verteilt, geschrieben von einem Team, das inzwischen weitergezogen war. Meine Aufgabe war es, sie gut genug zu verstehen, um eine neue Zahlungsintegration hinzuzufügen. Das Unternehmen schätzte, dass es 2-3 Wochen dauern würde, nur um die Architektur zu kartieren.
Diese Erfahrung ist der Grund, warum ich Archyls KI-Discovery-Funktion gebaut habe. Und jetzt, nachdem ich Monate damit verbracht habe, mit Large Language Models zur Codeanalyse zu arbeiten, möchte ich teilen, was wirklich funktioniert, was nicht, und warum KI-gestützte Architektur-Entdeckung mächtig aber nicht magisch ist.
Das Problem mit manueller Entdeckung
Bevor wir in KI eintauchen, lassen Sie uns anerkennen, warum wir das überhaupt brauchen.
Als ich mit dieser undokumentierten Codebase konfrontiert war, sah mein Entdeckungsprozess so aus:
Woche 1: Grep durch den Code auf der Suche nach Schlüsselwörtern. Die Haupteinstiegspunkte finden. Ein paar Kästen auf ein Whiteboard zeichnen. Realisieren, dass ich die Service-Grenzen falsch verstanden habe. Löschen und neu zeichnen.
Woche 2: Den einen Ingenieur interviewen, der lange genug dabei ist, um sich an etwas Geschichte zu erinnern. Die Hälfte von dem, was er mir erzählt, widerspricht dem, was ich im Code gefunden habe. Es stellt sich heraus, dass sich Dinge geändert haben, aber niemand sein mentales Modell aktualisiert hat.
Woche 3: Endlich das Gefühl haben, das System gut genug zu verstehen, um Änderungen vorzunehmen. Dokumentation erstellen, die ich schwöre, aktuell zu halten. (Spoiler: Habe ich nicht.)
Dieser Prozess ist langsam, fehleranfällig und skaliert nicht. Jedes neue Teammitglied durchläuft die gleiche schmerzhafte Entdeckung. Die Dokumentation veraltet innerhalb von Monaten.
Wie KI-Discovery tatsächlich funktioniert
Wenn Sie ein Repository mit Archyl verbinden und Discovery ausführen, passiert Folgendes unter der Haube:
Schritt 1: Repository-Scanning
Zuerst bauen wir eine Karte Ihrer Codebase. Das ist noch keine KI — es ist einfaches Dateisystem-Traversieren:
- Alle Dateien und Verzeichnisse auflisten
- Konfigurationsdateien identifizieren (package.json, go.mod, docker-compose.yml)
- Einstiegspunkte finden (main-Funktionen, index-Dateien, API-Routen)
- Einen Abhängigkeitsgraphen aus den Imports bauen
Das gibt uns das Skelett. Wir wissen, welche Dateien existieren und wie sie sich gegenseitig referenzieren. Aber wir verstehen noch nicht, was sie tun.
Schritt 2: Chunk-basierte Analyse
Hier kommen LLMs ins Spiel, und auch hier wird es knifflig.
Moderne Sprachmodelle haben Kontextgrenzen. GPT-4 kann etwa 128K Tokens verarbeiten, Claude kann 200K. Das klingt nach viel, aber eine mittelgroße Codebase überschreitet das leicht. Also können wir nicht einfach die gesamte Codebase in einen Prompt werfen und fragen "was ist das?"
Stattdessen teilen wir die Codebase in verdauliche Stücke:
- Dateien nach Verzeichnis oder Modul gruppieren
- Jeden Chunk an das LLM mit Kontext über seinen Standort im Projekt senden
- Das Modell bitten zu identifizieren: Wofür ist dieser Code verantwortlich? Welche Muster verwendet er? Mit welchen externen Systemen interagiert er?
Die Antworten kommen als strukturierte Daten zurück — JSON, das Systeme, Container und Komponenten mit ihren Beziehungen beschreibt.
Schritt 3: Aggregation und Abstimmung
Das ist der schwierigste Teil, und wo ich die meiste Entwicklungszeit verbracht habe.
Jede Chunk-Analyse gibt uns eine partielle Ansicht. Der User-Service-Chunk kennt die User-Datenbank. Der Payment-Chunk kennt Stripe. Aber keiner kennt das vollständige Bild.
Wir müssen diese partiellen Ansichten abstimmen:
- Doppelte Entitäten zusammenführen (Ist "UserDB" das gleiche wie "users_database"?)
- Beziehungen zwischen Chunks inferieren (der Order-Service ruft den User-Service auf, aber sie wurden separat analysiert)
- Konflikte lösen (ein Chunk sagt, wir verwenden PostgreSQL, ein anderer sagt MySQL — welcher hat Recht?)
Diese Abstimmung verwendet eine weitere Runde LLM-Analyse plus Heuristiken basierend auf gängigen Mustern. Es ist nicht perfekt. Manchmal liegt die KI falsch. Deshalb produziert Discovery Vorschläge, die Menschen überprüfen, keine finale Dokumentation.
Schritt 4: C4-Modell-Generierung
Schließlich mappen wir die entdeckten Entitäten auf C4-Modell-Elemente:
- Externe Systeme (Drittanbieter-APIs, Datenbanken, die wir nicht verwalten)
- Container (unsere deploybare Einheiten)
- Komponenten (Hauptmodule innerhalb von Containern)
- Beziehungen (wer ruft wen auf, welche Daten fließen wohin)
Das Ergebnis ist ein Satz von C4-Diagramm-Entwürfen, die das Verständnis der KI von Ihrer Architektur erfassen.
Was die KI gut macht
Nach dem Ausführen von Discovery auf Dutzenden von Codebases während der Entwicklung, hier ist, was mich beeindruckt hat:
Technologie-Stack-Erkennung
LLMs sind bemerkenswert gut darin zu identifizieren, welche Technologien ein Projekt verwendet. Sie erkennen Framework-Muster, Bibliotheks-Idiome und Konfigurationsdatei-Formate. Wenn GPT eine @Controller-Annotation sieht, weiß es, dass Sie Spring verwenden. Wenn es fiber.New() sieht, weiß es, dass Sie Go Fiber verwenden.
Service-Grenzen-Erkennung
In Microservice-Architekturen identifiziert die KI zuverlässig Service-Grenzen. Sie versteht, dass Code in /services/user/ wahrscheinlich ein separater Service von /services/order/ ist. Sie erkennt Docker Compose-Dateien als Indikatoren für Service-Topologie.
Erkennung gängiger Muster
Die KI hat Millionen von Codebases in ihren Trainingsdaten gesehen. Sie erkennt Repository-Muster, MVC-Strukturen, Event-Driven-Architekturen und API-Gateway-Setups. Wenn Ihr Code gängigen Mustern folgt, identifiziert die KI sie schnell.
Entdeckung externer Integrationen
Jede API-Key-Konstante, Webhook-URL oder SDK-Import ist ein Hinweis auf externe Integrationen. Die KI erfasst die meisten davon und baut ein Bild davon, von welchen Drittanbieter-Services Ihr System abhängt.
Was die KI falsch macht
Hier musste ich realistische Erwartungen setzen:
Benutzerdefinierte Geschäftslogik
Die KI versteht Ihre Geschäftsdomäne nicht. Sie kann erkennen, dass Sie eine processOrder-Funktion haben, aber sie weiß nicht, was "eine Bestellung verarbeiten" in Ihrem spezifischen Geschäftskontext bedeutet. Sie könnte den Zweck von domänenspezifischen Komponenten falsch identifizieren.
Ungewöhnliche Architekturen
Wenn Ihre Architektur nicht gängigen Mustern folgt, kämpft die KI. Ein benutzerdefiniertes Plugin-System, eine unkonventionelle Ordnerstruktur oder ein selbstgebautes Framework wird sie verwirren. Die KI erwartet, dass Rails-Apps wie Rails-Apps aussehen.
Versteckte Abhängigkeiten
Nicht alle Abhängigkeiten sind explizit im Code. Vielleicht erfordert Ihr Service eine bestimmte Version von Redis, die nur in der Produktion existiert. Vielleicht gibt es einen Sidecar-Container, den die KI nie sieht. Laufzeit-Abhängigkeiten sind oft unsichtbar für statische Analyse.
Veraltete Code-Pfade
Die KI weiß nicht, welcher Code aktiv genutzt wird versus welcher Legacy-Krempel ist, den niemand seit Jahren angefasst hat. Sie könnte einen veralteten Service prominent darstellen, der noch in der Codebase ist, aber nicht mehr deployt wird.
KI-Discovery besser machen
Durch Versuch und Irrtum habe ich Wege gefunden, die Genauigkeit der Discovery zu verbessern:
Kontext bereitstellen
Bevor Sie Discovery ausführen, erzählen Sie der KI von Ihrem System. "Dies ist eine E-Commerce-Plattform mit Zahlungsverarbeitung" gibt dem Modell einen Referenzrahmen. Ohne Kontext rät sie blind.
Mit Struktur beginnen
Wenn Sie vorhandene Dokumentation haben — auch nur ein README mit einer groben Architektur-Skizze — stellen Sie sie bereit. Die KI nutzt dies als Prior, um ihre Analyse zu leiten.
Inkrementell überprüfen
Führen Sie Discovery nicht auf Ihrer gesamten Codebase auf einmal aus. Beginnen Sie mit einem Service. Überprüfen und korrigieren Sie die Ergebnisse. Dann erweitern Sie auf den nächsten Service. Korrekturen, die Sie machen, informieren zukünftige Analysen.
Vertrauen aber verifizieren
Behandeln Sie KI-Vorschläge als Ausgangspunkt, nicht als finale Antwort. Die KI könnte 80% genau sein. Sie müssen die anderen 20% verifizieren. Klicken Sie in die Quellcode-Links, bestätigen Sie, dass die Beziehungen Sinn ergeben, und korrigieren Sie Fehler.
Die technischen Details
Für die Neugierigen zur Implementierung:
Chunking-Strategie
Wir verwenden semantisches Chunking anstelle von Chunks fester Größe. Ein Chunk ist typischerweise ein Modul, ein Service oder ein Verzeichnisbaum. Das hält zusammengehörigen Code zusammen, was das Verständnis der KI verbessert.
Prompt Engineering
Die Prompts haben sich erheblich weiterentwickelt. Frühe Versionen produzierten ausführliche, narrative Beschreibungen. Aktuelle Prompts verlangen strukturierte Ausgabe mit spezifischen Feldern. Wir verwenden Few-Shot-Beispiele, um das erwartete Format zu demonstrieren.
Parallelität
Große Codebases haben Tausende von Dateien. Sequenzielle Verarbeitung würde ewig dauern. Wir analysieren Chunks parallel, mit konfigurierbaren Parallelitätsgrenzen, um API-Rate-Limits zu vermeiden.
Modellauswahl
Verschiedene Modelle haben verschiedene Stärken. GPT-4 produziert genauere Analysen, kostet aber mehr. Claude ist besser darin, strukturierte Ausgabeanforderungen zu befolgen. Wir unterstützen beide, plus lokale Modelle über Ollama für Teams, die keinen Code an externe APIs senden können.
Die Zukunft der KI-gestützten Discovery
Was wir heute haben, ist Version 1. Hier ist, worauf ich hinarbeite:
Kontinuierliche Discovery
Anstelle von einmaliger Analyse, Ihre Codebase kontinuierlich überwachen. Wenn sich Code ändert, die relevanten Diagramme automatisch aktualisieren. Architektonische Drift erkennen, bevor es ein Problem wird.
Tieferes Verständnis
Die aktuelle Analyse ist hauptsächlich strukturell. Zukünftige Versionen könnten Verhalten verstehen: "Dieser Endpoint validiert Input, ruft den Payment-Service auf, sendet dann eine Bestätigungs-E-Mail." Sequenzdiagramme, generiert aus Code.
Repository-übergreifende Analyse
Die meisten Organisationen haben mehrere Repositories. Discovery sollte verstehen, wie sie sich verbinden — welche Services in Repo A Services in Repo B aufrufen.
Vertrauens-Scoring
Nicht alle Entdeckungen sind gleich sicher. Wir fügen Vertrauens-Scores hinzu, damit Sie wissen, welche Vorschläge Sie genauer prüfen sollten.
Fazit
KI-gestützte Architektur-Entdeckung ist keine Magie. Es ist ein Werkzeug, das die mühsamen Teile des Verstehens einer Codebase beschleunigt, während es immer noch menschliches Urteilsvermögen für die nuancierten Teile erfordert.
Wenn ich heute Discovery auf dieser 200K-Zeilen-Codebase ausführe, bekomme ich einen Architekturdiagramm-Entwurf in 10 Minuten statt 3 Wochen. Es ist nicht perfekt — ich muss es immer noch überprüfen und korrigieren. Aber es ist ein dramatisch besserer Ausgangspunkt als ein leeres Whiteboard.
Wenn Sie in undokumentiertem Code ertrinken, probieren Sie KI-Discovery. Gehen Sie mit realistischen Erwartungen hinein: Es wird Ihre Geschäftsdomäne nicht verstehen, es könnte ungewöhnliche Muster übersehen, und es erfordert definitiv menschliche Überprüfung. Aber es bringt Sie 80% des Weges in einem Bruchteil der Zeit.
Möchten Sie mehr erfahren? Schauen Sie sich unsere Einführung in das C4-Modell an, das KI-Discovery generiert, oder lesen Sie, warum Architekturdokumentation wichtig ist.