# Codebase-Map für KI-Agenten: Code finden ohne grep

URL: https://agentvera.dev/de/blog/codebase-map-for-ai-agents/ · Veröffentlicht: 2026-10-24

Codebase-Map für KI-Agenten: Wie ein lokaler Index aus Dateien, Symbolen, Imports und Tests Claude Code und Codex hilft, Code schneller zu finden.

**Kurz gesagt:**

- Agenten ohne Map erkunden mit grep und lesen ganze Dateien. Jede gelesene Datei landet im Kontextfenster und wird in jedem späteren Turn erneut bezahlt.
- Die Projekt-Map von AgentVera indexiert Dateien, Symbole, Imports, verknüpfte Tests und Dateien, die sich gemeinsam ändern, lokal mit tree-sitter gebaut, der Aufbau kostet also keine Tokens.
- Agenten fragen sie über MCP ab: map_related für Dateien einer Aufgabe, map_outline vor dem Lesen, map_usages vor Codeänderungen, map_api für die echte API eines installierten Pakets.

**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:

1. `grep -r "checkout"` ausführen und 200 Treffer bekommen
2. Die vielversprechend aussehenden Dateien öffnen, oft ganz
3. Imports verfolgen, indem er weitere Dateien liest
4. 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](/de/blog/claude-code-token-usage/ "Token-Verbrauch von Claude Code um 61 % 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](/de/features/project-map/ "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-files` und beachtet `.gitignore`. Sie überspringt `node_modules`, `dist`, `build`, Dateien über 1 MB sowie generierte oder minifizierte Dateien. In Repos mit mehr als 20.000 Dateien indexiert sie nur Quellordner wie `src`, `lib`, `app` und `packages/*/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:**

```text
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 tests
```

**Mit Map:**

```text
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 tests
```

Dann 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](/de/features/smart-tools/ "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](/de/blog/claude-code-hooks-guide/ "Claude Code Hooks Anleitung").

## Die Map ein- und ausschalten

Die Projekt-Map ist standardmäßig an und Teil des kostenlosen Tarifs.

1. Öffne **Settings → Token savings** und finde den Schalter **Project map**. Er ist an, sofern du ihn nicht ausgeschaltet hast.
2. Um einen Agenten ohne sie zu lassen, entferne das Häkchen bei **Project map** im Bearbeiten-Dialog des Agenten.
3. 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_related` liefern 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](/de/blog/shared-memory-for-ai-coding-agents/ "Gemeinsames Gedächtnis für KI-Coding-Agenten"), damit Agenten wissen, wo Code liegt und warum er so ist, und [lade AgentVera herunter](/de/download/), um es an deinem größten Repo auszuprobieren.

## Häufige Fragen

**Was ist eine Codebase-Map für KI-Agenten?** Ein Index eines Repos, den ein Agent abfragen kann, statt blind zu suchen: welche Dateien es gibt, welche Symbole sie definieren, wer sie importiert, welche Tests sie abdecken und welche Dateien sich meist gemeinsam ändern.

**Senkt eine Codebase-Map den Token-Verbrauch von Claude Code?** Das kann sie. Jede Datei, die ein Agent liest, bleibt in seinem Kontext und wird in späteren Turns erneut gelesen. Fragt der Agent zuerst nach einer Gliederung oder einer gerankten Dateiliste, liest er weniger und kleinere Dinge. Wie viel das spart, hängt vom Repo und von der Aufgabe ab.

**Welche Sprachen versteht die Projekt-Map von AgentVera?** Sie liest Symbole für TypeScript, TSX, JavaScript, Python und Go, mit Zeilenbereichen, Signaturen und dem ersten Satz des Doc-Kommentars. Rund 30 weitere Sprachen werden nach Pfad indexiert.

**Kostet der Aufbau der Map Tokens?** Nein. Die Map wird auf deinem Rechner mit tree-sitter und Git gebaut und aktuell gehalten, wenn sich Dateien ändern und Commits eingehen. Nur die Antworten, nach denen ein Agent fragt, gelangen in seinen Kontext.

**Welche Agenten können die Projekt-Map nutzen?** Jeder CLI-Agent in AgentVera, der MCP-Server annimmt, etwa Claude Code, Codex, opencode, Copilot, Gemini und Cursor. Agenten auf einem entfernten SSH-Host bekommen sie nicht.

---

**Über AgentVera.** AgentVera ist eine Desktop-App für macOS, Windows und Linux, entwickelt von Solviera Teknoloji. Sie führt 18 KI-Coding-Agenten (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) nebeneinander aus, pro Projekt, in echten Terminals mit den eigenen CLI-Installationen und Logins des Nutzers. Der kostenlose Plan hat unbegrenzt viele Agenten. Download: https://agentvera.dev/de/download/ · Preise: https://agentvera.dev/de/pricing/