Cursor Codebase-Index: Vollständiger Leitfaden zu Prinzip, Konfiguration und @-Symbolen

Aktualisiert am 2026-06-08: Gegen Cursors offizielle Doku gegengeprüft — die Index-Einstellungen liegen jetzt unter Cursor Settings → Indexing & Docs (mit „View included files“ prüfbar); Code-Chunks werden verschlüsselt an Cursors Server gesendet, um Embeddings zu erzeugen, die in einer entfernten Vektordatenbank liegen (kein rein lokaler FAISS-Index) — Quellcode wird jedoch nie im Klartext gespeichert und Indizes werden nach 6 Wochen Inaktivität gelöscht; die Synchronisierung läuft etwa alle 5 Minuten. Der Text unten ist entsprechend aktualisiert.

Der fünfte fehlerhafte Vorschlag von Cursor auf dem Bildschirm.

„Hilf mir, diesen Login-Bug zu fixen“ – die Anforderung war klar. Cursor kannte aber offenbar keine bestehende Auth-Hilfsfunktion im Projekt und wollte die Validierungslogik neu schreiben. Noch absurder: Es schlug vor, Code in ein utils-Verzeichnis zu legen – das es im Projekt gar nicht gibt.

Dann wurde klar: Wie schlau die KI auch ist – ohne Projektüberblick bleibt sie ein Code-Schreibroboter, und die Vorschläge treffen daneben.

20 Minuten später: Codebase-Index und .cursorignore konfiguriert. Beim nächsten Versuch verstand Cursor sofort: Es fand die Auth-Hilfe und drei Stellen mit duplizierter Validierung – Vorschlag zur Vereinheitlichung. Das Gefühl „Die KI versteht endlich mein Projekt“ ist unschlagbar.

Grundlagen des Cursor-Index

Was ist der Codebase-Index?

Beim ersten Mal klingt „Index“ hochtrabend – in Wahrheit ist es simpel.

Stellen Sie sich eine Bibliothek ohne Katalog vor: Reihe für Reihe durchsuchen, vielleicht einen Tag. Mit Katalogkarten finden Sie in Sekunden das richtige Buch.

Genau so funktioniert der Cursor Codebase-Index – ein „intelligenter Katalog“ für das gesamte Projekt, damit die KI relevanten Code schnell findet statt zu raten.

Konkret scannt der Index Ihre Dateien, analysiert Funktionen, Klassen und Variablen und versieht sie per Vektorisierung mit „Tags“. Bei Ihrer Frage matcht die KI blitzschnell die passendsten Code-Snippets.

Sechs zentrale Schritte der Indexierung

Technische Details spare ich mir – aber der Ablauf erklärt, warum Indexierung manchmal dauert und warum .cursorignore wichtig ist.

Schritt 1: Dateiscan und Vorverarbeitung

Nach dem Öffnen scannt Cursor alle Dateien. Ausgelassen werden Einträge aus .gitignore und .cursorignore – ohne .cursorignore indexiert Cursor möglicherweise node_modules mit Zehntausenden Dateien.

Schritt 2: Code-Chunking

Cursor behandelt keine ganze Datei als einen Block. Es teilt nach Funktionen, Klassen und logischen Abschnitten – eine 1.000-Zeilen-Datei wird vielleicht in 30 Chunks, präzisere Treffer bei Abfragen.

Schritt 3: Vektor-Embeddings (Kern)

Vereinfacht: Vektorisierung wandelt Code in Zahlen – ein „Fingerabdruck“. Ähnliche Funktionen liegen im mathematischen Raum nah beieinander – zwei Login-Funktionen mit unterschiedlichem Code, ähnliche Embeddings.

Schritt 4: Vektordatenbank

Hier irren viele Anleitungen. Tatsächlich werden Code-Chunks verschlüsselt an Cursors Server hochgeladen, um Embeddings zu erzeugen; diese Vektoren landen samt obfuskierter Dateipfade und Zeilennummern in einer entfernten Vektordatenbank (Cursor nutzt einen Dienst wie Turbopuffer), mit inkrementeller Synchronisierung über einen Merkle-Baum. Der Index ist also nicht rein lokal — aber Cursor gibt an, dass Quellcode nie im Klartext gespeichert wird (nach der Anfrage verworfen), Dateinamen obfuskiert/verschlüsselt sind und Indizes nach 6 Wochen Inaktivität gelöscht werden.

Schritt 5: Abfrage-Matching

