Cursor-Regeln: So hältst du die KI im Einklang mit deinem Codebase

Du öffnest einen neuen Chat in Cursor und fügst denselben Anweisungsblock ein, den du schon hunderte Male eingefügt hast. Dein Stack, deine Namenskonventionen und die Ordnerstruktur, die die KI ständig falsch versteht. Dann produziert sie eine 40-zeilige Klasse mit drei Abstraktionsebenen für etwas, das eine Funktion gebraucht hätte.

Zeit, aus diesem Albtraum aufzuwachen. Cursor-Regeln sind Projektdateien, die das Einfügen überflüssig machen. Schreib deine Konventionen einmal auf, und die KI passt ihre Ausgaben an deine Codebasis an, statt dagegen anzukämpfen.

Dieses Tutorial erstellt eine Reihe von .mdc-Regeldateien für ein Python-Webprojekt mit FastAPI und pytest und behandelt Projektkontext, Codeschlichtheit und API-Fehlerformatierung. Wenn du neu bei Cursor bist, empfehle ich zuerst unseren Kurs Software Development with Cursor und dann ein Projekt zu öffnen und mitzumachen.

Was sind Cursor-Regeln?

Cursor-Regeln sind Markdown-Dateien mit MDC-spezifischem Frontmatter, die in deinem Projekt unter .cursor/rules/ liegen. Bevor deine Eingabe das Modell erreicht, prüft Cursor, welche Regeln passen, und stellt deren Inhalt vorne in das Kontextfenster. Deine Anweisungen landen jedes Mal zuerst.

Jede .mdc-Datei hat drei Frontmatter-Felder, die die Aktivierung steuern: description, globs und alwaysApply. Eine Regel kann in jedem Gespräch greifen oder nur, wenn bestimmte Dateien geöffnet sind. Eine dritte Option, Apply Intelligently, lässt den Agenten die Beschreibung lesen und selbst entscheiden, ob die Regel relevant ist. Im nächsten Abschnitt gehen wir alle Typen praktisch durch.

Cursor unterstützt vier Kategorien von Regeln:

Projektregeln haben die ältere Datei .cursorrules ersetzt – eine einzelne Datei auf Root-Ebene ohne Scoping oder Metadaten – indem sie Regeln in mehrere .mdc-Dateien mit Frontmatter aufteilen.

AGENTS.md ist die einfachere Alternative für Projekte, die kein Glob-Scoping brauchen. Es ist pures Markdown, das auch von KI-Coding-Tools außerhalb von Cursor erkannt wird; tiefere Dateien in Unterordnern überschreiben übergeordnete.

Mehr darüber, wie agentenbasierte Workflows in deinen Entwicklungsprozess greifen, lernst du in unserem Skill-Track AI Agent Fundamentals.

Cursor-Projektregeln erstellen und konfigurieren

Im weiteren Verlauf dieses Tutorials erstellen wir Regeldateien für ein FastAPI-Projekt mit pytest. Die Muster lassen sich auf jeden Stack übertragen.

Regelverzeichnis und -dateien einrichten

Erstelle ein Verzeichnis .cursor/rules/ im Projektstamm. Jede .mdc-Datei, die du hier ablegst, wird sofort als Regel erkannt – kein Neustart nötig.

Die erste Regeldatei, project-context.mdc, gibt der KI dauerhaftes Bewusstsein für deinen Stack und die Ordnerstruktur:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Das Tippen von /create-rule in einem Agent-Chat ist ein weiterer Einstieg: Cursor entwirft dir über ein Chat-Panel eine Regel.

Das Frontmatter alwaysApply: true bedeutet, dass diese Regel in jedem Gespräch geladen wird. Benenne Dateien im Kebab-Case nach Themen (project-context.mdc, simplicity.mdc, error-responses.mdc) und halte jede unter 500 Zeilen. Aufgeblähte Regeldateien fressen Platz im Kontextfenster, den du für echten Code und Prompts brauchst. Committe das Verzeichnis .cursor/rules/ in Git.

Regelmetadaten für präzises Matching konfigurieren

Die oben gezeigte Regel project-context.mdc nutzt alwaysApply: true – den einfachsten Modus: Jedes Gespräch lädt sie, egal, an welchen Dateien du gerade arbeitest. Das ist die richtige Wahl für projektweiten Kontext.

Manche Regeln gelten nur für bestimmte Teile der Codebasis. Setze alwaysApply: false und füge Globmuster als kommagetrennte Liste hinzu, um sie zu begrenzen. Eine Regel mit globs: app/routers/**/*.py greift nur, wenn passende Dateien (hier: Python-Dateien in app/routers/ oder Unterordnern) im Kontext auftauchen – so bleiben API-Konventionen aus irrelevanten Chats heraus.

Apply Intelligently verzichtet komplett auf Dateimuster. Du lässt globs leer und schreibst stattdessen eine aussagekräftige description, und der Agent entscheidet, ob die Regel zum aktuellen Gespräch passt. Die Qualität der Beschreibung zählt: "Error handling rules" ist zu vage für zuverlässiges Matching, aber "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" liefert klare Signale.

Regeln ohne Globs, ohne sinnvolle Beschreibung und mit alwaysApply: false werden manuell: Sie werden nur geladen, wenn du im Chat @rule-name eintippst. Praktisch für Referenzen, die du bei Bedarf hinzuziehst.

Regelinhalte und Vorgaben schreiben

Regeln in weicher Sprache („versuche, Funktionen klein zu halten“, „bevorzuge asynchrone Endpunkte“) geben der KI die Erlaubnis, sie zu ignorieren. Formuliere stattdessen Befehle: „Funktionen dürfen maximal 30 Zeilen haben. Alle Endpunkte müssen async sein.“

Im Intro ging es um die KI, die eine 40-zeilige Klasse mit drei Abstraktionsschichten erzeugt. Die Regel, die dieses Verhalten stoppt, ist simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

Der Unterschied ist sofort spürbar. Die KI greift nicht mehr zu abstrakten Basisklassen, wenn es nur eine Implementierung gibt, und nutzt If-Anweisungen, wenn es zwei Fälle sind.

Die dritte Regel, error-responses.mdc, ist per Glob so eingegrenzt, dass sie nur bei der Arbeit an API-Routen-Dateien auslöst:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Verweise, wenn möglich, auf bestehende Dateien in deiner Codebasis, statt Code in Regeln zu kopieren. Eine Zeile wie „Siehe app/routers/users.py für die kanonische Endpoint-Struktur“ bleibt korrekt, wenn sich der Code weiterentwickelt, während ein kopierter Schnipsel in dem Moment veraltet, in dem jemand das Original refaktoriert.

Regelanbindung testen und verifizieren

Cursor zeigt nicht an, welche Regeln in einem Gespräch aktiv sind. Du prüfst es, indem du das Verhalten testest.

Öffne einen neuen Agent-Chat und schreibe einen Prompt, der eine deiner Regeln auslösen sollte. Für error-responses.mdc probiere: „Füge einen DELETE-Endpunkt zum Entfernen eines Users per ID in app/routers/users.py hinzu.“ Wenn das generierte Error-Handling nichts mit der JSON-Struktur deiner Regel zu tun hat oder HTTPException mit dem detail-Dict überspringt, stimmt etwas mit dem Matching nicht.

Glob-basierte Regeln benötigen eine passende Datei, die im Prompt referenziert oder im Editor geöffnet ist. error-responses.mdc zu testen, ohne eine Datei unter app/routers/ zu erwähnen, bedeutet, dass die Regel nie aktiviert wird. 

„Apply Intelligently“-Regeln sind themenbasiert: Versuche einen Prompt, der zur Beschreibung passt, und einen, der nicht passt, und vergleiche die Ausgaben. Der Agent sollte die Regel im ersten Fall befolgen und im zweiten ignorieren.

So bleiben deine Cursor-Regeln wirksam

Regeln, die letzten Monat funktionierten, können die KI nach einem Refactor oder einer Ordnerumbenennung in die Irre führen.

Matching-Probleme beheben

Der häufigste Grund, warum eine Regel nicht greift, ist die Dateiendung: Regeln müssen .mdc verwenden; einfache .md-Dateien in .cursor/rules/ werden stillschweigend ignoriert.

Darüber hinaus gilt:

• Zu breite Globs wie **/*.py hängen die Regel an jede Python-Datei im Projekt. Enger fassen mit app/routers/**/*.py oder tests/**/*.py, damit die Regel nur dort greift, wo sie hingehört.

• Du bemerkst fehlende „Apply Intelligently“-Treffer, wenn die Beschreibung zu generisch ist. Die guten/schlechten Beispiele aus dem obigen Metadaten-Abschnitt gelten hier ebenso.

