CodeBuddy: Intelligentere Kontextabrufung für KI-Programmieragenten
Erklärt, wie ein durch einen Abhängigkeitsgraphen gesteuertes System zur Kontextabrufung AI-Programmieragenten dabei hilft, sowohl einen Kontextmangel als auch eine Kontextüberlastung in großen Codebasen zu vermeiden.
Der übersehene Schmerzpunkt beim agilen Programmieren
Die Begeisterung für KI-basierte Programmieragenten ist durchaus berechtigt – Claude, Codex, Cursor und die anderen haben sich zu wirklich nützlichen Werkzeugen entwickelt. Doch wenn man länger als eine Woche damit verbringt, einen solchen Agenten auf eine große, reale Codebasis anzuwenden, taucht ein bekanntes Problem immer wieder auf.
Der Agent selbst ist nicht der begrenzende Faktor. Es sind nicht die Fähigkeiten des Modells, die versagen. Was versagt, ist der Kontext.
Zwei wiederkehrende Fehlermuster tauchen immer wieder auf:
- Dem Agenten zu wenig Kontext geben – man gibt ihm eine Aufgabe, und er hat keine Ahnung von den Konventionen des Projekts, kein Gedächtnis an ähnliche Fehler, die bereits behoben und anschließend wieder rückgängig gemacht wurden, und kein Verständnis dafür, welche Dateien von derjenigen abhängen, an der er arbeiten soll. Das Ergebnis sind Änderungen, die für sich genommen sinnvoll erscheinen, aber für das gesamte System falsch sind.
Niemand von beidem hat tatsächlich etwas mit der Intelligenz des Modells zu tun. Beides sind Symptome einer schlechten Kontextgestaltung. Das ist das eigentliche Problem, das CodeBuddy beheben will.
Als Workaround entstanden, nicht als geplantes Produkt
Lange bevor CodeBuddy als Tool existierte, wurde die Kernidee bereits manuell umgesetzt.
Jedes Mal, wenn in einem mit Claude erstellten Projekt eine echte Änderung vorgenommen werden musste, verlief der Ablauf stets gleich: Es wurden die relevanten Funktionen ausfindig gemacht, die Tests gesucht, die diesen Teil des Codes abdeckten, alle Notizen herangezogen, die erklärten, warum bestimmte Dinge auf diese Weise konstruiert worden waren, und all das wurde bereits vor der Beschreibung der Änderung in das Gespräch eingefügt. Das funktionierte zwar, war aber mühsam, repetitiv und hing vollständig davon ab, sich an den Codebase zu erinnern – eine Erinnerungskraft, die unweigerlich nachlässt, je größer das Projekt wird.
Irgendwann stellte sich die offensichtliche Frage: Warum übernahm ein Mensch die Aufgabe, den Kontext abzurufen? Das ist eine mechanische, wiederholbare Aufgabe. Sie gehört in die Automatisierung und nicht in den Kopf eines Menschen.
Darüber hinaus entstand CodeBuddy genau aus diesem Grund – nicht als Entscheidung, „ein KI-Entwicklertools“ zu bauen, sondern als Entscheidung, diese Abfragen nicht mehr manuell durchzuführen.
Der falsche Shortcut: Graphify vermeiden
Die Automatisierung dieses Abrufschritts erforderte die Entscheidung darüber, wie CodeBuddy die Struktur eines Projekts verstehen sollte – welche Dateien voneinander abhängen, was was aufruft und wo sich die tatsächlichen architektonischen Grenzen befinden.
Ein separates Projekt namens Graphify hat dieses Problem bereits angegangen, indem es ein echtes Abhängigkeitsdiagramm einer Codebasis erstellte und so die tatsächlichen Beziehungen zwischen Dateien darstellte, anstatt sie aus Namensmustern oder Nähe abzuleiten. Die Einbeziehung dieses Tools als Abhängigkeit erschien als unnötige Komplexität – ein weiterer beweglicher Bestandteil, ein weiterer Installationsschritt und ein weiterer potenzieller Fehlerpunkt. Der ursprüngliche Plan war, es ganz wegzulassen und stattdessen zu ermöglichen, dass CodeBuddy seinen eigenen leichten architektonischen Index mithilfe von Symbolextraktion, Dateiko-Occurrence und einigen Heuristiken erstellt – gerade genug, um den Agenten in eine vernünftige Richtung zu lenken.
Der Ansatz reichte nicht aus.
Der leichte Index konnte zwar anzeigen, was in der Nähe von was lag, doch er konnte nicht zuverlässig erklären, warum zwei Dateien tatsächlich miteinander verbunden waren, und er konnte keine Abhängigkeitskette von drei oder vier Ebenen nachverfolgen – genau die Art von Informationen, die am wichtigsten sind, bevor man Code mit weitreichenden Auswirkungen anfasst. Immer wieder vornahm das Tool Änderungen, die auf den ersten Blick sicher erschienen, aber etwas in einer tieferen Ebene beschädigten, einfach weil der Index diese Beziehung nicht mit ausreichender Präzision erfasst hatte.
Dies führte zu einer Umkehrung der Strategie. Anstatt Graphify als optionalen Zusatz, um den man sich kümmern musste, zu betrachten, wurde es zu einem Kernbestandteil des Systems: CodeBuddy funktioniert weiterhin eigenständig mit seinem internen Index für alle, die keine zusätzliche Einrichtung wünschen. Wenn jedoch Graphify installiert ist, bezieht sich CodeBuddy auf dessen Graph als autoritäre Quelle für architektonische Beziehungen, anstatt auf Vermutungen zu setzen.
Diese Richtungsänderung ist die eigentliche Geschichte hinter dem aktuellen Arbeitsablauf – nicht eine neu hinzugefügte Funktion, sondern die Erkenntnis, dass das einfachere Design tatsächlich schlechter war, gefolgt von einem Neuaufbau um genau jene Abhängigkeit, die ursprünglich vermieden werden sollte.
Wie CodeBuddy heute in der Praxis aussieht
1. Einrichten
npm install -g @ayushkumar320/codebuddy
codebuddy
Durch das Ausführen von codebuddy innerhalb eines Projekts werden die wenig ansprechenden, aber notwendigen Einrichtungsschritte abgewickelt:
- Verbindung zu einer lokalen PostgreSQL-Datenbank herstellen
- Anwendung des Schemas und der Einstellungen, die das jeweilige Projekt benötigt
- Erstellung einer privaten Konfigurationsdatei, die auf dieses Projekt beschränkt ist
- Integration mit Claude und Codex, wobei Anweisungen hinzugefügt werden, die dem Agenten zeigen, wie er die Tools von CodeBuddy nutzen kann
- Aufforderung, zu entscheiden, ob Graphify aktiviert werden soll
Durch Aktivierung von Graphify wird dessen MCP-Server verbunden, wodurch das Ausführen von /graphify . einmalig die anfängliche Architekturkarte des Projekts erstellt. Wenn man dies ablehnt, greift CodeBuddy auf seinen eigenen leichten Index zurück – das Tool funktioniert weiterhin vollständig, doch das entstehende Architekturbild ist weniger präzise.
2. Der Kernzyklus: context_pack
Hier findet die eigentliche Arbeit statt. Wenn man dem Agenten eine Aufgabe überlässt – zum Beispiel „OAuth-Anmeldung hinzufügen“ – beginnt er nicht damit, zufällig nach Dateien zu suchen oder den gesamten Repository-Ordner durchzusehen. Stattdessen ruft er CodeBuddys context_pack-Tool auf, das einen eng abgegrenzten Datensatz zusammenstellt, der Folgendes enthält:
- Die Dateien, die tatsächlich für die Aufgabe relevant sind
- Die spezifischen Funktionen und Klassen, anstatt ganzer Dateien, sofern dies vermeidbar ist
Dadurch entsteht ein kleines, dichtes Paket mit fokussiertem Inhalt anstelle eines umfangreichen, dünnen Pakets. Genau dieser Unterschied unterscheidet ein wirklich kontextbewusstes Verhalten von etwas, das nur so erscheint.
3. Der Agent implementiert die Änderung
Mit diesem Paket ausgestattet verfügen Claude oder Codex über genügend Informationen, um auch über die nachfolgenden Auswirkungen nachzudenken – und nicht nur über den unmittelbaren Unterschied – wie beispielsweise welche Aufrufer von dieser Funktion abhängen, welche Tests weiterhin bestehen müssen und ob bereits ein genau solcher Ansatz versucht und anschließend wieder rückgängig gemacht wurde.
4. CodeBuddy erinnert sich
Sobald die Aufgabe abgeschlossen ist, kann der Agent das Gelernte wieder in CodeBuddy eintragen: die getroffenen Entscheidungen, die im Laufe der Arbeit entdeckten Regeln, aufgetretene Regressionen sowie Ansätze, die sich als wirksam erwiesen haben. Dieses Wissen bleibt lokal gespeichert, aufgeteilt zwischen Postgres- und Markdown-Speicher, und wird in das Kontextpaket für die nächste verwandte Aufgabe integriert. Anstatt bei jeder Sitzung auf Null zurückzusetzen, wird das System immer präziser.
5. PRs werden automatisch überprüft
Ein GitHub-Workflow kann automatisch Berichte zu jeder Pull Request erstellen, wobei folgende Aspekte abgedeckt werden:
- Wie riskant der Änderungsvorschlag erscheint
- Wo die Testabdeckung fehlt
- Was die Änderung architektonisch betrifft
- Ob die Implementierung vom ursprünglichen Plan abgewichen ist
- Ob die Überprüfung tatsächlich erfolgreich war
Warum das wichtiger ist, als es auf den ersten Blick scheint
Es ist verlockend, dies als „ein weiteres Entwicklungswerkzeug rund um Claude“ abzutun. Diese Sichtweise übergeht jedoch einige Aspekte:
Es befasst sich mit dem eigentlichen Engpass. Modelle werden stetig leistungsfähiger. Die Qualität der ihnen zur Verfügung gestellten Kontexte hat auf Werkzeugebene nicht Schritt gehalten – die meisten Einrichtungen lesen weiterhin ganze Dateien oder nutzen Suchfunktionen in der Hoffnung auf das Beste. CodeBuddy basiert auf der Annahme, dass die nächsten bedeutenden Fortschritte im agilen Programmieren aus der Verbesserung dessen resultieren werden, was den Modellen zur Verfügung gestellt wird, und nicht vom Modell selbst.
Es entwickelt sich im Laufe der Zeit weiter. Ein Kontextfenster verfügt standardmäßig über kein Gedächtnis – jede Sitzung beginnt von vorne, es sei denn, das umgebende System bewahrt den Zustand absichtlich auf. Da CodeBuddy Entscheidungen, Regeln sowie Rückfälle verfolgt, sollte die zehnte Aufgabe in einer bestimmten Codebasis reibungsloser ablaufen als die erste, ohne dass Sie dieselben Dinge erneut erklären müssen.
Es ist ehrlich zu den Kompromissen, anstatt sie zu verschweigen. Die Möglichkeit, Graphify optional zu nutzen, ist eine direkte Reaktion auf einen früheren Versuch, diesen Kompromiss gänzlich zu beseitigen – was jedoch nicht funktionierte. Sie können selbst entscheiden: entweder ohne zusätzliche Einrichtung einen brauchbaren, leichten Index oder, wenn Sie bereit sind, ein wirklich präzises Architekturdiagramm, indem Sie einen weiteren Komponenten hinzufügen.
Alles bleibt auf Ihrem Rechner. PostgreSQL, der Markdown-Speicher, der interne Index sowie Graphifys Graph laufen alle lokal. Die Anmeldeinformationen befinden sich in einer privaten Konfigurationsdatei. Um den Kontext des Agents zu verbessern, muss Ihr Codebase nirgendwohin verschickt werden.
Es passt zu den Tools, die die Nutzer bereits verwenden. Es handelt sich nicht um einen neuen Editor oder einen neuen Agenten, den man erlernen muss – es integriert sich direkt in Claude und Codex, trifft Sie dort, wo Sie bereits arbeiten, und macht sie einfach effektiver darin, den vorliegenden Codebase zu verstehen.
Was kommt als Nächstes?
Es handelt sich hier noch um ein Projekt in einer frühen Entwicklungsphase, das kontinuierlich weiterentwickelt wird. Insbesondere das Speichersystem bietet die größten Verbesserungsmöglichkeiten – derzeit verhält es sich eher wie strukturierte Notizen als wie ein System mit nach Relevanz sortiertem Speicherinhalt. Wenn Sie KI-Code-Agenten in einer echten Codebasis einsetzen und auf die Herausforderung stoßen, dass „die KI mein Projekt nicht versteht“, sind Rückmeldungen wirklich willkommen:
npm install -g @ayushkumar320/codebuddy
Falls Sie es ausprobieren oder dieses Problem auf andere Weise in Ihrer eigenen Umgebung gelöst haben, wäre es hilfreich, Ihre Erfahrungen zu teilen.
CodeBuddy ist eine Schicht zur Verwaltung des Kontexts für KI-Code-Agenten wie Claude und Codex. Sie bereitet gezielten, relevanten Kontext vor, anstatt vollständige Lesevorgänge des gesamten Repositoriums durchzuführen, und kann optional mit Graphify integriert werden, um eine detailliertere Architekturkarte zu erhalten. Sie ist über npm unter @ayushkumar320/codebuddy verfügbar.
Zusätzliche Literatur
- Verständnis von KI-Agenten: Ziele, Werkzeuge, Speicher und der Agentenzyklus — Eine für Anfänger geeignete Erklärung, wie sich KI-Agenten von Chatbots unterscheiden, mit Informationen zu den Kernkomponenten, dem Entscheidungszyklus, den Autonomiegraden sowie praktischen Anwendungsfällen.
- Vergleich von Frontier-KI-Agenten: Astra, Flash, Fable und Mythos — Eine Analyse, wie sich die neuesten Versionen der Modelle GPT, Gemini und Claude bei echten agentbasierten Aufgaben wie Programmieren, Surfen und Werkzeugnutzung schlagen – nicht nur bei Benchmarks.