Bei „Optimiere die Login-Logik“ vektorisiert Cursor die Frage und sucht die nächsten Code-Chunks – Millisekunden.

Schritt 6: Kontext-Injektion

Gefundene Snippets fließen in den KI-Kontext – die Antwort basiert auf Ihrem echten Code.

Warum der Index so wichtig ist

Ein Vergleich: Ohne Index sieht Cursor oft nur die geöffnete Datei – Vorschläge daneben. Mit Index verknüpft es 3–5 relevante Dateien – oft direkt nutzbar.

Der Unterschied ist enorm. Ein Cross-File-Bug über API-, Daten- und UI-Schicht: ohne Index musste ich drei Dateien manuell @-en und Beziehungen erklären. Mit Index fragte ich „Warum werden Nutzerdaten nicht aktualisiert?“ – Cursor fand alle drei Dateien und eine vierte in der Middleware (Datenvalidierung), die ich übersehen hatte.

Datenschutz und Sicherheit

Bei „Cloud“ und „KI analysiert Code“ werden viele nervös – mir ging es anfangs genauso.

Zuerst der Mechanismus (den viele Anleitungen falsch darstellen): Beim Indexieren werden Code-Chunks verschlüsselt an Cursors Server gesendet, um Embeddings zu berechnen. Es gibt aber echte Schutzmaßnahmen:

1. Quellcode nicht im Klartext gespeichert – der Server verarbeitet ihn nur während der Anfrage und verwirft ihn danach; gespeichert werden Vektoren, nicht Ihr Source
2. Dateinamen/Pfade obfuskiert und verschlüsselt – selbst mit den Vektordaten lässt sich die Projektstruktur nicht rekonstruieren
3. Automatische Löschung nach 6 Wochen – lange inaktive Indizes werden gelöscht; beim erneuten Öffnen wird neu indexiert
4. Privacy Mode – der Privacy-Modus in den Einstellungen begrenzt die Datenhaltung zusätzlich

Für stark sensible Projekte (Finanzen, Medizin) aktiviere ich Privacy Mode und prüfe genau; für normale Web- oder Hobby-Projekte reicht der Standard. Die Aussage „Ihr Code verlässt nie den Rechner“ stimmt aber nicht – das sollten Sie wissen.

Vollständiger Leitfaden zu @-Symbolen

Am Anfang dachte ich, @ ist @ – in Wahrheit steckt dahinter viel. Falsche Wahl kostet Zeit und liefert absurde Vorschläge.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Hier: alle 6 @-Varianten mit Einsatz, Vor- und Nachteilen.

@Codebase – Projektkontext

Zweck: Die KI versteht Struktur und Logik des gesamten Projekts.

Mächtig und oft unterschätzt. Mit @Codebase durchsucht Cursor die Index-Datenbank und findet automatisch die relevantesten Snippets.

Einsatz:

• Cross-File: „Warum synchronisieren sich Nutzerdaten nach Login nicht?“
• Architektur: „Wo wird Berechtigung geprüft?“
• Neues Projekt: „Wie ist das Routing organisiert?“

Erfahrung: Legacy-Projekt, tausende Dateien, keine Doku. Frage: @Codebase Wie läuft der Payment-Flow? – fünf Dateien von API über Validierung bis Callback in Sekunden. Manuell: halber Tag.

Grenzen:

• Abhängig von Index-Qualität
• Relativ langsam (1–3 s), Suche in der gesamten DB
• Sehr große Projekte (100.000+ Zeilen): Randcode kann fehlen

@Files – präzise Dateireferenz

Zweck: Die KI fokussiert auf bestimmte Dateien.

@Files öffnet einen Dateiwähler – nur ausgewählte Dateien zählen.

Einsatz:

• Bekannte betroffene Dateien
• Änderungen an konkreten Dateien
• Keine Störung durch irrelevanten Code

Beispiel: Refactoring einer Komponente plus Styles und Tests – drei Dateien @-en, „In funktionale Komponente umbauen“ – fokussierter Plan ohne Ballast.

Vorteile: Präzise, schnell, kontrollierbar
Nachteile: Dateien müssen bekannt sein – leicht etwas übersehen

@Folders – Verzeichnisebene

Zweck: Gesamtes Verzeichnis als Kontext.

Wenn das Modul klar ist, die Datei nicht.

Einsatz:

• „Alle Komponenten unter /components/auth/ optimieren“
• „Sicherheitsprobleme in /api/ prüfen“
• Batch-Arbeit in einem Modul

