Cursor: @Codebase, @Docs oder @Files – Praxisleitfaden für die richtige Wahl

Cursors @-Symbol-System wirkt simpel: @Codebase, @Files, @Docs – ein Klick, und die KI hat Kontext. In der Praxis hängen viele an einer Frage fest: Sie wissen, welchen Code Sie brauchen, aber nicht, welches Symbol Sie wählen sollen.

Die falsche Wahl bedeutet: Die KI füllt den Kontext mit irrelevantem Material oder findet nicht die richtige Datei. Der Chat füllt sich mit wiederholten Abfragen, Token gehen drauf, und das Problem bleibt unklar.

Dieser Artikel erklärt keine Funktionsdefinitionen, sondern eine Sache: In konkreten Szenarien schnell das richtige @-Symbol wählen. Danach haben Sie eine klare Entscheidungslogik – ohne jedes Mal zu zögern.

1. Kernvergleich: sechs Funktionen auf einen Blick

Eine zentrale Erkenntnis vorweg: Laut BetterLink Blog-Praxisstatistik sollten Sie in etwa 80 % der Entwicklungszeit @Codebase nutzen, statt Dateien manuell auszuwählen. Das klingt hoch – die Logik ist einfach: Der Kernvorteil von @Codebase ist nicht Suche, sondern dass die KI verknüpften Code findet, den Sie leicht übersehen.

Die sechs Symbole, nach Häufigkeit absteigend:

@Codebase (60–80 %): Semantische Suche über die gesamte Codebasis. Sie stellen eine Frage, die KI findet relevante Dateien, Funktionen und Typen – ohne dass Sie den Speicherort kennen müssen. Typisch für Architekturverständnis, Refactoring und repo-übergreifende Fehlersuche. Hoher Token-Verbrauch, weil der Index die ganze Codebasis abdeckt.

@Docs (10–15 %): Externe Dokumentation einbinden. Eingebaute Framework-Docs (React, Vue, Astro) oder eigene Quellen per URL. Sinnvoll bei neuen Bibliotheken, aktuellen API-Spezifikationen und Team-Wissensbasen.

@Files (5–10 %): Eine Datei vollständig referenzieren. Wenn der Dateiname klar ist oder Sie Konfigurationsdateien (z. B. vite.config.ts) ändern. Ab etwa 600 Zeilen ist @Files präziser als @Codebase. Höherer Token-Verbrauch, weil der gesamte Dateiinhalt im Kontext landet.

@Code (5–10 %): Einen exakten Codeausschnitt referenzieren. Nur die markierten Zeilen, nicht die ganze Datei. Für lokale Optimierung, Debugging kleiner Logikblöcke und sauberen Kontext. Niedrigster Token-Verbrauch.

@Folders (unter 5 %): Struktur und Inhaltsüberblick eines Verzeichnisses. Für Modul-Refactoring, neue Komponenten und Architektur-Konsistenz. Hoher Verbrauch, mehrere Dateien betroffen.

@Repo (Spezialfälle): Repository-Kontext. Für Multi-Repo-Projekte, Versionshistorie und repo-übergreifende Analyse. Mittlerer Token-Verbrauch.

Die Symbole schließen sich nicht aus – kombinieren Sie sie. Erst @Codebase für den Überblick, dann @Files für Schlüsseldateien, zuletzt @Docs für offizielle Spezifikation. Entscheidend: nach Problemtyp wählen, nicht blind stapeln.

2. Entscheidungsbaum: Problemtyp → @-Symbol

Die Kernfrage ist eine: Wissen Sie, wo der Code liegt?

Unbekannt → @Codebase. Bekannt → @Files oder @Code. Fehlt Dokumentation → @Docs dazu.

Im Detail:

Szenario 1: Dateiposition unbekannt

Sie refactoren ein Next.js-Projekt und wollen ein API-Response-Format ändern, wissen aber nicht, wo der Typ definiert ist – vielleicht in types/, in components/ oder nebenbei in einer utils.ts.

