MDC-Regeln Best Practices und Fehlerbehebung in Cursor

MDC-Regeln (Markdown Configuration) sind Cursors leistungsstarke Möglichkeit, Codierungsstandards, Projektkonventionen und KI-Verhaltensrichtlinien durchzusetzen. Bei korrekter Konfiguration verbessern sie die Codequalität und Konsistenz erheblich. Dieser Guide behandelt Best Practices für das Erstellen, Organisieren und Fehlerbeheben von MDC-Regeln.

Was sind MDC-Regeln?

MDC-Regeln sind Markdown-Dateien mit YAML-Frontmatter, die Cursor mitteilen, wie es sich bei der Arbeit mit bestimmten Dateien oder in bestimmten Kontexten verhalten soll. Sie können:

• Codierungsstandards durchsetzen
• Projektarchitekturmuster definieren
• Dokumentationsanforderungen festlegen
• KI-Verhalten für bestimmte Dateitypen steuern

Dateiformatanforderungen

MDC-Regeln müssen genau dieses Format einhalten:

---
description: 'Regelbeschreibung hier'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# Regeltitel

Ihr Regelinhalt hier...

## Spezifische Richtlinien

- Richtlinie 1
- Richtlinie 2

Kritische Anforderungen

Anforderung	Details
Erweiterung	Muss .mdc sein (nicht .md)
Front matter	Muss YAML-Format zwischen --- Trennzeichen verwenden
Speicherort	Muss im Verzeichnis .cursor/rules/ sein
globs	Array von Dateimustern, auf die diese Regel zutrifft
alwaysApply	Boolesch - ob ohne Dateiübereinstimmung angewendet wird

Namenskonvention

Verwenden Sie ein nummeriertes Präfixsystem zur Organisation:

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

Nummerierungssystem

Bereich	Kategorie	Beispiel
001-099	Kernregeln (gelten für alle Dateien)	Codierungsstandards, Formatierung
100-199	Integrationsregeln (spezifische Domänen)	API, Datenbank, Authentifizierung
200-299	Muster/Rollenregeln	Tests, Dokumentation
300-399	Technologiespezifisch	React, Vue, Angular

Effektive Regeln schreiben

Seien Sie spezifisch und handlungsorientiert

Schlecht:

Schreiben Sie guten Code.

Gut:

## Fehlerbehandlung

Alle asynchronen Funktionen müssen try/catch-Blöcke verwenden:

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### Beispiele einbeziehen

Zeigen Sie immer sowohl korrekte als auch inkorrekte Beispiele:

```markdown
## Zustandsverwaltung

✅ TUN: React Query für Serverzustand verwenden
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ NICHT TUN: useEffect für Datenabruf verwenden

// Dieses Muster vermeiden
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### Glob-Muster effektiv nutzen

```yaml
# Auf alle TypeScript-Dateien anwenden
globs: ['**/*.ts', '**/*.tsx']

# Nur auf Backend-Code anwenden
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# Auf bestimmte Testdateien anwenden
globs: ['**/*.test.ts', '**/*.spec.ts']

# Bestimmte Dateien ausschließen
globs: ['src/**/*.ts', '!src/generated/**']

Häufige Regelkategorien

1. Code-Stil-Regeln

---
description: 'Konsistenten Code-Stil durchsetzen'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# Code-Stil-Standards

## Importe
- Importe gruppieren: React, externe Libs, interne Module, Typen
- Absolute Importe für src/-Module verwenden
- Innerhalb der Gruppen alphabetisch sortieren

## Benennung
- Komponenten: PascalCase (UserProfile)
- Hooks: camelCase beginnend mit 'use' (useAuth)
- Konstanten: UPPER_SNAKE_CASE
- Dateien: kebab-case (user-profile.tsx)

2. Architekturregeln

---
description: 'Clean Architecture Patterns durchsetzen'
globs: ['src/**/*.ts']
alwaysApply: false
---

# Architekturrichtlinien

## Schichtabhängigkeiten
- Domain-Schicht: Keine externen Abhängigkeiten
- Anwendungsschicht: Hängt nur von Domain ab
- Infrastrukturschicht: Hängt von Anwendung ab

## Dateiorganisation

src/ domain/ # Geschäftslogik, Entitäten application/ # Anwendungsfälle, DTOs infrastructure/ # DB, API, externe Dienste presentation/ # UI-Komponenten

3. Testregeln

---
description: 'Testanforderungen und Muster'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# Teststandards

## Erforderliche Tests
- Unit-Tests für alle Hilfsfunktionen
- Komponententests für alle React-Komponenten
- Integrationstests für API-Endpunkte
- E2E-Tests für kritische Benutzerabläufe