Hinweis: Große Ordner sprengen den Kontext – unter ~10 Dateien ideal. Bei Dutzenden sieht die KI oft nur den Anfang, Rest wird abgeschnitten.

@Code – Code-Snippet

Zweck: Bestimmte Funktion, Klasse oder Block.

Code markieren → „Add to Chat“, oder @Code und Funktionsname wählen.

Einsatz:

• „Diese validateUser-Funktion hat einen Bug“
• „Diese Logik klarer strukturieren“
• Code-Review für einen Abschnitt

Lieblings-Workflow: In einer 1.000-Zeilen-Datei nur eine 50-Zeilen-Funktion @-en – keine Ablenkung.

@Docs – externe Dokumentation

Zweck: Offizielle Docs, API-Referenzen.

Seit Ende 2024 in Cursor – noch wenig bekannt.

Einsatz:

• „Nach Next.js-Docs dynamisches Routing konfigurieren“
• „Aus dieser API-Doku Aufrufcode generieren“
• Neues Framework mit Doc-Kontext lernen

Nutzung: @Docs, URL oder eingebaute Framework-Docs wählen.

Grenzen:

• Nicht alle Frameworks
• Eigene URLs manchmal fehleranfällig (Netzwerk, Format)

@Web – Live-Websuche

Zweck: Aktuelle Informationen aus dem Netz.

Frisch veröffentlichte Bibliothek, noch nicht im Modell – @Web für neueste Docs.

Einsatz:

• „React-19-Neuerungen suchen“
• „Aktuelle npm-Version dieser Library“
• Frische Bugs und Fehlermeldungen

Hinweis: Etwas langsamer wegen Live-Suche – nur wenn wirklich nötig.

Vergleich: Welches @-Symbol wann?

Persönliche Empfehlung

Anfangs nur @Files – sicher, aber mühsam. Später: In 80 % der Fälle ist @Codebase schneller – die KI findet Verknüpfungen, die ich übersehe.

Meine Verteilung:

• @Codebase: 60 %
• @Files: 30 %
• @Code: 5 %
• Andere: 5 %

Finden Sie Ihren Rhythmus – verstehen Sie die Stärken jedes Symbols.

.cursorignore in der Praxis

Unscheinbar, aber entscheidend: Index oft 50 %+ schneller, CPU halbiert.

Ohne .cursorignore indexierte Cursor bei mir node_modules mit 30.000 Dateien – Lüfter hoch, Cursor stockend.

Warum .cursorignore?

Nicht jede Datei verdient einen Index-Eintrag.

Typisch im Projekt:

• Abhängigkeiten: node_modules, vendor, .venv – tausende Dateien, selten relevant
• Build-Artefakte: dist, build, .next – generiert, kein Quellcode
• Temporäres: .log, .cache, .DS_Store
• Große Assets: Video, Bilder, Fonts – für Code-KI nutzlos

Ausschluss: Index von 5 Minuten auf 30 Sekunden, präzisere Abfragen ohne Rauschen.

.cursorignore vs. .gitignore

Frage: „Ich habe schon .gitignore – brauche ich .cursorignore?“

Ja – andere Logik.

.gitignore: Was nicht committed wird. Manche Dateien wollen Sie nicht committen, die KI soll sie aber sehen:

• Lokale Config: .env.local – nicht im Repo, KI braucht Variablen
• Notizen: TODO.md – nicht committen, KI darf lesen

Umgekehrt committen, aber nicht indexieren:

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

• package-lock.json – im Repo, KI braucht es nicht
• Coverage-Reports – CI, kein Index-Wert

.cursorignore separat pflegen.

Universelle Vorlage (Copy & Paste)

Für die meisten Frontend-Projekte – .cursorignore im Projektroot:

# Abhängigkeiten
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# Build-Artefakte
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# Logs und Temp
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

# IDE
.idea/
.vscode/
*.swp
*.swo

# Test-Coverage
coverage/
.nyc_output/

# Statische Assets (optional)
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# Große JSON (optional)
package-lock.json
yarn.lock
pnpm-lock.yaml

Hinweis: Basisvorlage – anpassen. Python: __pycache__/, *.pyc.

Fortgeschrittene Strategien

1. Monorepo – gestaffelter Index

Dutzende Pakete – alles indexieren dauert:

