Semantische KI-Suche über 46 Code-Repositories – so funktioniert die Lösung

Ryan Tsui, CTO von airCloset, stand vor einem scheinbar unlösbaren Problem: Wie macht man den Inhalt von 46 Code-Repositories nicht nur technisch durchsuchbar, sondern auch semantisch verständlich für KI-Systeme? Die naheliegende Lösung – jede Funktion manuell zu dokumentieren – wäre schlichtweg undurchführbar gewesen. Doch mit einem cleveren Mix aus statischer Analyse, vektorbasierter Suche und präzisen Annotationen an den Schnittstellen gelang es, ein funktionierendes Wissensnetzwerk zu schaffen. Dieser Ansatz könnte die Art und Weise, wie Entwicklerteams mit großen Codebasen interagieren, grundlegend verändern.

Warum semantische Suche für KI-Systeme unverzichtbar ist

In einem ersten Schritt hatte Tsui bereits ein statisches Wissensnetzwerk aus 46 Repositories erstellt, das Funktionen, Klassen und Schnittstellen verbindet. Doch dieses Netzwerk war für KI-Systeme zunächst nutzlos, weil es keine semantische Suche ermöglichte. Ohne natürliche Spracheingaben wie „Finde alle Funktionen, die den Mietstatus eines Benutzers aktualisieren“ musste die KI auf Inferenzen zurückgreifen – und das widersprach dem Grundprinzip: „Gib der KI verifizierte Fakten, keine Spekulationen.“

Die Lösung lag nicht in der Erweiterung des Netzwerks, sondern in der Anreicherung mit Kontext. Inspiriert von einem früheren Projekt, das Datenbanktabellen semantisch durchsuchbar machte, übertrug Tsui diesen Ansatz auf den Code. Das Ergebnis: Eine KI kann nun gezielt nach funktionalen Zusammenhängen fragen, ohne den gesamten Code manuell analysieren zu müssen.

Drei Graphen, ein Ziel: Ein nahtloses Wissensnetzwerk

Tsui kombinierte drei separate Graphen zu einem kohärenten System, das als Service-Produkt-Graph (SPG) bezeichnet wird. Jeder Graph erfüllt eine spezifische Rolle, bleibt aber durch gemeinsame Knotenpunkte miteinander verknüpft:

• code-graph (Struktur): Enthält alle Funktionen, Klassen und Schnittstellen aus den 46 Repositories, die durch statische Analyse extrahiert wurden. Boundary-Knoten wie API-Endpunkte oder Datenbankzugriffe sind hier bereits als logische Schnittstellen definiert.

• db-graph (Datenbankkontext): Beschreibt 1.133 Tabellen mit 10.815 Spalten semantisch – ähnlich wie in Tsus früherem Projekt. Dieser Graph liefert den Kontext für Datenbankoperationen, ohne dass Entwickler Tabellennamen kennen müssen.

• annotation-graph (Intent): Enthält gezielte Annotationen an den Schnittstellen des Codes. Hier wird nicht jede Funktion dokumentiert, sondern nur diejenigen, die für die Interaktion mit anderen Systemen oder Benutzeroberflächen relevant sind. Die Annotationen folgen einem klaren Schema, das in den Code eingebettet wird.

Die Verbindung dieser Graphen erfolgt über SAME_ENTITY-Kanten, sodass eine KI von jedem Ausgangspunkt aus das gesamte Netzwerk durchsuchen kann. Ein zentraler MCP-Server agiert als Vermittler und ermöglicht es KI-Systemen, auf die verschiedenen Graphen zuzugreifen, ohne direkten Zugriff auf den db-graph zu benötigen.

Annotationen als Schlüssel zur semantischen Suche

Die größte Herausforderung bestand darin, den Code mit semantischem Kontext zu versehen, ohne jede Funktion manuell zu dokumentieren. Tsui löste dieses Problem mit einem minimalistischen Ansatz: Annotationen werden ausschließlich an den Boundary-Knoten gesetzt – also an Schnittstellen wie APIs, Events oder Benutzeroberflächen. Das reicht aus, um der KI die notwendigen Informationen zu liefern.

Ein Beispiel für eine solche Annotation (fiktiv, aber realitätsnah) könnte so aussehen:

/**
 * @graph-page /home
 * @graph-business Hauptbildschirm. Mitglieder sehen ihre aktuellen Mietgegenstände, können Artikel kaufen oder Rückgaben einleiten.
 * @graph-label Home Screen
 * @graph-has-section banners, wearing-items, wearing-return, delivery-status
 * @graph-has-dialog buying-modal, return-modal
 * @graph-navigates-to /return-procedure, /checkout, /my-karte
 * @graph-calls GET /api/v1/wearing
 * @graph-reads admin_delivery_orders, admin_rental_items
 * @graph-flow styling-loop
 * @graph-status monthly-member
 */

Hier sind zwei Elemente entscheidend:

• `@graph-business` enthält den eigentlichen Intent-Text, der später vektorbasiert durchsuchbar gemacht wird. In Tsus Team wird dieser Text auf Japanisch verfasst, um die natürliche Sprache der Entwickler zu nutzen.

• `@graph-flow` und `@graph-status` beschreiben den geschäftlichen Kontext oder den Zustand, in dem sich eine Funktion befindet. Diese Metadaten helfen der KI, den Zweck einer Funktion besser zu verstehen.

Durch diesen gezielten Einsatz von Annotationen wird vermieden, dass Entwickler Tausende von Funktionen manuell dokumentieren müssen. Stattdessen reicht es aus, die Schnittstellen zu kennzeichnen – und schon wird der Code semantisch durchsuchbar.

Grenzen und nächste Schritte

Tsui betont, dass der Service-Produkt-Graph zwar die semantische Suche ermöglicht, aber noch nicht alle ursprünglichen Probleme gelöst hat. Die verbleibenden Herausforderungen umfassen:

• Explosionsgefahr des Graphen: Durch die Verbindung vieler Repositories könnte das Netzwerk unüberschaubar groß werden.
• Kosten neuer Parser: Jede neue Boundary-Pattern erfordert Anpassungen der statischen Analyse.
• Funktionsdokumentation: Bisher wurden nur Boundary-Knoten annotiert – die innere Logik der Funktionen bleibt weiterhin undokumentiert.

Tsui plant, diese Themen in zukünftigen Beiträgen zu vertiefen. Sein Fokus liegt darauf, das System weiter zu automatisieren, um die manuelle Pflege auf ein Minimum zu reduzieren. Langfristig könnte dieser Ansatz nicht nur die Arbeit von Entwicklern erleichtern, sondern auch die Zusammenarbeit zwischen KI-Systemen und menschlichen Teams revolutionieren.

Der nächste logische Schritt wäre die Integration des Systems in bestehende Entwicklungsumgebungen, sodass Annotationen direkt im Code-Editor vorgenommen werden können. So ließe sich der Service-Produkt-Graph noch nahtloser in den Arbeitsalltag einbinden – und die semantische Suche würde zu einem Standardwerkzeug für jedes größere Softwareprojekt.