→ @Codebase. Im Chat: „Finde die Definition von ApiResponse und passe das Response-Format an.“ Die KI scannt die Codebasis, findet alle Referenzen – auch die utils.ts, die Sie vergessen hätten.

Szenario 2: Dateiname bekannt

Sie ändern die Proxy-Konfiguration in vite.config.ts oder refactoren eine Funktion in src/utils/auth.ts. Pfad klar, Datei lang (über 600 Zeilen).

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

→ @Files. Zieldatei wählen – die KI erhält den vollen Inhalt. Präziser als @Codebase, ohne „ähnliche, aber irrelevante“ Treffer.

Szenario 3: Aktuelle Dokumentation nötig

Neue Bibliothek (gerade veröffentlicht) oder neueste API eines Frameworks (Trainingsdaten evtl. veraltet).

→ @Docs. Framework-Dokumentation wählen oder URL als Quelle. Im Prompt betonen: „Verwende die neueste Syntax aus der Dokumentation“ – sonst greift die KI auf ältere APIs aus dem Gedächtnis zurück.

Szenario 4: Nur ein Codeausschnitt

Debugging einer Funktion – nur ein paar Zeilen optimieren, nicht die ganze Datei in den Kontext.

→ @Code. Ausschnitt markieren, Cmd+K für Inline-Edit oder @Code im Chat. Minimaler Token-Verbrauch, sauberster Kontext.

Szenario 5: Modul-Refactoring oder neue Komponente

Ganzes components/-Verzeichnis refactoren oder neues features/-Modul mit konsistenter Architektur.

→ @Folders. Verzeichnisstruktur und Schlüsseldateien – die KI versteht das Modul und generiert passenden Code.

Szenario 6: Multi-Repo oder Versionshistorie

Mehrere Git-Repositories oder Analyse eines Commits über Repos hinweg.

→ @Repo. Repository-Kontext inkl. Historie und repo-übergreifender Abhängigkeiten.

Kurz: Unsicher → @Codebase; sicher → @Files/@Code; Dokumentation fehlt → @Docs. @Folders und @Repo sind Ergänzungen für Spezialfälle.

3. @Codebase vs. @Files: Unterschied und Praxisbeispiele

Die beiden Symbole verwechselt man am leichtesten. Der Unterschied: Sucht die KI für Sie, oder zeigen Sie selbst?

@Codebase ist kein reines „Suchen“, sondern Entdecken. Die KI matcht semantisch über die Codebasis und liefert relevante Dateien, Funktionen und Typen – oft auch unerwartete. Fragen Sie „Wie ändere ich das API-Response-Format?“, kann die KI liefern:

• API-Handler (erwartet)
• Typdefinitionen (bekannt)
• Typalias in einer utils.ts (leicht übersehen)
• Mock-Daten in Tests (oft ignoriert)

Das ist der Kernvorteil: Die KI findet Verknüpfungen, die Ihnen entgehen.

@Files ist präzise. Sie nennen die Datei, die KI erhält alles – ohne Mehrdeutigkeit. Voraussetzung: Sie kennen den Ort und akzeptieren höheren Token-Verbrauch.

Praxisbeispiel 1: API-Response-Format ändern (@Codebase)

Szenario: Next.js-API mit folgendem Response:

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

Ziel: Format von { data, total } zu { users, count } – Typdefinition unbekannt.

Mit @Files müssten Sie manuell suchen: route.ts, evtl. types.ts, Frontend-Komponente – leicht etwas vergessen.

Mit @Codebase im Chat:

@Codebase
Ändere das User-API-Response-Format von { data, total } zu { users, count }.
Passe alle Typdefinitionen und Frontend-Aufrufe entsprechend an.

Die KI liefert z. B.:

Gefundene relevante Dateien:
1. src/app/api/users/route.ts – API-Handler
2. src/types/api.ts – ApiResponse-Typ
3. src/components/UserList.tsx – Frontend (ruft API auf)
4. src/utils/mock.ts – Test-Mocks (nutzt dasselbe Format)

Sofort sichtbar: Auch mock.ts nutzt das Format – oft übersehen.

