Ein lokales Codegraph-Werkzeug bauen, das KI-Agenten abfragen können

## Den Codegraphen lokal aus Syntaxbäumen statt aus KI-Zusammenfassungen erstellen Halten Sie die Projektanalyse lokal und deterministisch. Leiten Sie Symbole, Beziehungen und Dateien aus Syntaxbäumen statt aus Zusammenfassungen eines Sprachmodells ab, speichern Sie den projektbezogenen Zustand in einer lokalen indizierten Datenbank und stellen Sie den daraus entstehenden Wissensgraphen über eine Bibliothek, eine Befehlszeilenschnittstelle oder ein Agentenprotokoll bereit. Gliedern Sie das System als mehrschichtige Verarbeitungskette: - Die Extraktion analysiert Quellcode und erzeugt kanonische Symbole; - die Beziehungsauflösung verbindet Importe, Namen, Frameworks und weitere Beziehungen; - Graphabfragen beantworten Fragen zu Aufrufern, Aufrufzielen, Pfaden und Auswirkungen; - die Kontextformatierung bereitet kompaktes Markdown oder JSON für die nutzenden Systeme vor. Führen Sie aufwendige Analysen nicht im Hauptthread aus. Leiten Sie alle Schichten durch einen einzigen öffentlichen Einstiegspunkt und machen Sie ihn zur einzigen unterstützten Bibliotheksschnittstelle. Wenn eine ausführbare Datei bewusst zugleich als Installationsprogramm, Indexierungsprogramm und Protokollserver dient, testen Sie alle Rollen mit demselben Artefakt. Bewahren Sie eine einzige maßgebliche Quelle für die agentenseitige Werkzeuganleitung, vorzugsweise die Initialisierungsantwort des Protokolls. Duplizieren Sie dieselben Anweisungen nicht in der Repositorydatei jedes Clientprogramms, da die Kopien auseinanderdriften und Aktualisierungen oder die Deinstallation unvollständig machen. ## Die Laufzeitversion festlegen und Dateien ohne Code mit in den Build packen Ermitteln und verwenden Sie die dokumentierten Erstellungs-, Entwicklungs-, Bereinigungs-, Test-, Bewertungs- und lokalen CLI-Befehle des Repositorys. Halten Sie den festgeschriebenen Bereich der Laufzeitumgebung ein und lassen Sie Ausführungen außerhalb dieses Bereichs eindeutig fehlschlagen; eine neuere Hauptversion ist nicht automatisch kompatibel, und die Ausführung aus dem Quellcode kann eine strengere Mindestversion erfordern als eine gebündelte Auslieferung. Behandeln Sie Laufzeitressourcen als Bestandteil des Erstellungsvertrags. Kopieren Sie Datenbankschemata, Parsergrammatiken, WebAssembly-Module und andere Dateien ohne Programmcode in das Auslieferungspaket. Aktualisieren Sie bei jeder neuen Ressource den Kopierschritt, andernfalls wird sie nicht ausgeliefert. Beginnen Sie die Überprüfung mit einer gezielten Testdatei oder einem Namensmuster und führen Sie anschließend die direkt betroffene Testreihe aus. Halten Sie Bewertungsreihen getrennt, wenn sie Testaufbauten erzeugen oder Verhalten bewerten, statt gewöhnliche Komponententests auszuführen. Nutzen Sie das tatsächliche Speicherverhalten, wenn dessen Semantik wichtig ist. Erstellen Sie voneinander getrennte temporäre Verzeichnisse, räumen Sie sie nach jedem Test auf und prüfen Sie den wirklichen Datenbankmodus, statt ihn mit Simulationen zu verdecken. ## Knoten- und Kantentypen vereinheitlichen und die öffentliche API klein halten Definieren Sie kanonische Knoten- und Kantenarten in einem einzigen Schema. Extraktoren und Auflöser müssen genau diese Zeichenfolgen erzeugen; führen Sie keine nahezu gleichen Varianten ein, die Abfragen, Durchläufe oder serialisierte Daten unbemerkt aufteilen. Halten Sie die öffentliche API schmal. Exportieren Sie unterstützte Typen erneut über den öffentlichen Einstiegspunkt und verpflichten Sie Befehlszeilen- und Protokolladapter dazu, denselben Kerndienst zu verwenden, statt ihn zu umgehen. Formulieren Sie Aussagen zur Speicherung ausdrücklich und überprüfbar. Wenn das Produkt nur ein unterstütztes Datenbank-Backend mit Write-Ahead-Logging und Volltextsuche besitzt, melden Sie dieses tatsächlich aktive Backend, halten Sie jeden Kompatibilitätsadapter schlank und erwecken Sie nicht den Eindruck einer nicht implementierten nativen oder WebAssembly-Ausweichlösung. Wenn Sie eine Sprache, ein Framework, eine Abfrage oder ein Schemafeld hinzufügen, aktualisieren Sie den zuständigen Extraktor oder Auflöser, den öffentlichen Vertrag, die Serialisierung, die Tests und die Anleitung für Nutzende gemeinsam. ## In mehrere KI-Clients installieren, ohne Einstellungen zu zerstören, und sauber deinstallieren Modellieren Sie jedes unterstützte Clientprogramm als Ziel mit eigenem Konfigurationsort, Format und eigenen Protokollargumenten. Fügen Sie ein neues Clientprogramm über eine Zielimplementierung und einen Registereintrag hinzu, statt Bedingungen im gesamten Installationsprogramm zu verteilen. Bearbeiten Sie Konfigurationen gezielt. Bewahren Sie nicht zugehörige TOML-Tabellen und -Listen, erhalten Sie Formatierung und Kommentare von JSON mit Kommentaren, bevorzugen Sie eine vorhandene unterstützte Dateivariante und erstellen Sie den dokumentierten Standard nur bei einer Neuinstallation. Die Installation muss idempotent sein, eine erneute Installation muss einen unvollständigen Zustand selbst reparieren, und die Deinstallation darf nur Änderungen rückgängig machen, die dem Installationsprogramm gehören. Entfernen Sie veraltete Anweisungsblöcke mithilfe stabiler Markierungen, bewahren Sie die aktuelle Agentenanleitung jedoch in ihrer einzigen Quelle zur Laufzeit, statt eine weitere Kopie zu schreiben. Decken Sie jedes Ziel mit parametrisierten Vertragstests für die Bewahrung benachbarter Einstellungen, bytegleiche Wiederholungen, umkehrbare Deinstallation und Wiederherstellung aus unvollständigen Zuständen ab. Erhalten Sie Client-spezifische Korrekturen des Arbeitsverzeichnisses, etwa das Einfügen eines ausdrücklichen Projektpfads, wenn ein Clientprogramm Protokoll-Unterprozesse aus dem falschen Verzeichnis startet. ## Die Suchwerkzeuge verbessern, die Agenten schon nutzen Prüfen Sie vor dem Bau einer Abruffunktion, ob sie einem bereits vom Agenten aufgerufenen Werkzeug ermöglicht, mit den bereits gelieferten Eingaben mehr zu leisten. Verlassen Sie sich nicht darauf, dass der Agent ein neues Werkzeug erlernt, einen anderen Abfragestil übernimmt oder wenig auffällige Beispiele und Initialisierungstexte bemerkt. Verwenden Sie präzise Eingaben für präzise Antworten. Ein zentrales Erkundungswerkzeug soll eine kompakte Menge von Symbolnamen einschließlich qualifizierter Namen annehmen und den Ablauf zwischen ihnen verbinden. Ein ergänzendes Knotenwerkzeug soll den vollständigen Quellcode samt Kontext der Aufrufer und Aufrufziele zurückgeben; ist ein Name mehrdeutig, soll es alle plausiblen Überladungen in einer Antwort liefern. Integrieren Sie präzise Ablaufantworten nicht in ein unscharfes natürlichsprachliches Werkzeug, das die Endpunkte nicht unterscheiden kann. Verbessern Sie die Abdeckung innerhalb der Werkzeuge, die Agenten bereits auswählen, einschließlich statischer Extraktion und beweisgestützter dynamischer Beziehungen. Optimieren Sie die tatsächliche Laufzeit und die Anzahl der Werkzeugaufrufe ebenso wie den Tokenverbrauch. Messen Sie den Gesamtverbrauch über alle Gesprächsrunden und nicht nur die letzte Antwort, denn die Einsparung entsteht durch weniger Runden mit einem kleineren angesammelten Kontext. ## Antworten liefern, damit Agenten nicht zum direkten Lesen von Dateien zurückkehren Geben Sie erwartete Zustände in Erfolgsform zurück. Ein nicht indiziertes Projekt, ein fehlendes Symbol oder eine Datei außerhalb des Index soll umsetzbare Hinweise ohne Fehlerkennzeichnung liefern. Reservieren Sie echte Fehler für Sicherheitsablehnungen und tatsächliche Fehlfunktionen und fügen Sie nur dann eine begrenzte Wiederholungsanweisung hinzu, wenn ein erneuter Versuch sinnvoll ist. Stellen Sie die Werkzeugschnittstelle auch dann bereit, wenn das aktuelle Stammverzeichnis nicht indiziert ist. Erklären Sie die Auswahl eines indizierten Projekts, überlassen Sie die Indizierung jedoch dem Nutzer. Das Ausblenden von Werkzeugen beim Start kann Repositorys mit mehreren Projekten und Sitzungen beschädigen, die vor der Indizierung begonnen haben. Steigern Sie sowohl die Budgets für Erkundungsaufrufe als auch die Ausgabebudgets monoton mit der Größe des Repositorys: - weniger als 500 Dateien: 1 Aufruf, etwa 18.000 Zeichen und 3.800 Zeichen je Datei; - 500–4.999 Dateien: 2 Aufrufe, etwa 28.000 Zeichen und 6.500 Zeichen je Datei; - 5.000–14.999 Dateien: 3 Aufrufe, etwa 35.000 Zeichen und 7.000 Zeichen je Datei; - 15.000–24.999 Dateien: 4 Aufrufe, etwa 38.000 Zeichen und 7.000 Zeichen je Datei; - 25.000 Dateien oder mehr: höchstens 5 Aufrufe, etwa 38.000 Zeichen und 7.000 Zeichen je Datei. Eine größere Stufe darf niemals ein geringeres Budget je Datei erhalten als eine kleinere Stufe. Fordern Sie den Agenten niemals auf, zum direkten Lesen von Dateien zurückzukehren; leiten Sie ihn zu einem weiteren Graphaufruf und erklären Sie, dass der zurückgegebene Quellcode als bereits gelesen zu behandeln ist. ## Abläufe über Callbacks und Events von Anfang bis Ende verbinden Die statische Analyse übersieht Rückruffunktionen, Beobachter, Ereignisverteiler, reaktive Darstellung, Deskriptoren und andere indirekte Aufrufweiterleitungen. Fügen Sie eng begrenzte Synthesekomponenten oder Framework-Auflöser nur hinzu, wenn sie den kanonischen Ablauf mit belastbaren Nachweisen verbinden können. Kennzeichnen Sie jede synthetisch erzeugte Kante als heuristisch, halten Sie den erzeugenden Mechanismus fest und nehmen Sie die Registrierungs- oder Verbindungsstelle auf. Zeigen Sie diesen Herkunftsnachweis zusammen mit dem Ablauf, damit Nutzende analysierte Fakten von erschlossenen Beziehungen unterscheiden können. Teilweise Abdeckung ist schlechter als keine, wenn sie einen indirekten Übergang zeigt, aber die nächste Grenze unterbrochen lässt. Schließen Sie den Ablauf von der auslösenden Aktion bis zu ihrer sichtbaren Wirkung, messen Sie den Agenten erneut und liefern Sie keinen nur halb verbundenen Pfad aus, der weiterhin eine manuelle Rekonstruktion erzwingt. Bevorzugen Sie an Grenzen der Laufzeitumgebung, die sich nicht sicher erschließen lassen, Schweigen gegenüber einer falschen Kante. Prüfen Sie, dass eine erneute Indizierung die Knotenzahl nicht aufbläht, und kontrollieren Sie die Genauigkeit synthetischer Kanten stichprobenartig, bevor Sie einen Auflöser erweitern. ## Das Verhalten der Agenten mit echten Repositorys unter Windows und Linux prüfen Testen Sie für jede Sprache und jedes Framework kleine, mittlere und große reale Repositorys mit mindestens 3 verschiedenen Ablauffragen. Wählen Sie für jedes Framework einen kanonischen durchgängigen Ablauf statt einzelner Symbole, die seine schwierigen Grenzen der Aufrufweiterleitung umgehen. Führen Sie deterministische Prüfungen am erstellten Artefakt aus. Bestätigen Sie, dass die Erkundung die erwarteten Endpunkte innerhalb des Budgets verbindet, die Knotenzahl bei erneuter Indizierung stabil bleibt und heuristische Kanten einen genauen Herkunftsnachweis tragen. Führen Sie Agenten-A/B-Tests mit demselben bewusst gewählten Mindestleistungsmodell und demselben Schlussfolgerungsaufwand mindestens 2-mal je Versuchsgruppe aus. Erfassen Sie Dauer, Gesamtzahl der Werkzeugaufrufe, direkte Dateizugriffe und Textsuchen; berichten Sie Spannweiten statt eines günstigen Einzelversuchs. Wärmen Sie einen dauerhaften Protokollprozess vor, wenn die Startverzögerung das Werkzeug sonst verbergen würde, und beurteilen Sie die Verbindung anhand tatsächlicher Aufrufe statt einer Initialisierungsaufnahme. Verlangen Sie innerhalb des Erkundungsbudgets des Repositorys annähernd null direkte Dateizugriffe und Suchen, einen schnelleren Abschluss als bei der Kontrollgruppe und keine Verschlechterung in einem Kontroll-Repository. Prüfen Sie plattformspezifisches Verhalten auf der wirklichen Plattform. Schalten Sie Windows-spezifische und Nicht-Windows-Prüfungen ausdrücklich plattformabhängig und führen Sie sie jeweils nur auf der passenden Plattform aus. Erstellen Sie unter Linux mit frischen plattformspezifischen Abhängigkeiten in einem kurzlebigen Container und verwenden Sie einen init-Prozess, damit beendete Kindprozesse aufgeräumt werden. Verwenden Sie unter Windows ein lokales Dateisystem und frische Abhängigkeiten in einer echten virtuellen Maschine; vergleichen Sie verdächtige Fehler mit dem Standardzweig, bevor Sie eine Ursache zuweisen. ## Release Notes schreiben und das Veröffentlichen dem automatischen Release-Ablauf überlassen Tragen Sie bevorstehende Änderungen in einen Abschnitt Unreleased ein. Erstellen Sie den nächsten Versionsblock nicht vorab, wenn der Veröffentlichungsablauf den Inhalt von Unreleased automatisch übernimmt. Gestalten Sie Veröffentlichungshinweise für Nutzende hilfreich: - Ordnen Sie Inhalte nur bei Bedarf unter nutzerorientierten Überschriften für neue Funktionen, Korrekturen, Sicherheit oder inkompatible Änderungen ein; - erklären Sie in jedem Aufzählungspunkt mit einem leicht verständlichen Satz die Funktion oder das behobene Symptom; - lassen Sie interne Pfade, Implementierungssymbole, Einzelheiten zu Leistungsmessungen und leere Abschnitte weg; - behalten Sie nützliche Ticketverweise, Namen unterstützter Plattformen und Befehle bei, die Nutzende tatsächlich eingeben. Lassen Sie den automatisierten Veröffentlichungsablauf die Versionen der Sperrdatei abgleichen, das Änderungsprotokoll übernehmen, Plattformpakete erstellen, Prüfsummen erzeugen sowie die Veröffentlichung und die Pakete bereitstellen. Erhöhen Sie Versionen nur nach ausdrücklicher Aufforderung und stellen Sie Pakete nicht manuell bereit, übertragen Sie keine Veröffentlichungs-Commits und erstellen Sie keine Tags, wenn diese Schritte dem Ablauf gehören. Verankern Sie ein Ticket, einen Prüfkommentar oder einen externen Bericht vor jeder Reaktion an einem Datum und vergleichen Sie den veröffentlichten Stand, den zusammengeführten, aber noch nicht veröffentlichten Stand und den aktuellen Zweig. Schreiben Sie eine laufende Korrektur nicht dem Stand zu, den der Meldende zuvor sehen konnte. Behandeln Sie Produktanforderungen als Entscheidungen der Nutzenden und nicht als Fakten, die aus dem Codegraphen abgeleitet werden. Versehen Sie jede Bild-URL der Dokumentation mit einer Version und erhöhen Sie ihre Abfragekennung bei jeder Änderung der Ressource, damit Zwischenspeicher nicht weiterhin veraltete Daten ausliefern.