Claude Code: Warum Sie auf lokales RAG umsteigen und Grep hinter sich lassen sollten

Der Einsatz von KI-Agenten im Terminal, etwa Claude Code, ist für viele Entwickler eine Offenbarung. Doch diese Magie stößt schnell an eine physische Grenze: die Verwaltung des Kontexts.

Bei einer kleinen Codebasis läuft alles reibungslos. Sobald Ihr Projekt jedoch einige Dutzend Dateien überschreitet, brechen die Leistungen ein.

Warum? Weil Claude standardmäßig wie eine Datenbank ohne Index arbeitet.

Dieser Artikel zeigt, wie Sie eine lokale RAG-Architektur (Retrieval-Augmented Generation) umsetzen, um Ihren CLI-Assistenten in ein chirurgisch präzises Werkzeug zu verwandeln und dabei Latenz sowie Token-Verbrauch um mehr als 90 % zu reduzieren.

Der Engpass: „Full Table Scan“ vs. Index

Wenn Sie Claude fragen: „Wie wird die Authentifizierung verwaltet?“, kennt der Agent Ihren Code noch nicht. Er muss ihn erst entdecken.

Standardmäßig geht er dabei grob vor:

1. Er listet alle Dateien auf (ls -R / glob).
2. Er sucht nach Textvorkommen (grep).
3. Er liest ganze Dateien, um ihre Relevanz zu prüfen.

In Datenbankbegriffen ist das ein Full Table Scan. Das ist ineffizient, langsam und teuer. Für eine einfache Frage kann der Agent 3000 Tokens irrelevanten Code lesen, nur um die 50 relevanten Tokens zu finden.

Die Lösung: lokale Indexierung über MCP

Die Lösung besteht darin, das Wissen über das Projekt vorab zu berechnen. Statt die KI bei jeder Anfrage die Dateien durchsuchen zu lassen, verwenden wir qmd, ein Open-Source-Tool, das als MCP-Server (Model Context Protocol) fungiert.

qmd erzeugt auf Ihrem Rechner zwei Arten von Indizes:

• Lexikalisch (BM25): für die Suche nach exakten Schlüsselwörtern.
• Semantisch (Embeddings): um Konzepte zu verstehen. So findet „Fehlerbehandlung“ auch Code, in dem das Wort „Fehler“ nicht vorkommt.

Der Paradigmenwechsel ist grundlegend: Der Agent fragt den Index ab, erhält einen nach Relevanz sortierten Ausschnitt und antwortet.

Technische Umsetzung

So richten Sie diese Architektur in Ihrer Entwicklungsumgebung ein.

1. Installation des Stacks

Wir verwenden bun als Runtime wegen seiner Geschwindigkeit und qmd als Indexierungs-Engine.

# Installation der Engine
curl -fsSL https://bun.sh/install | bash
bun install -g https://github.com/tobi/qmd

2. Erstellen der Vektoren

Initialisieren Sie die Sammlung im Stammverzeichnis Ihres Projekts. Hier wird qmd Ihren Code zum ersten Mal „lesen“ und seine mentale Karte erstellen.

# Sammlung erstellen und relevante Dateien filtern
qmd collection add . --name backend-api --mask "**/*.{ts,tsx,go,rs,md}"

# Embeddings erzeugen (entscheidender Schritt für die semantische Suche)
qmd embed

Hinweis: Im Gegensatz zu grep, das sofort, aber wenig intelligent ist, dauert dieser Schritt zu Beginn einige Sekunden. Danach werden alle zukünftigen Anfragen sofort beantwortet.

3. Die MCP-Brücke

Claude Code muss wissen, dass dieser Server existiert. Ändern Sie Ihre Konfiguration ~/.claude/mcp.json:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

4. Prompt Engineering (die Datei CLAUDE.md)

Dies ist der entscheidende Schritt. Ohne Anweisung wird Claude aus Gewohnheit weiterhin seine nativen Tools verwenden. Wir müssen die Nutzung des Index durch eine Systemregel in der Datei CLAUDE.md im Projektstamm erzwingen.

## Systemregel: Indexierung hat Vorrang

**Kritische Richtlinie:** Scannen Sie das Dateisystem (ls/grep/read) niemals, um Informationen zu entdecken.

1. Verwenden Sie für jede Kontextermittlung AUSSCHLIESSLICH das Tool `qmd`.
2. Verwenden Sie `qmd search` für präzise Bezeichner (Funktionsnamen, Konstanten).
3. Verwenden Sie `qmd vsearch` für abstrakte Konzepte oder die funktionale Erkundung.
4. Lesen Sie die vollständige Datei (`Read`) nur, wenn der von `qmd` gelieferte Ausschnitt nicht ausreicht.

Wirkungsanalyse: Vorher/Nachher

Bei einem mittelgroßen TypeScript-Projekt mit 200 Dateien sind die Zahlen eindeutig:

Fazit

Bei der Token-Optimierung geht es nicht nur um finanzielle Einsparungen. Es geht um den Workflow.

Mit lokalem RAG beseitigen Sie die Reibung zwischen Ihrem Gedanken und der Antwort der KI. Claude hört auf, wie ein Praktikant die Archive zu durchsuchen, und wird zu einem Senior Engineer, der den genauen Speicherort jeder Funktion kennt.