# Nur aktuelles Paket
packages/*/node_modules/
packages/package-a/  # vorerst nicht relevant
packages/package-b/

Später Kommentare entfernen.

2. Whitelist

Chaotisches Repo – lieber explizit einschließen:

# Alles ausschließen
*

# Nur src
!src/
!src/**/*

# Config
!*.config.js
!tsconfig.json

Für Legacy: KI nur auf Kerncode.

3. Nach Dateigröße

Cursor überspringt oft Dateien >1 MB – manuell sicherer:

# Große Daten
*.sql
*.csv
*.json  # bei sehr großen JSON-Dateien

Konfiguration prüfen

Nach Änderungen validieren:

Methode 1: Index-Geschwindigkeit

Projekt schließen, neu öffnen – „Indexing…“ unten rechts. Vorher 3–5 Min., nachher 30–60 s.

Methode 2: Dateianzahl

Cursor Settings → Indexing & Docs öffnen und „View included files“ anklicken, um die tatsächlich indexierten Dateien aufzulisten. Von Zehntausenden auf Hunderte = Erfolg.

Methode 3: @Codebase testen

@Codebase Welche Dateien hat das Projekt? – erscheinen node_modules-Einträge, Syntax prüfen.

Performance-Vergleich

Next.js-Projekt, reale Messung:

Zahlen lügen nicht. .cursorignore ist Schritt eins mit Cursor.

Häufige Probleme und Lösungen

Über ein Jahr Cursor – Index-Fehler, langsame Abfragen, volle CPU. 90 % kennen das.

Die vier häufigsten Fälle – Checkliste zum Abarbeiten.

Problem 1: Index hängt bei „Indexing…“ oder schlägt fehl

Symptome:

• „Indexing…“ bleibt ewig
• „Indexing failed“
• @Codebase reagiert nicht

Ursachen und Lösungen:

Ursache 1: Zu viele Dateien, Timeout

• Lösung: .cursorignore, node_modules usw. ausschließen
• Prüfen: Projekt neu öffnen – unter 2 Minuten?

Ursache 2: Nicht unterstütztes oder beschädigtes Format

• Lösung: Dateien >10 MB oder Binärdateien in .cursorignore
• Typisch: Videos, große SQL-Dumps, kompilierte Binaries

Ursache 3: Wenig Speicherplatz

• Index lokal – mindestens ~5 GB frei
• Mac: ~/Library/Application Support/Cursor/
• Windows: %APPDATA%\Cursor\

Ursache 4: Netzwerk (Cloud-Sync)

• Privacy Mode testweise aus, anderes Netz
• Temporär: Privacy-Mode-Einstellung prüfen oder sicherstellen, dass das Netzwerk Cursors Server erreicht

Schnell-Checkliste:

☐ .cursorignore konfiguriert?
☐ Dateianzahl (über 1.000 → optimieren)
☐ Speicher (mind. 5 GB)
☐ Cursor neu starten
☐ Index-Cache löschen, neu indexieren

Problem 2: @Codebase liefert schlechte Treffer

Symptome:

• Relevanter Code existiert, wird nicht gefunden
• Irrelevante Snippets

Ursachen und Lösungen:

Ursache 1: Index unvollständig oder veraltet

• Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows) → „Reindex Codebase“

Ursache 2: Frischer Code noch nicht indexiert

• Synchronisierung etwa alle 5 Minuten – kurz warten oder manuell „Reindex“

Ursache 3: Frage zu vage

• Nicht „Bug fixen“, sondern „Warum landet das Token nach Login nicht in localStorage?“
• ❌ „Performance optimieren“
• ✅ „Listen-Komponente langsam – doppeltes Rendering finden“

Ursache 4: Relevanter Code ausgeschlossen

• .cursorignore prüfen – nicht versehentlich ganzes src/ ausgeschlossen

Tipps für Genauigkeit:

• Konkrete Funktions-, Variablen- und Dateinamen
• Geschäftsszenario statt Allgemeinplätze
• Bei @Codebase-Misserfolg: @Files

Problem 3: Hohe CPU-/RAM-Last

Symptome:

• Lüfter laut
• Cursor CPU 80 %+
• Mehrere GB RAM
• System ruckelt

Ursachen und Lösungen:

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Ursache 1: Große Indexierung läuft

• Normal bis fertig – sonst .cursorignore verschärfen

Ursache 2: Zu häufige Live-Updates