Praxisbeispiel 2: vite.config.ts optimieren (@Files)

Szenario: Proxy in vite.config.ts anpassen:

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

Ziel: Multi-Environment (Dev, Test, Prod).

→ @Files passt besser:

1. Pfad klar
2. Datei kurz (typisch 50–200 Zeilen)
3. Kein repo-übergreifendes Suchen nötig

Im Chat:

@Files vite.config.ts
Passe die Proxy-Konfiguration für mehrere Umgebungen an (Dev, Test, Prod).
Lese Umgebungsvariablen aus .env.development, .env.test, .env.production.

Die KI erhält die volle Datei und schlägt z. B. vor:

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

Fazit: Position unbekannt oder versteckte Verknüpfungen → @Codebase; Position bekannt oder lange Datei vollständig nötig → @Files.

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

4. @Docs: neue Bibliotheken und Dokumentation

@Docs löst: Trainingsdaten hinken der Dokumentation hinterher.

Neue Bibliothek, geänderte API (React-19-Hooks, Next.js 15 mit Turbopack) – die KI kann veraltete Syntax erzeugen.

@Docs ruft die gewählte Dokumentation ab, parst sie und fügt sie dem Kontext hinzu. Beim Generieren priorisiert die KI die aktuelle Spezifikation.

Nutzung

1. Im Chat @Docs eingeben
2. Framework-Dokumentation wählen (React, Vue, Astro, Tailwind, Next.js …)
3. Oder URL für eigene Quellen einfügen

Praktisch für interne Wikis oder Team-Docs – die KI kann danach teamkonformen Code vorschlagen.

Praxisbeispiel: React-19-Hook useOptimistic

Sie wollen useOptimistic, kennen die neueste Syntax nicht:

@Docs React
Implementiere Optimistic Update mit React-19 useOptimistic.
Szenario: Like-Button, sofort +1 anzeigen, dann Server-Bestätigung.

Die KI liest die React-Docs und generiert z. B.:

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // Sofort +1
    await onSubmit();     // Server-Bestätigung
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

Hinweis: Trainingsdaten können @Docs überlagern

Die KI mischt manchmal alte und neue APIs. Im Prompt betonen: neueste Dokumentation verwenden.

@Docs React
Bitte die neueste Syntax aus der Dokumentation (React 19), keine alten APIs aus den Trainingsdaten.

Wann @Docs?

Bibliothek/Framework neuer als Trainings-Cutoff oder große API-Änderung → @Docs.

Beispiele:

• React 19 (Ende 2024, große API-Updates)
• Next.js 15 (Turbopack standardmäßig)
• Aktuelle Supabase-Features
• Interne Team-Standards (nicht in Trainingsdaten)

Bei stabilen Stacks (React 18, Vue 3, Tailwind 3) reichen Trainingsdaten oft – @Docs weniger kritisch.

5. Best Practices für Kontextmanagement

Richtige @-Symbole sind Schritt eins – Kontext managen ist Schritt zwei. Lange Chats → die KI driftet ab, Code passt nicht mehr zum Ziel.

Prinzip: kurze Chats, getrennte Aufgaben

Nach einer abgeschlossenen Funktion Chat neu starten. Refactoring, Bugfix und neues Feature nicht in einem Thread mischen.

Jede Aufgabe braucht anderen Kontext: Refactoring → Typen, Handler, Aufrufer; Bugfix → Logs, Ausschnitte, Tests. Gemischt wird der Kontext unübersichtlich.

Einfach: oben rechts Clear Chat oder Shortcut für neuen Chat.

Kleine Edits vs. komplexe Aufgaben

Kleine Edits (eine Zeile, ein Parameter): Inline-Edit mit Cmd+K. Code markieren, Cmd+K, Anweisung – aktuelle Datei ist Kontext, ohne extra @-Mentions.

Komplexe Aufgaben (Modul refactoren, neue Komponente): Chat + @-Mentions. Erst @Codebase, dann @Files, dann klare Aufgabenbeschreibung.

