Cursor Rules: Wie man .cursor/rules-Dateien schreibt, die wirklich funktionieren

Jeder Cursor-Nutzer stößt irgendwann auf dasselbe Problem. Die KI generiert Code, der technisch funktioniert, aber die Konventionen Ihres Projekts ignoriert — falsche Import-Pfade, veraltete Muster, Komponenten, die nichts mit dem Rest Ihrer Codebasis gemeinsam haben. Cursor Rules lösen das, indem sie der KI dauerhaften Kontext darüber liefern, wie Ihr Projekt funktioniert.

Was sind Cursor Rules und warum sind sie wichtig?

Cursor Rules sind Markdown-Dateien, die als permanenter System-Prompt fungieren und vor jeder KI-Interaktion eingefügt werden — Chat, Autovervollständigung, Code-Generierung, alles. Stellen Sie sie sich als Einarbeitungsdokumentation für die KI vor. Anstatt in jeder Sitzung dieselben Fehler zu korrigieren, schreiben Sie die Anweisung einmal, und sie bleibt bestehen.

Der alte Ansatz war eine einzelne .cursorrules-Datei im Projektstammverzeichnis. Das funktioniert noch, ist aber veraltet. Das aktuelle System verwendet ein .cursor/rules/-Verzeichnis mit einzelnen .mdc-Dateien (Markdown Cursor), die jeweils auf bestimmte Situationen zugeschnitten sind. Das ist eine viel bessere Lösung, weil Sie nicht alle Anweisungen in eine riesige Datei quetschen müssen — Sie teilen Regeln nach Zuständigkeiten auf, und Cursor lädt nur diejenigen, die für Ihre aktuelle Tätigkeit relevant sind.

Wenn Sie mit Context Engineering für KI-Tools vertraut sind, ist das Konzept bekannt: Besserer Eingabekontext liefert deutlich bessere Ergebnisse. Rules sind Context Engineering für Ihren gesamten Entwicklungs-Workflow.

Ihre erste Regel-Datei einrichten

Erstellen Sie das .cursor/rules/-Verzeichnis in Ihrem Projektstammverzeichnis:

mkdir -p .cursor/rules

Jede Regel ist eine .mdc-Datei mit YAML-Frontmatter gefolgt von Markdown-Inhalt. Hier ist das Grundgerüst:

---
description: "Wann diese Regel gelten soll"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Ihre Anweisungen stehen hier im einfachen Markdown.

Drei Frontmatter-Felder steuern alles:

Sie können Regeln auch direkt in Cursor erstellen — geben Sie /create-rule im Chat ein und beschreiben Sie, was Sie möchten. Das manuelle Schreiben gibt Ihnen jedoch mehr Kontrolle.

Die vier Regeltypen erklärt

Wie eine Regel aktiviert wird, hängt von der Frontmatter-Konfiguration ab. Es gibt vier Modi, und die richtige Wahl ist entscheidend für Ihr Kontextfenster-Budget.

Immer anwenden

---
alwaysApply: true
---

Wird in jede einzelne KI-Anfrage geladen. Verwenden Sie dies sparsam — für projektweite Grundlagen wie Ihre Tech-Stack-Deklaration oder kritische Konventionen, die überall gelten. Jede dauerhaft aktive Regel verbraucht bei jeder Interaktion Tokens, ob relevant oder nicht.

Automatisch angehängt (Glob-basiert)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Wird nur aktiviert, wenn Sie Dateien bearbeiten, die den Glob-Mustern entsprechen. Dies ist der wichtigste Regeltyp. Ihre React-Komponenten-Konventionen werden geladen, wenn Sie in Komponentendateien arbeiten, Ihre API-Muster beim Arbeiten in Route-Handlern, Ihre Testregeln beim Schreiben von Tests.

Vom Agenten angefordert (intelligent)

---
description: "Datenbankmigrierungsmuster mit Drizzle ORM"
alwaysApply: false
---

Keine Globs, kein Always-Apply — nur eine Beschreibung. Cursors Agent liest die Beschreibung und entscheidet, ob die Regel für die aktuelle Aufgabe relevant ist. Wenn Sie ihn bitten, eine Migration zu schreiben, zieht er diese Regel heran. Wenn Sie einen Button gestalten, überspringt er sie. Das funktioniert erstaunlich gut für Regeln, die sich nicht sauber auf Dateipfade abbilden lassen.

Manuell

---
---

Keine Frontmatter-Felder gesetzt (oder leeres Frontmatter). Diese Regeln werden nur aktiviert, wenn Sie sie explizit mit @regel-name im Chat erwähnen. Gut für selten verwendete, aber wichtige Anweisungen — wie Deployment-Checklisten oder Refactoring-Leitfäden, die Sie nur gelegentlich benötigen.