• Milderung: Cursor synchronisiert standardmäßig etwa alle 5 Minuten inkrementell; häufig geänderte große Ordner in .cursorignore aufnehmen senkt die Re-Indexierungslast

Ursache 3: Mehrere große Projekte offen

• Jedes Fenster kostet Ressourcen – schließen

Ursache 4: Beschädigte Index-DB

• Cache löschen, neu indexieren
• Mac: ~/Library/Application Support/Cursor/Index/
• Windows: %APPDATA%\Cursor\Index\

Optimierung:

☐ .cursorignore (<1.000 Dateien anstreben)
☐ Unnötige Projekt-Fenster schließen
☐ Häufig geänderte große Ordner in .cursorignore ausschließen, um Re-Indexierung zu reduzieren
☐ Sehr große Projekte: @Files statt @Codebase
☐ Hardware: mind. 16 GB RAM, empfohlen 32 GB

Problem 4: @Codebase reagiert langsam

Symptome:

• 5–10 s Wartezeit
• Timeouts

Ursachen und Lösungen:

Ursache 1: Zu große Index-DB

• .cursorignore – ideal 500–2.000 Dateien

Ursache 2: Langsames Netz (Cloud-Modell)

• Verbindung prüfen, schnelleres Modell

Ursache 3: Zu viel gematchter Code

• Breite Fragen → viele Dateien – präzisere Frage oder @Files

Ursache 4: Schwache Hardware

• Vektorsuche braucht CPU/RAM – 16 GB + SSD empfohlen

Beschleunigung:

• @Files oder @Folders statt @Codebase
• Index-Cache regelmäßig bereinigen
• Modular arbeiten – nur nötige Teile laden

Eigene Fehlersuche-Reihenfolge

90 % Index-Probleme: fehlende .cursorignore, zu viel Ballast.

Meine Reihenfolge:

1. .cursorignore prüfen
2. Manuell neu indexieren
3. CPU/RAM – Performance oder Config?
4. Cache löschen, von vorn

Meist reicht das. Sonst Bug melden auf GitHub.

Praxis: Next.js-Index von null konfigurieren

Genug Theorie – echtes Next.js-Projekt: .cursorignore anlegen, prüfen, @-Symbole testen.

10 Minuten, Schritt für Schritt.

Praxis-Vergleich vorher/nachher

Next.js mit Komponenten, API-Routen, DB – vollständiger Test:

Letzte Zeile: 20 reale Dev-Fragen – nutzbare Vorschläge vor/nach Index. Von 60 % auf 92 %.

Kernpunkte

Nach diesem Walkthrough sollten Sie:

1. ✅ .cursorignore für Next.js anlegen
2. ✅ Index-Wirkung prüfen
3. ✅ @-Symbole testen
4. ✅ Konfiguration optimieren

Gilt auch für React, Vue, Angular und Backend: Irrelevantes raus, KI auf Kerncode fokussieren.

Weiterführend

• Cursor Agent-Modus: vollständiger Leitfaden
• Cursor-Netzwerkprobleme vollständig beheben
• Cursor Free-Tier: vollständiger Leitfaden

Fazit

Zurück zum Anfang – der fünfte falsche Vorschlag um ein Uhr nachts. Viele kennen die Frustration. Ohne Projektüberblick rät die KI.

Der Index ist der Schlüssel.

Drei Kernpunkte:

1. Prinzip verstehen – nicht zum Angeben. Dann ist klar, warum node_modules weg muss, Abfragen manchmal dauern und Code fehlen kann.

2. .cursorignore hat Priorität eins. Index ~50 % schneller, CPU halbiert, Genauigkeit ~60 % höher – gemessen, nicht Marketing.

3. @-Symbole nach Szenario, nicht auswendig. 80 % @Codebase, 20 % @Files – mit der Zeit automatisch.

Drei Schritte jetzt:

1. .cursorignore im Projektroot – Vorlage aus diesem Artikel kopieren
2. Cursor neu starten – Index-Geschwindigkeit vergleichen
3. @Codebase testen – eine Frage, die vorher schiefging

10 Minuten investiert, hunderte Stunden gespart.

Wenn der Artikel hilft – an Freunde weitergeben, die noch mit dem Index kämpfen.

Cursor entwickelt sich weiter. Dieser Leitfaden wurde gegen die offizielle Doku von Mitte 2026 gegengeprüft, aber es können neue Features und Fallstricke folgen – bei Lücken die offizielle Doku prüfen.

Genug gelesen – jetzt konfigurieren.