Wie Entwicklungsteams Cursor-Regeln konfigurieren, um Architekturmuster und Coding-Standards über Repositories hinweg durchzusetzen

Entwicklungsteams setzen Architekturmuster und einheitliche Programmierstandards in Cursor durch, indem sie von monolithischen Legacy-Dateien wie .cursorrules auf modulare Projektregeln (.cursor/rules/*.mdc) umsteigen. Dabei werden Richtlinien über YAML-Frontmatter in globale Invarianten und pfadbezogene Grenzen (Globs) unterteilt und über Cursor Team Rules oder automatisierte CI/CD-Pipelines über mehrere Repositories hinweg synchronisiert und verwaltet.

Wird ein KI-Programmierassistent ohne klare Leitplanken im Unternehmen skaliert, droht eine schleichende "Architektur-Drift": Verschiedene Entwickler erhalten Code mit uneinheitlichen Paradigmen, Sprachmodelle halluzinieren veraltete interne Pakete und die automatische Codegenerierung umgeht fundamentale Domänengrenzen. Durch strukturierte, in Git versionierte Cursor-Regeln werden deterministische Leitplanken für KI-generierten Code geschaffen, während gleichzeitig wertvolle Prompt-Tokens eingespart werden.

Herausforderungen der KI-Governance in Ingenieurteams

Wird Cursor ohne zentrale Vorgaben eingeführt, stützen sich Sprachmodelle auf generische Trainingsdaten aus dem Web anstatt auf die spezifischen Konventionen des Unternehmens. Das führt in der Praxis zu typischen Problemen:

• Durchbrechen von Architekturschichten: Die KI platziert Datenbankabfragen direkt in UI-Komponenten oder leitet HTTP-spezifische Framework-Objekte ungefiltert an Domänenservices weiter.
• Einschleppen veralteter oder erfundener Abhängigkeiten: Modelle schlagen überholte interne Hilfsbibliotheken vor (z. B. das veraltete @company/legacy-ui anstelle von @company/design-system-v2) oder binden nicht freigegebene externe Pakete ein.
• Stilistische Fragmentierung: Im selben Projekt vermischen sich funktionale und objektorientierte Ansätze, Fehlerbehandlungen weichen voneinander ab und konkurrierende State-Management-Bibliotheken werden parallel genutzt.
• Mangelhafte Testabdeckung: Generierter Testcode verzichtet häufig auf Grenzfallprüfungen, nutzt veraltete Mocking-Tools oder vernachlässigt Tests bei Refactorings vollständig.

Um diesen Reibungsverlusten entgegenzuwirken, müssen Softwarearchitekten die internen Standards als persistente, versionskontrollierte Instruktionen direkt im Repository verankern.

Evolution der Regelarchitektur: Von .cursorrules zu modularen .mdc-Dateien

Ursprünglich verwendete Cursor eine einzelne .cursorrules-Datei im Root-Verzeichnis. Zwar bleibt diese Datei abwärtskompatibel, doch ein monolithischer Ansatz zwingt das System dazu, sämtliche Anweisungen bei jeder Interaktion in den Prompt zu laden. Das überlastet das Kontextfenster und schwächt die Befolgung komplexer Instruktionen.

Das moderne Regelsystem von Cursor basiert auf Projektregeln (Project Rules) im Verzeichnis .cursor/rules/, die als .mdc-Dateien (Markdown Cursor) mit YAML-Frontmatter strukturiert sind.

Aufbau einer .mdc-Regeldatei

Jede .mdc-Datei verbindet Metadaten zur Ausführung mit konkreten technischen Richtlinien:

---
description: Grenzen der Domänenservices und Repository-Muster
globs: src/domains/**/*.ts, src/services/**/*.ts
alwaysApply: false
---

# Architektur der Domänenschicht

- Domänenservices dürfen niemals rohe HTTP-Request-Objekte verarbeiten.
- Sämtliche Datenbankänderungen müssen über Repository-Interfaces abgewickelt werden.

Trigger-Optionen im Frontmatter

Das YAML-Frontmatter steuert exakt, wann und unter welchen Bedingungen die Regel in das Kontextfenster geladen wird:

Produktionserprobte Vorlagen für Softwarearchitekten

Ein wartbares Regelsystem unterteilt Konventionen in separate .mdc-Dateien nach dem Single-Responsibility-Prinzip. Nachfolgend sind drei praxiserprobte Vorlagen für Unternehmensanwendungen aufgeführt.

1. Globale Architektur-Invarianten (.cursor/rules/00-core-architecture.mdc)

Gilt projektweit und definiert die unverrückbare technische Basislinie.

---
description: Globale Architekturregeln, Basis-Tech-Stack und verbotene Pakete
alwaysApply: true
---

# Grundlegende Architektur-Invarianten

## Technologie-Stack & Versionen
- Laufzeitumgebung: Node.js v20 LTS
- TypeScript: v5.4+ mit `strict: true`
- Framework: Next.js App Router (v14+)
- State-Management: Zustand (Redux oder MobX sind untersagt)

## Verbotene Pakete und Muster
- UNTERSAGT: `axios` (Natives `fetch` über den Wrapper in `@lib/api-client` nutzen)
- UNTERSAGT: `@company/ui-core-v1` (Veraltet; `@company/design-system-v2` verwenden)
- UNTERSAGT: `moment.js` (Ausschließlich `date-fns` einsetzen)

## Standards für Codequalität
- Keine expliziten `any`-Typen. `unknown` in Kombination mit Type Guards verwenden.
- Guard Clauses und frühe Rückgaben (Early Returns) bevorzugen; verschachtelte `if/else`-Blöcke vermeiden.
- Niemals API-Schlüssel, Passwörter oder Geheimnisse im Quellcode ablegen.

2. Domänenschicht & Clean Architecture (.cursor/rules/backend-services.mdc)

Wird nur dann aktiv, wenn Entwickler Services oder Domänenlogik im Backend bearbeiten.

---
description: Hexagonale Architektur und Repository-Muster für Backend-Services
globs: src/services/**/*.ts, src/domains/**/*.ts
alwaysApply: false
---

# Standards für die Backend-Domänenschicht

## Verantwortung der Schichten
- Controller übernehmen die HTTP-Serialisierung, Parameter-Validierung und Statuscodes.
- Services implementieren die reine Geschäftslogik. Keine `req`- oder `res`-Objekte von Express/Fastify übergeben.
- Repositories kapseln den Datenzugriff. Services müssen von abstrakten Repository-Interfaces abhängen, nicht von ORM-Instanzen.

## Implementierungsbeispiele

```typescript
// ✅ KORREKT: Service hängt von abstraktem Interface ab und nutzt Domänen-Entitäten
export class OrderService {
  constructor(private readonly orderRepository: OrderRepositoryPort) {}

  async processOrder(orderId: string): Promise<Result<Order>> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) return Result.fail('Order not found');
    order.markPaid();
    await this.orderRepository.save(order);
    return Result.ok(order);
  }
}

// ❌ VERBOTEN: Direkte ORM-Aufrufe und Datenbankänderungen in der Domänenlogik
export class OrderService {
  async processOrder(orderId: string) {
    await prisma.orders.update({ where: { id: orderId }, data: { status: 'PAID' } });
  }
}

### 3. Standards für automatisierte Tests (`.cursor/rules/testing-standards.mdc`)

Stellt sicher, dass KI-generierte Tests die vorgegebenen Frameworks und Strukturen einhalten.

```markdown
---
description: Richtlinien für Unit- und Integrationstests sowie Verifikationsanforderungen
globs: **/*.test.ts, **/*.spec.ts, src/tests/**/*
alwaysApply: false
---

# Richtlinien für automatisierte Tests

## Test-Stack
- Test-Runner: Vitest
- Mocking: `vi.mock()` (Keine Module von Jest importieren)
- Assertions: `expect()` mit typisierten Matchern

## Strukturvorgaben für Tests
- Tests streng nach dem Muster Arrange-Act-Assert (Vorbereiten-Ausführen-Prüfen) aufbauen.
- Unit-Tests im selben Verzeichnis wie die Quelldatei anlegen: `feature.service.ts` -> `feature.service.test.ts`.
- In Unit-Tests externe Netzwerke und Datenbanken mocken; keine Live-Verbindungen aufbauen.
- Stets negative Testfälle abdecken (fehlende Parameter, fehlende Rechte, Ausnahmeszenarien).

Skalierung über Repositories: Monorepo- und Polyrepo-Strategien

Die unternehmensweite Durchsetzung von Standards erfordert je nach Repository-Struktur passende Governance-Modelle.

                         Zentrale Governance für Cursor-Regeln
                                          │
         ┌────────────────────────────────┴────────────────────────────────┐
         ▼                                                                 ▼
   Monorepo-Strategie                                              Polyrepo-Strategie
  ├── .cursor/rules/00-core.mdc                                   ├── Zentrales Repository: org-cursor-rules
  ├── .cursor/rules/apps-web.mdc (Glob: apps/web/**)              ├── CI/CD-Validierung und Synchronisation
  └── .cursor/rules/shared-ui.mdc (Glob: packages/**)             └── Cursor Team Rules (Admin-Dashboard)

Strategie A: Hierarchische Pfadabgrenzung in Monorepos

In Monorepos auf Basis von Turborepo, Nx oder pnpm-Workspaces liegen alle Regeln im Root-Ordner .cursor/rules/, grenzen sich aber über globs voneinander ab:

• globs: ["apps/web/**/*"]: Bestimmt Next.js-Muster, UI-Komponenten und Tailwind-Regeln.
• globs: ["apps/api/**/*"]: Erzwingt OpenAPI-Spezifikationen, Schema-Validierungen und Backend-Strukturen.
• globs: ["packages/ui/**/*"]: Sichert Abwärtskompatibilität, Barrierefreiheit (ARIA) und entkoppelte Shared-Pakete.
• Vorteil: Bei Arbeiten am Frontend werden keine Backend-Datenbankregeln geladen; der Prompt-Kontext bleibt fokussiert.

Strategie B: Synchronisation in Polyrepos über CI/CD (Rules as Code)

Für verteilte Microservice-Repositories werden Cursor-Regeln wie versionierte Softwarebibliotheken gepflegt:

1. Zentrales Regel-Repository: Ein dediziertes Git-Repository (z. B. github.com/org/cursor-rules-standards) enthält die offiziellen .mdc-Dateien mit SemVer-Tags (v1.2.0).
2. Drift-Prüfung in der CI: Die CI-Pipeline jedes Projekts prüft, ob die lokalen Regeln in .cursor/rules/ mit dem freigegebenen Versionsstand übereinstimmen.
3. Automatisierte Update-Workflows: Ein GitHub Actions- oder GitLab CI-Workflow klont neue Versionen und öffnet bei Änderungen automatisch Pull Requests in den Anwendungs-Repositories.

Strategie C: Zentrale Verwaltung über Cursor Team Rules

Unternehmen mit Cursor Team- oder Enterprise-Lizenzen können die Cloud-Verwaltung nutzen:

• Zentrale Bereitstellung im Dashboard: Administratoren hinterlegen Regeln direkt im Web-Dashboard; diese werden automatisch an alle authentifizierten Clients verteilt.
• Verbindliche vs. optionale Regeln: Sicherheitsrichtlinien und Technologie-Standards lassen sich als "Enforced" festlegen, sodass Entwickler sie lokal nicht deaktivieren können.
• Sofortige Verfügbarkeit: Neu geklonte Repositories oder neue Teammitglieder profitieren sofort von den Vorgaben, ohne dass Konfigurationsdateien manuell kopiert werden müssen.

Best Practices und typische Fehler

Durch modulare .mdc-Regeln mit gezielter Pfadbindung und die Synchronisation über Git oder Cursor Team Rules stellen Entwicklungsteams sicher, dass KI-gestützte Entwicklung zu schnelleren Ergebnissen führt, ohne die architektonische Integrität zu gefährden.

Referenzen

• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI