Cursor Codebase-Indizierung: So funktioniert sie besser

Cursors Codebase-Indizierung ist das, was ihn "schlau" über dein Projekt wirken lässt. Wenn sie funktioniert, bekommst du relevante Vorschläge, präzise @-Erwähnungen und Antworten, die deine Architektur tatsächlich verstehen. Wenn nicht, ist Cursor blind.

Diese Anleitung erklärt, wie die Indizierung funktioniert und wie du sie optimierst.

Wie Cursor deine Codebase versteht

Cursor baut im Hintergrund zwei Dinge auf:

1. Embeddings — Vektorrepräsentationen deiner Codedateien. Wenn du eine Frage stellst oder @ verwendest, durchsucht Cursor diese Vektoren, um die semantisch relevantesten Dateien zu finden.

2. AST-Analyse (Abstract Syntax Tree) — Cursor parst deinen Code, um Imports, Funktionsdefinitionen, Klassenhierarchien und Beziehungen zwischen Dateien zu verstehen.

Diese beiden Systeme arbeiten zusammen. Embeddings finden "was relevant aussieht", und die AST-Analyse ermittelt "was tatsächlich verbunden ist".

info

Die Indizierung geschieht automatisch, wenn du ein Projekt öffnest. Bei großen Codebases kann der initiale Scan einige Minuten dauern. Du siehst einen Fortschrittsindikator in der Statusleiste.

@-Symbole: Die richtige Verwendung

Das @-Symbol ist deine direkte Verbindung zu Cursors Indizierung. Nutze es, um spezifischen Kontext in Chat oder Inline-Edits zu ziehen.

@file — Eine bestimmte Datei referenzieren

@src/utils/auth.ts wie funktioniert die Token-Validierung?

Das ist die zuverlässigste Methode, um sicherzustellen, dass Cursor die exakte Datei sieht, die dich interessiert. Es umgeht die Embedding-Suche und hängt den vollständigen Datei-Inhalt an (bis zu Kontextlimits).

@folder — Ein ganzes Verzeichnis referenzieren

@src/components erkläre die Komponenten-Hierarchie hier

Nützlich für Architekturfragen, aber vorsichtig — große Ordner können dein Kontextfenster schnell füllen.

@code — Ein bestimmtes Symbol referenzieren

@code:validateUser welche Edge-Cases behandelt diese Funktion?

Das nutzt den AST-Index, um die exakte Funktion, Klasse oder Variablendefinition zu finden. Es ist präzise und kontext-effizient.

tipp

Bevorzuge @code: gegenüber @file, wenn du nur eine Funktion brauchst. Das spart Kontextplatz und reduziert Rauschen.

Optimierung für große Projekte

Wenn dein Projekt Tausende von Dateien hat, kann die Standard-Indizierung Dinge übersehen oder langsam wirken.

Überprüfen, was tatsächlich indiziert ist

Öffne Cursor Einstellungen > Allgemein > Codebase-Indizierung. Du siehst:

• Gesamtanzahl indizierter Dateien
• Letzte Indizierungszeit
• Dateien, die nicht geparst werden konnten

Kontextrelevanz erhöhen

Bei Monorepos greift Cursor manchmal irrelevante Dateien auf. Sei explizit in deinen Prompts:

Schau nur in @packages/api/src für diese Frage. Ignoriere den Frontend-Code.

Riesige Dateien aufteilen

Dateien mit mehreren tausend Zeilen können Probleme verursachen. Cursor indiziert möglicherweise nur den Anfang oder hat Schwierigkeiten mit Embeddings. Wenn du eine 5000-Zeilen-Utility-Datei hast, erwäge, sie aufzuteilen.

Dateien mit .cursorignore ignorieren

Nicht alles sollte indiziert werden. Generierte Dateien, Build-Output und Drittanbieter-Code verschwenden Kontextplatz und verfälschen Suchergebnisse.

Erstelle eine .cursorignore-Datei im Projekt-Root:

# Build-Output
dist/
build/
.out/

# Abhängigkeiten
node_modules/
vendor/

# Generierte Dateien
*.generated.ts
*.min.js
coverage/

# Große Datendateien
*.csv
*.json

warnung

.cursorignore verwendet dieselbe Syntax wie .gitignore, aber es ist eine separate Datei. Geh nicht davon aus, dass dein .gitignore ausreicht — Cursor respektiert ihn nicht automatisch.

Nach dem Bearbeiten von .cursorignore, starte Cursor neu oder warte eine Minute auf die Reindizierung.

Wenn die Indizierung versagt: Fehlerbehebung

Manchmal "sieht" Cursor deinen Code offensichtlich nicht. Hier ist die Checkliste:

1. Prüfen, ob die Datei indiziert ist

Öffne die Datei, dann frage:

Welche Datei schaue ich mir gerade an?

Wenn Cursor nicht antworten kann, ist die Datei möglicherweise nicht im Index.

2. Reindizierung erzwingen

Befehlspalette (Ctrl+Shift+P) → "Cursor: Codebase reindizieren"

Das baut den gesamten Index von Grund auf neu auf. Es dauert, behebt aber die meisten Korruptionsprobleme.

3. Nach Parse-Fehlern suchen

Unter Einstellungen > Allgemein > Codebase-Indizierung, prüfe auf Dateien mit roten Fehlerindikatoren. Diese Dateien werden nicht für AST-Beziehungen analysiert.

Häufige Ursachen:

• Syntaxfehler in der Datei
• Nicht unterstützte Sprache (Cursor unterstützt ~20 Sprachen gut)
• Binäre oder minifizierte Dateien, die fälschlicherweise als Quellcode identifiziert wurden

4. Überprüfen, ob .cursorignore nicht zu aggressiv ist

Wenn du *.config.* ignoriert hast und deine vite.config.ts wichtige Pfad-Aliase enthält, wird Cursor deine Imports nicht verstehen.

Kontextqualität verbessern

Die richtigen Dateien in den Kontext zu bekommen, ist nur die halbe Miete. Wie du diesen Kontext nutzt, ist ebenso wichtig.

Sei spezifisch in deinen Fragen

Schlecht:

Wie funktioniert Auth?

Gut:

In @src/auth/middleware.ts, wie behandelt die JWT-Verifizierung abgelaufene Tokens?

Verkette deinen Kontext

Wenn Cursor eine partielle Antwort gibt, folge mit spezifischeren @-Referenzen, anstatt die ganze Frage zu wiederholen.

Du hast Rate Limiting erwähnt. @src/middleware/rateLimit.ts — wie wird das Limit berechnet?

Nutze kürzlich geöffnete Dateien

Cursor gewichtet kürzlich geöffnete Dateien in der Embedding-Suche höher. Wenn du gerade eine Datei geöffnet hast, funktionieren @-Referenzen auf verwandte Dateien wahrscheinlicher ohne explizite Erwähnungen.

tipp

Bei komplexen Refactorings, öffne zuerst alle Dateien, die du planst zu ändern. Das "primes" den Index, sie als relevant zu behandeln.

Zusammenfassung

• Cursor nutzt Embeddings + AST, um deinen Code zu verstehen
• Nutze @file, @folder und @code:, um den Kontext explizit zu steuern
• Erstelle eine .cursorignore, um Rauschen auszuschließen
• Reindiziere, wenn etwas nicht stimmt
• Sei spezifisch in Prompts — der Index findet Dateien, aber du steuerst, wie sie genutzt werden

Das Codebase-Indizierung-Einstellungspanel zeigt den Indizierungsstatus deines Projekts und eventuelle Fehler.