## Teststruktur
AAA-Muster folgen:
1. Arrange: Testdaten und Mocks einrichten
2. Act: Die zu testende Funktion ausführen
3. Assert: Die Ergebnisse überprüfen

Fehlerbehebung häufiger Probleme

Problem 1: Änderungen werden nicht gespeichert

Symptom: Sie bearbeiten eine .mdc-Datei, speichern sie, aber Cursor wendet die Änderungen nicht an.

Lösung:

1. Cursor vollständig schließen (nicht nur das Fenster - die Anwendung beenden)
2. Cursor erneut öffnen
3. Die Änderungen sollten jetzt angewendet werden

Warum das passiert: MDC-Regeln werden beim Start von Cursor zwischengespeichert. Sie laden nicht automatisch neu.

Problem 2: Regeln werden nicht angewendet

Symptom: Cursor ignoriert Ihre Regeln beim Bearbeiten von Dateien.

Checkliste:

• Dateierweiterung ist .mdc (nicht .md)
• Datei befindet sich im Verzeichnis .cursor/rules/
• Front matter hat gültige YAML-Syntax
• globs-Muster stimmt mit Ihren Zieldateien überein
• Keine Syntaxfehler im Markdown-Inhalt

Debug-Befehl:

# Überprüfen, ob Cursor Ihre Regeln erkennt
ls -la .cursor/rules/
# Dateierweiterungen überprüfen
file .cursor/rules/*

Problem 3: Konfliktierende Regeln

Symptom: Mehrere Regeln geben widersprüchliche Anweisungen.

Auflösungsreihenfolge:

1. Regeln mit spezifischeren Glob-Mustern haben Vorrang
2. Regeln mit alwaysApply: true werden zuerst ausgewertet
3. Spätere Regeln in alphabetischer Reihenfolge überschreiben frühere

Best Practice: Das Feld priority verwenden (falls unterstützt):

---
description: 'Regel mit hoher Priorität'
globs: ['src/**/*.ts']
priority: 100
---

Problem 4: Regeln zu lang

Symptom: Cursor folgt nicht allen Anweisungen in einer langen Regel.

Lösung: In mehrere fokussierte Regeln aufteilen:

.cursor/rules/
  001-general-style.mdc       # Kurze, allgemeine Richtlinien
  002-error-handling.mdc      # Spezifisch für Fehlerbehandlung
  003-performance.mdc         # Leistungsoptimierungen

Erweiterte Techniken

Bedingte Regeln

Verwenden Sie globs, um verschiedene Regeln auf verschiedene Teile Ihrer Codebasis anzuwenden:

# Frontend-Regeln
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
React-Hooks-Muster verwenden. Funktionale Komponenten bevorzugen.

# Backend-Regeln
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
Dependency Injection verwenden. SOLID-Prinzipien folgen.

Regelvererbung

Erstellen Sie eine Basisregel und erweitern Sie sie:

---
description: 'Basis TypeScript-Standards'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# Basis TypeScript-Regeln

- Strikte TypeScript-Konfiguration verwenden
- Keine `any`-Typen ohne Begründungskommentar
- `interface` gegenüber `type` für Objektformen bevorzugen

---
description: 'React-spezifische Erweiterungen'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# React-Regeln

Zusätzlich zu den Basis TypeScript-Regeln:
- Funktionale Komponenten mit Hooks verwenden
- Props-Interfaces müssen exportiert werden
- React.FC sparsam verwenden (explizites Props-Typing bevorzugen)

Dynamische Regeln mit Variablen

Einige erweiterte Setups unterstützen Vorlagenvariablen:

---
description: 'Projektspezifische Konventionen'
globs: ['**/*.ts']
---

# Projektkonventionen

## API-Basis-URL
Verwenden: {{API_BASE_URL}}

## Authentifizierung
Token-Header: {{AUTH_HEADER_NAME}}

Schnellreferenz: MDC-Regelvorlage

---
description: ''
globs: ['']
alwaysApply: false
---

# Titel

## Abschnitt 1
- Richtlinie 1
- Richtlinie 2

## Abschnitt 2
```typescript
// Beispielcode

Referenzen

• Link zur Dokumentation

## Verwandte Ressourcen

- [Cursor-Regeln effektiv nutzen](using-cursor-rules-effectively.mdx)
- [Best Practices für Cursor-Regeln](best-practices-for-cursor-rules.mdx)
- [CursorRules Setup-Guide](cursorrules-setup-guide.mdx)