Index: .cursorignore für Stördateien

@Codebase indexiert breit – nicht alles muss die KI sehen:

• node_modules/
• dist/, build/
• .env, .env.local
• große Medien

.cursorignore analog zu .gitignore, Frage: Braucht die KI diese Datei?

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

Kleinerer Index → schnellere Abfragen (oft 5–10 s auf 2–3 s), relevantere Treffer.

README.md aktuell halten

README ist ein Schlüssel für @Codebase. Klare README mit Struktur, Kernmodulen und recent changes hilft der KI, schneller zu verstehen und weniger zu wiederholen.

Pro vs. Free

Cursor Pro indexiert semantisch die ganze Codebasis; Free hat Grenzen. Ab ~500 Dateien wirkt @Codebase mit Pro deutlich besser.

Free-Nutzer: Kontext und Symbole diszipliniert nutzen, Stördateien ausschließen. Pro ist Bonus, nicht Voraussetzung.

6. FAQ: häufige Probleme

Problem 1: @Codebase passt nicht zur aktuellen Codebasis

Symptom: Gerade geänderte Datei liefert alte Inhalte, oder existierende Datei wird nicht gefunden.

Ursache: Index nicht synchron.

Lösung:

1. Cursor Settings → Reindex Codebase
2. Oder Projektordner entfernen und neu hinzufügen

1–2 Minuten warten, dann sollte es stimmen.

Problem 2: Falsche Treffer bei @Codebase

Symptom: Frage nach UserService, Treffer ist utils/user.ts statt services/UserService.ts.

Ursache: Mehrdeutigkeit bei semantischem Matching.

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

Jetzt testen →Anzeige

Lösung:

1. @Files mit korrekter Datei
2. Oder Pfad im Prompt: „Ändere src/services/UserService.ts“

@Codebase entdeckt automatisch, kann aber irren – präzise Aufgaben → @Files.

Problem 3: Alte API trotz @Docs

Symptom: @Docs React, Code sieht nach React 18 aus.

Ursache: Starke Prägung durch Trainingsdaten.

Lösung:

@Docs React
Bitte die neueste Syntax aus der Dokumentation (React 19), keine alten APIs aus den Trainingsdaten.

Problem 4: @Codebase langsam (5–10 s)

Symptom: Jede @Codebase-Abfrage dauert lange.

Ursache: Index zu groß (node_modules, dist …).

Lösung: .cursorignore prüfen:

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

Problem 5: Lange Historie, KI versteht falsch

Symptom: Nach mehreren Themen im Chat driftet die Antwort.

Ursache: Kontextverschmutzung.

Lösung: Clear Chat, neuer Thread pro Funktion.

Problem 6: Hoher Token-Verbrauch

Symptom: Pro-Kontingent schnell leer.

Ursache: Falsche Symbole, zu viel irrelevantes Material.

Lösung:

1. Kleine Edits: Cmd+K ohne @-Mentions
2. Präzise Aufgaben: @Files/@Code statt @Codebase mit vielen Nebentreffern
3. Große Ordner per .cursorignore ausschließen

Prinzip: Gezielt referenzieren, keine Volltextsuche über die ganze Codebasis.

Zusammenfassung

Cursors @-System in einem Satz: Unsicher → @Codebase; sicher → @Files/@Code; Dokumentation fehlt → @Docs.

Etwa 80 % der Zeit lohnt @Codebase – weil Entdecken der Wert ist: versteckte Typen in utils.ts, Mocks in Tests.

@Codebase ist nicht alles: Datei >600 Zeilen oder klarer Pfad → @Files. Kleiner Ausschnitt → @Code. Neue APIs → @Docs.

Kontext zählt: kurze Chats, eine Aufgabe pro Thread, .cursorignore, aktuelles README.

Vor dem nächsten Feature fragen: Kenne ich den Speicherort – oder soll die KI Verknüpfungen finden? Unsicher → @Codebase. Sicher → gezielt referenzieren.

So wird Cursor Partner statt Suchmaschine mit Rauschen.