• Widersprüchliche Regeln sind schwerer zu erkennen. Wenn zwei Regeln für dieselben Dateien gegenteilige Anweisungen geben, wählt die KI eine (meist die zuletzt geladene). Behebe das, indem du die Globs enger fasst, sodass sie sich nicht überlappen, oder führe verwandte Leitlinien in einer Datei zusammen.

Eine Eigenheit, die du kennen solltest: Änderungen an .mdc-Dateien verschwinden manchmal ungespeichert. Wenn Bearbeitungen nicht übernommen werden, schließe Cursor komplett, wähle im Pop-up „Override“ bei ungespeicherten Änderungen und öffne es erneut.

Regeln im laufenden Gespräch verankern

Eine Regel kann zu Beginn korrekt greifen und fünf Nachrichten später ignoriert werden. Schuld ist die Aktualitätsverzerrung des Kontextfensters: Wenn das Gespräch wächst, priorisiert das Modell jüngere Nachrichten gegenüber Anweisungen, die oben injiziert wurden. Das ist die häufigste Beschwerde in der Cursor-Community, und es gibt keine Einstellung, die das behebt.

Der Workaround ist Verstärkung. Wenn die Ausgabe von deinen Regeln abdriftet, füge deinem nächsten Prompt eine Zeile wie „halte dich an die Projektre geln für Fehlermeldungen“ hinzu. Das holt die Anweisung zurück in den jüngsten Kontext des Modells. 

Für Regeln, die bei jeder Antwort zählen (Formatierung, Benennung), halten sich kürzere und direktere Formulierungen über lange Gespräche besser als ausformulierte Absätze.

Regeln mit Codebeispielen widerstehen dem Drift besser als reine Prosa. Statt „verwende Early Returns für Error-Handling“ zu schreiben, füge einen kurzen Vorher/Nachher-Block mit dem gewünschten Muster ein. Das Modell verankert sich zuverlässiger an echtem Code, besonders wenn der Kontext wächst.

Regeln pflegen und ausmisten

Überprüfe Regeln nach jedem größeren Refactor, Dependency-Upgrade oder einer Ordnerumstrukturierung. Eine Regel, die auf veraltete APIs oder entfernte Dateien verweist, gibt der KI falsche Anweisungen. Veraltete Globs sind noch tückischer: Benennst du app/api/ in app/routers/ um, feuert eine auf den alten Pfad begrenzte Regel einfach nicht mehr – ohne Warnung.

Ausmisten geht in die andere Richtung. Mit besseren Modellen werden gängige Konventionen auch ohne Vorgaben getroffen. Wenn die KI einer Regel ohnehin schon folgt, lösche sie und gewinne Tokens im Kontextfenster zurück. Ein gesundes Regelset schrumpft über die Zeit – es wächst nicht nur.

Regeln im Team skalieren

Behandle Regeln wie Anwendungscode. Änderungen gehen über Pull Requests, und das Team einigt sich auf ein Muster, bevor es in .cursor/rules/ landet.

Für Organisationen mit Business- oder Enterprise-Plänen ermöglichen Teamregeln Administratoren, Regeln zentral im Cursor-Dashboard durchzusetzen. „Sofort aktivieren“ schaltet eine Regel standardmäßig ein, lässt Nutzer sie aber deaktivieren. „Diese Regel erzwingen“ entfernt die Opt-out-Möglichkeit – passend für nicht verhandelbare Vorgaben wie Sicherheitspraktiken und Compliance-Anforderungen.

Fazit

Starte mit ein bis zwei Regeln für die Muster, die du am häufigsten korrigierst. Wenn du in jeder Session dieselbe Art von KI-Ausgabe nachbearbeitest (falsches Fehlerformat, unnötige Abstraktionen), wartet hier eine Regel darauf, geschrieben zu werden. Füge weitere hinzu, sobald du wiederkehrende Fehler siehst, und streiche diejenigen, die keinen Wert mehr liefern.

Die .mdc-Dateien aus diesem Tutorial passen zu einem FastAPI-Projekt. Für ein Next.js-Frontend oder ein Rust-CLI-Tool sieht es anders aus – und genau darum geht es: Sie kodifizieren die Konventionen deines Teams, nicht generische Best Practices. 

Wenn du tiefer in Cursor einsteigen willst, schau dir unseren Cursor 2.0 Guide an. Für Vergleiche mit anderen KI-Coding-Assistenten empfehle ich unsere Gegenüberstellungen:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf