Eine Codebase-Map für KI-Agenten ist ein lokaler Index aus Dateien, Symbolen, Imports, Tests und Änderungshistorie eines Repos, den ein Agent abfragen kann, sodass er den richtigen Code in wenigen Aufrufen findet, statt zu greppen und Datei um Datei zu lesen. Weniger gelesene Dateien bedeuten weniger im Kontextfenster, und weniger im Kontextfenster macht jeden späteren Turn günstiger.
Dieser Beitrag erklärt, warum Agenten beim Erkunden Tokens verschwenden, was eine gute Map enthält und wie die Projekt-Map von AgentVera Claude Code, Codex und anderen CLI-Agenten diesen Index über MCP bereitstellt.
Wie Agenten ein Repo ohne Map erkunden
Gib einem Coding-Agenten in einem unbekannten Repo eine Aufgabe wie „füge dem Checkout ein Gutscheinfeld hinzu“, und er macht, was du mit nur einem Terminal auch tun würdest:
grep -r "checkout"ausführen und 200 Treffer bekommen- Die vielversprechend aussehenden Dateien öffnen, oft ganz
- Imports verfolgen, indem er weitere Dateien liest
- Erneut nach der Testdatei suchen
Jeder Schritt zieht Text in den Kontext. Eine 1.000 Zeilen lange Datei, die einmal gelesen wurde, bleibt für den Rest der Session im Gespräch, und das Modell liest das Gespräch in jedem Turn neu. Waren die ersten Vermutungen falsch, liegen diese Dateien trotzdem noch da. Das ist einer der Hauptgründe, warum eine Session teuer wird, lange bevor die eigentliche Änderung passiert. Zur anderen großen Quelle, dem Basiskontext, siehe Token-Verbrauch von Claude Code senken.
Was eine nützliche Codebase-Map enthält
Eine Dateiliste reicht nicht. Ein Agent muss „wo“ und „was geht kaputt, wenn ich das ändere“ beantworten können, ohne Code zu lesen. Eine gute Map enthält:
| Ebene | Beantwortet |
|---|---|
| Dateien und Module | Was steckt in diesem Repo und wie ist es aufgebaut? |
| Symbole mit Signaturen | Wo ist applyCoupon und was nimmt es entgegen? |
| Imports | Wer nutzt diese Datei, und wer nutzt jene? |
| Verknüpfte Tests | Welche Tests decken diesen Code ab? |
| Gemeinsame Änderungshistorie | Welche Dateien ändern sich meist mit dieser? |
| Einstiegspunkte und Testbefehl | Wo beginnt es und wie führe ich die Tests aus? |
Die letzten beiden sind wichtiger, als sie aussehen. Die Git-Historie weiß, dass sich checkout.ts, checkout.test.ts und pricing.ts tendenziell im selben Commit ändern, auch wenn kein Import sie verbindet.
Wie die Projekt-Map von AgentVera gebaut wird
AgentVera baut für jeden Projektordner eine Projekt-Map:
- Symbole. tree-sitter liest Funktionen, Klassen, Methoden, Interfaces, Typen, Enums und Konstanten mit Zeilenbereichen, Signaturen und dem ersten Satz des Doc-Kommentars, für TypeScript, TSX, JavaScript, Python und Go. Rund 30 weitere Sprachen werden nach Pfad indexiert.
- Imports und Tests. Imports werden zu Dateien aufgelöst, und Tests werden mit dem Code verknüpft, den sie abdecken.
- Gemeinsame Änderungen. Dateien, die sich in mindestens 2 der letzten 500 Commits gemeinsam geändert haben, werden verknüpft. Commits, die mehr als 40 Dateien berühren, werden ignoriert, damit ein großes Umbenennen nicht alles mit allem verknüpft.
- Was sie überspringt. Sie beginnt bei
git ls-filesund beachtet.gitignore. Sie überspringtnode_modules,dist,build, Dateien über 1 MB sowie generierte oder minifizierte Dateien. In Repos mit mehr als 20.000 Dateien indexiert sie nur Quellordner wiesrc,lib,appundpackages/*/src.
Die Map wird auf deinem Rechner gebaut und kostet keine Tokens. Sie beobachtet Dateiänderungen, zählt die gemeinsame Änderungshistorie neu, wenn Commits eingehen, und prüft eine Datei erneut, wenn ein Agent nach ihr fragt. Pro Ordner gibt es eine Map, die alle dort arbeitenden Agenten teilen, ein Projekt und jeder seiner Worktrees haben also je eine eigene. Sie wird komprimiert im Datenordner der App gespeichert.
Die MCP-Tools, die Agenten nutzen
AgentVera fügt jedem Agenten einen MCP-Server namens agentvera-map hinzu. Seine Anweisungen sagen dem Agenten, eine Aufgabe mit map_related zu beginnen, vor dem Lesen einer Datei map_outline zu nutzen und vor dem Ändern von Code map_usages.
| Tool | Liefert |
|---|---|
map_related | Dateien, die eine Aufgabe wahrscheinlich betrifft, gerankt, mit Begründung (Namenstreffer, Imports, gemeinsam geändert, Tests) |
map_outline | Die Symbole einer Datei mit Zeilenbereichen und Signaturen, ihre Imports, Importer und Tests |
map_usages | Wer ein Symbol oder eine Datei aufruft oder importiert, bei Tiefe 2 die Importer der Importer, plus abdeckende Tests |
map_find | Symbole oder Dateien per unscharfem Namen, mit Art, file:line und Signatur |
map_overview | Module, Größen, Einstiegspunkte und der Testbefehl |
map_api | Die echte exportierte API eines installierten Pakets, in der Version aus node_modules, aus seinen Typdeklarationen |
map_related nimmt eine Aufgabe in einfachen Worten entgegen, in jeder Sprache. Türkische Wörter wie sepet, kupon oder ödeme treffen englische Codenamen wie cart, coupon und payment.
map_api behebt eine stille Fehlerquelle: einen Agenten, der Aufrufe aus dem Gedächtnis für eine Bibliotheksversion schreibt, die du nicht hast. Es liest die .d.ts-Dateien der tatsächlich installierten Version.
Neue Agenten bekommen außerdem eine kurze Zusammenfassung von Modulen, Einstiegspunkten und Testbefehl in ihre Anweisungen, damit sie die ersten Turns nicht damit verbringen herauszufinden, wie man die Tests ausführt.
Vorher und nachher: dieselbe Aufgabe
So ändert sich die Gutschein-Aufgabe. Die Schritte sind typisch, kein Benchmark.
Ohne Map:
grep -rn "checkout" src # 200 lines of hits
cat src/checkout/index.ts # whole file
cat src/checkout/summary.tsx # whole file, not the right one
cat src/pricing/total.ts # whole file
grep -rn "total(" src test # find callers and testsMit Map:
map_related "add a coupon field to checkout"
-> src/pricing/total.ts (name match, changed together with checkout)
-> src/checkout/CheckoutForm.tsx (imports total.ts)
-> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts # symbols and lines only
map_usages calculateTotal # callers and testsDann liest der Agent nur die Zeilen, die er braucht. Die erste Variante füllt den Kontext mit Dateien, die er nicht brauchte; die zweite mit einer gerankten Liste und einer Gliederung.
Smart Tools: wenn der Agent trotzdem liest
Agenten fragen nicht immer zuerst die Map. Für Claude Code greifen die Smart Tools von AgentVera über Hooks ein:
- Das erste vollständige Lesen einer Datei über 800 Zeilen und 24 KB liefert stattdessen die Gliederung aus der Projekt-Map, sodass der Agent den benötigten Teil lesen kann.
- Wiederholtes Lesen einer unveränderten Datei wird blockiert, da der Inhalt schon im Kontext ist.
- Testläufe werden auf die Tests eingegrenzt, auf die es ankommt.
Wie Hooks allgemein funktionieren, liest du in der Claude Code Hooks Anleitung.
Die Map ein- und ausschalten
Die Projekt-Map ist standardmäßig an und Teil des kostenlosen Tarifs.
- Öffne Settings → Token savings und finde den Schalter Project map. Er ist an, sofern du ihn nicht ausgeschaltet hast.
- Um einen Agenten ohne sie zu lassen, entferne das Häkchen bei Project map im Bearbeiten-Dialog des Agenten.
- Um die Map zu sehen, öffne die Details-Seite des Projekts und den Tab Project map. Er zeichnet einen Graphen mit Imports in Grau und Verknüpfungen gemeinsamer Änderungen als gestrichelte orange Linien. Gib eine Aufgabe ein und klicke auf Show, um zu sehen, was
map_relatedliefern würde.
Ist die Map noch nicht fertig, zum Beispiel direkt nach dem Öffnen eines großen Repos, antworten die Tools mit dem Aufbaufortschritt. Der Agent wartet ein paar Sekunden und greift dann auf seine normalen Tools zurück.
Spart das wirklich Tokens?
Die ehrliche Antwort lautet: Es hängt vom Repo und von der Aufgabe ab. Ein kleines Repo, in dem der Agent ohnehin weiß, wo er suchen muss, gewinnt wenig. Ein großes oder unbekanntes Repo, in dem ein Agent sonst ein Dutzend falsche Dateien läse, gewinnt viel.
Statt einer Zahl zu trauen, miss es an deiner eigenen Arbeit. Der Tab AI ROI hat eine Karte Project map impact, die Gespräche mit und ohne Map nach Erfolg, Erstdurchlauf-Quote, Tokens pro Aufgabe und Nachfragen vergleicht.
Grenzen, die du kennen solltest
- Symboldetails gibt es für TypeScript, TSX, JavaScript, Python und Go. Andere Sprachen werden auf Pfadebene indexiert.
- Agenten auf einem entfernten SSH-Host bekommen die Map nicht.
- Ein Agent liest nur die Map seines eigenen Ordners, ein Worktree-Agent sieht also seinen Worktree, nicht den Haupt-Checkout.
- Das Code-Map-Fenster in der Projekttour von AgentVera ist eine eigene Funktion, mit der du den Code erkundest; die Projekt-Map ist das, was Agenten abfragen.
Zusammenfassung
Eine Codebase-Map für KI-Agenten ersetzt blindes Grep-und-Lesen durch wenige gezielte Fragen: welche Dateien, welche Symbole, wer sie nutzt und welche Tests sie abdecken. Die Projekt-Map von AgentVera baut diesen Index lokal mit tree-sitter und Git, hält ihn aktuell und gibt ihn über agentvera-map an jeden MCP-fähigen Agenten weiter, während Smart Tools große und wiederholte Lesevorgänge in Claude Code abfangen. Kombiniere sie mit einem gemeinsamen Projektgedächtnis, damit Agenten wissen, wo Code liegt und warum er so ist, und lade AgentVera herunter, um es an deinem größten Repo auszuprobieren.