Glob-Muster, die wirklich funktionieren

Globs bestimmen, welche Dateien automatisch angehängte Regeln auslösen. Wenn sie falsch sind, werden Ihre Regeln entweder nie ausgelöst oder überall. Hier ist, was funktioniert:

# Alle TypeScript-Dateien in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Nur Komponentendateien
globs: ["**/components/**/*.tsx"]

# Python-Dateien, ohne Tests
globs: ["**/*.py", "!**/test_*.py"]

# Mehrere spezifische Verzeichnisse
globs: ["src/api/**", "src/services/**"]

Ein paar Tücken aus der Praxis:

• src/* entspricht nur einer Verzeichnisebene. Sie wollen fast immer src/**/* für rekursives Matching.
• *.js entspricht nicht .jsx- oder .ts-Dateien. Seien Sie explizit bei Erweiterungen.
• Globs müssen eine YAML-Liste sein. Die Klammerschreibweise wie {src,lib}/**/*.ts kann lautlos scheitern — verwenden Sie lieber separate Listeneinträge.
• Das !-Präfix schließt Muster aus, was nützlich ist, um generierte Dateien oder Legacy-Code zu ignorieren.

Praktische Regelbeispiele

Hier trifft Theorie auf Realität. Das sind Regeln, die Sie in ein Projekt einfügen und sofort bessere KI-Ausgaben sehen werden.

Projektweite Basisregel (Immer anwenden)

---
alwaysApply: true
---

# Projekt: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Halten Sie dies unter 30 Zeilen. Es wird bei jeder Anfrage geladen, also kostet jedes Wort Tokens.

React-Komponenten-Regel (Automatisch angehängt)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Python-API-Regel (Automatisch angehängt)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Go-Service-Regel (Automatisch angehängt)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Die Token-Steuer verwalten

Hier ist etwas, das die meisten Cursor-Anleitungen überspringen: Jede Regel, die Sie schreiben, kostet Tokens. Ein Projekt mit 20 dauerhaft aktiven Regeln könnte **über 2.000 Tokens pro Anfrage** allein für Anweisungen verbrauchen — bevor die KI überhaupt Ihren Code betrachtet.

Das ist wichtig, weil Cursors Chat-Kontext im Standardmodus etwa 20.000 Tokens umfasst. Wenn Ihre Regeln 25 % davon verbrauchen, haben Sie ein Viertel des KI-"Denkraums" für Ihre eigentliche Frage verloren. Sie werden schlechtere Ausgabequalität bemerken, wenn sich Regeln anhäufen, besonders in längeren Gesprächen.

Drei Grundsätze halten Ihr Token-Budget gesund:

**1. Verwenden Sie automatisch angehängte und vom Agenten angeforderte Regeln konsequent.** Nur Ihre Projektstack-Deklaration sollte dauerhaft aktiv sein. Alles andere sollte bedingt geladen werden. Diese React-Komponenten-Regel? Sie muss nicht im Kontext sein, wenn Sie SQL-Migrationen schreiben.

**2. Schreiben Sie präzise, nicht ausschweifend.** Ersetzen Sie "Es wird dringend empfohlen, dass Entwickler TypeScript-Interfaces anstelle von Type-Aliases verwenden, wenn öffentliche API-Verträge definiert werden" durch "Prefer `interface` over `type` for public APIs." Die KI braucht keine Überzeugungsarbeit — sie braucht Anweisungen.

**3. Wenden Sie die Drei-Mal-Regel an.** Kodifizieren Sie ein Muster erst als Regel, wenn die KI es dreimal falsch gemacht hat. Wenn Cursor Ihre Namenskonventionen bereits ohne eine Regel richtig handhabt, überspringen Sie die Regel. Jede unnötige Regel ist verschwendeter Kontext.

Sie können die Token-Nutzung in der Statusleiste am unteren Rand von Cursors Chat-Panel überwachen. Achten Sie darauf, wenn sie sich 100 % nähert — das ist Ihr Signal zum Kürzen.

## Regeln für ein echtes Projekt organisieren

Ein Produktionsprojekt benötigt typischerweise 5-8 Regeldateien. Hier ist eine Struktur, die gut funktioniert:

```text
.cursor/rules/
  base.mdc            # Tech-Stack, always-apply (< 30 Zeilen)
  components.mdc      # React/Vue-Muster, Glob zu Komponentenverzeichnissen
  api.mdc             # Backend-Konventionen, Glob zu API-Verzeichnissen
  database.mdc        # ORM-Muster, Glob zu Models/Migrations
  testing.mdc         # Testkonventionen, Glob zu Testdateien
  deployment.mdc      # CI/CD-Muster, manueller Auslöser
  personal.mdc        # Ihre Präferenzen (gitignored)

Committen Sie alles in die Versionskontrolle außer personal.mdc. So erhält Ihr gesamtes Team das gleiche KI-Verhalten — was der eigentliche Sinn ist. Wie ein Cursor-Forum-Nutzer es ausdrückt, bedeuten gute Regeln, dass Sie "mehr Vorschläge direkt akzeptieren, mit Ausgaben, die beim ersten Versuch Ihren Konventionen entsprechen."

Wenn Sie neben Cursor andere KI-Coding-Tools verwenden, lassen sich die Konzepte direkt übertragen. Claude Code verwendet CLAUDE.md, GitHub Copilot hat Instruktionsdateien, und Windsurf hat sein eigenes Format — aber das zugrundeliegende Prinzip ist identisch.

Wie Regelvorrang funktioniert

Wenn mehrere Regeln auf dieselbe Datei zutreffen, folgt Cursor einer klaren Hierarchie:

Team Rules sind in Team- und Enterprise-Tarifen verfügbar. Sie werden im Cursor-Dashboard von Administratoren festgelegt und organisationsweit durchgesetzt — einzelne Entwickler können sie nicht deaktivieren.

Innerhalb von Projektregeln ist das Verhalten nicht streng definiert, wenn zwei Regeln auf dieselbe Datei zutreffen und in Konflikt stehen. In der Praxis haben später geladene Regeln Vorrang. Durch Nummerierung Ihrer Dateien (001-base.mdc, 002-components.mdc) erhalten Sie vorhersehbare Reihenfolge.

Häufige Fehler und wie man sie behebt

Nach dem Lesen durch Dutzende von Community-Threads und dem Testen von Regeln in verschiedenen Projekten sind dies die Fehler, über die die meisten stolpern:

Regeln schreiben, die zu vage sind. "Schreiben Sie sauberen Code" sagt der KI nichts. "Verwenden Sie benannte Exporte, keine Standard-Exporte. Strukturieren Sie Komponenten als: Importe, Typen, Funktion, Teilkomponenten" gibt ihr etwas Umsetzbares.

Alles auf always-apply setzen. Der erste Instinkt ist, alwaysApply: true bei jeder Regel zu setzen. Widerstehen Sie. Überprüfen Sie Ihre Regeln vierteljährlich — wenn Sie mehr als 2-3 dauerhaft aktive Regeln haben, verschwenden Sie wahrscheinlich Tokens.

Vergessen, Regeln zu testen. Nachdem Sie eine Regel geschrieben haben, öffnen Sie eine relevante Datei und bitten Sie Cursor, etwas zu generieren, das der Regel folgen sollte. Wenn nicht, könnte Ihr Glob-Muster falsch sein, oder die Anweisung ist nicht klar genug.

Anti-Patterns nicht dokumentieren. Der KI zu sagen, was sie tun soll, ist die halbe Arbeit. Ihr zu sagen, was sie nicht tun soll, ist die andere Hälfte. Fügen Sie in jede Regel einen Abschnitt "NIEMALS diese Muster verwenden" mit expliziten Beispielen des falschen Ansatzes ein.

Regelspeicherungen in der UI ignorieren. Ein bekannter Fehler führt dazu, dass Regeländerungen verschwinden. Wenn Änderungen verschwinden, schließen Sie Cursor vollständig, wählen Sie "Überschreiben" im Popup für nicht gespeicherte Änderungen und öffnen Sie es erneut.

Cursor Rules vs. CLAUDE.md vs. AGENTS.md

Cursor ist nicht das einzige Tool, das Instruktionsdateien verwendet. Hier ist ein Vergleich der Formate für alle, die mit mehreren KI-Coding-Assistenten arbeiten:

Cursors Vorteil ist die Granularität. CLAUDE.md und AGENTS.md sind einfacher — sie laden alles immer. Cursor ermöglicht es Ihnen, die richtigen Regeln zur richtigen Zeit zu laden, was wichtig wird, sobald Ihr Anweisungsset über ein paar hundert Zeilen hinauswächst.

Für einen tieferen Einblick, wie Kontext die KI-Ausgabe in diesen Tools beeinflusst, erklärt unser Context-Engineering-Leitfaden die Prinzipien, die unabhängig davon gelten, welchen Editor Sie verwenden.

FAQ

Ist .cursorrules veraltet?

Ja. Die einzelne .cursorrules-Datei in Ihrem Projektstammverzeichnis funktioniert noch, aber Cursor empfiehlt die Migration zu .cursor/rules/*.mdc-Dateien. Das neue Format unterstützt Glob-Muster, bedingtes Laden und bessere Organisation. Migrieren Sie, indem Sie Ihre monolithische Datei in fokussierte Regeln aufteilen.

Welche Dateiendung sollte ich verwenden — .mdc oder .md?

Verwenden Sie .mdc für Dateien, die YAML-Frontmatter enthalten (description, globs, alwaysApply). Einfache .md-Dateien funktionieren auch im Rules-Verzeichnis, unterstützen aber nicht die Frontmatter-Metadaten, die bedingtes Laden ermöglichen.

Wie viele Regeln sollte ein Projekt haben?

Fünf bis acht ist das optimale Maß für die meisten Projekte. Eine dauerhaft aktive Basisregel, drei bis vier automatisch angehängte Regeln nach Dateityp und eine oder zwei manuelle Regeln für besondere Aufgaben. Mehr als 10 Regeln bedeutet meist, dass einige konsolidiert oder entfernt werden können.

Beeinflussen Cursor Rules die Autovervollständigung und Tab-Vervollständigung?

Regeln gelten für Chat- und Agenten-Interaktionen. User Rules gelten nicht für Inline-Bearbeitungen (Cmd/Strg+K), und Regeln haben generell keinen Einfluss auf Cursor Tab-Autovervollständigungs-Vorschläge. Sie sind am effektivsten in Chat- und Composer-Sitzungen.

Kann ich Regeln über mehrere Projekte hinweg teilen?

Ja, über Cursors Remote-Rules-Funktion. Gehen Sie zu Cursor Settings > Rules, Commands, wählen Sie "Remote Rule (GitHub)" und fügen Sie eine Repository-URL ein. Regeln werden automatisch synchronisiert, wenn das Quell-Repository aktualisiert wird. Alternativ können Sie ein gemeinsames Rules-Repository pflegen und in jedes Projekt verlinken.

Was ist die empfohlene maximale Regellänge?

Cursors Dokumentation empfiehlt, einzelne Regeln unter 500 Zeilen zu halten. In der Praxis sollten Sie unter 100 Zeilen pro Regel bleiben. Kürzere Regeln sind einfacher zu pflegen und kosten weniger Tokens. Wenn eine Regel 150 Zeilen überschreitet, teilen Sie sie in zwei fokussierte Regeln auf.

Funktionieren Regeln mit allen KI-Modellen in Cursor?

Regeln funktionieren mit jedem Modell, das Cursor unterstützt — Claude, GPT-4o, Gemini und andere. Die Regeln werden als Kontext auf Systemebene injiziert, unabhängig davon, welches Modell Sie ausgewählt haben. Das Modellverhalten kann variieren, aber die Regeln selbst sind modell-agnostisch.

Wie debugge ich eine Regel, die nicht funktioniert?

Überprüfen Sie zunächst, ob das Glob-Muster zu Ihrer Datei passt — öffnen Sie die Datei und prüfen Sie, ob die Regel im Kontext-Panel erscheint. Testen Sie dann mit einer direkten Frage, die die Regel auslösen sollte. Versuchen Sie anschließend, alwaysApply: true vorübergehend zu setzen, um zu bestätigen, dass der Regelinhalt selbst funktioniert. Wenn ja, liegt das Problem in Ihrem Glob-Muster.

Sollte ich .cursor/rules in git committen?

Unbedingt. Der gesamte Sinn von Projektregeln ist teamweite Konsistenz. Committen Sie alles in .cursor/rules/ außer persönlichen Präferenzdateien. Fügen Sie personal.mdc zur .gitignore für individuelle Einstellungen hinzu, die nicht für alle gelten sollen.

Kann ich Cursor Rules zusammen mit MCP-Servern verwenden?

Ja, und sie ergänzen sich gut. Regeln definieren wie die KI Code schreiben soll, während MCP-Server der KI Zugang zu externen Tools und Daten geben. Eine Regel könnte besagen "verwende immer unseren internen API-Client", während ein MCP-Server der KI ermöglicht, diese API während der Entwicklung tatsächlich abzufragen.

Wenn KI-Funktionen auf Ihrer Roadmap stehen, ist das unsere Spezialität: Das KI-Integrationsteam von Techsy bringt LLM-Systeme vom Prototyp in die Produktion. Sie möchten eine zweite Meinung zu Ihrem Stack? Fordern Sie eine kostenlose Beratung an.

Quellen

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub