Cursor Rules im Monorepo: jedes Paket eingrenzen, ohne alles zu wiederholen

Wie Cursor entscheidet, welche Regeln gelten

Cursor kennt vier Arten von Regeln: Team Rules, die in Team- und Enterprise-Plänen im Dashboard verwaltet werden, Projektregeln als .mdc-Dateien in .cursor/rules, User Rules und AGENTS.md. Das Frontmatter einer Projektregel entscheidet, wann sie geladen wird. Mit alwaysApply auf true ist sie in jedem Chat. Mit Globs wird sie angehängt, sobald eine passende Datei im Kontext ist. Mit nur einer Beschreibung entscheidet der Agent. Ohne all das gilt sie nur, wenn jemand sie erwähnt. Eine einfache .md-Datei in .cursor/rules wird ignoriert.

In einem Monorepo zählen drei Details. Alle zutreffenden Regeln werden zusammengeführt, wobei bei Widersprüchen Team Rules vor Projektregeln und diese vor User Rules stehen. Regeln werden über ihren vollständigen Pfad identifiziert, sodass zwei gleichnamige Dateien in verschiedenen Ordnern beide gelten. Und Cursor behandelt eine CLAUDE.md wie AGENTS.md, wendet sie aber immer an. Eine große CLAUDE.md im Wurzelverzeichnis, geschrieben für Claude Code, kostet also auch in jedem Cursor-Chat Kontext.

Ein Aufbau, der nach Paketen eingrenzt

AGENTS.md                       # shared commands and conventions
.cursor/rules/
  repo-basics.mdc               # alwaysApply: true, a few lines
  billing/money.mdc             # globs: packages/billing/**
  web/components.mdc            # globs: packages/web/src/**/*.tsx
  migrations.mdc                # description only, agent decides
packages/
  billing/AGENTS.md             # billing build and test commands
  web/AGENTS.md                 # web build and test commands

Die beiden Mittel zur Eingrenzung dienen verschiedenen Zwecken. Glob-Regeln halten Konventionen an einer Stelle im Wurzelverzeichnis und können verstreute Pfade treffen, etwa jeden Migrationsordner. Eine verschachtelte AGENTS.md liegt beim Paket, das sie beschreibt, und Cursor kombiniert sie mit den Dateien darüber, wobei die spezifischere Datei Vorrang hat. Andere Agenten lesen dieselbe Datei ebenfalls, was in einem Monorepo hilft, in dem manche Teams Claude Code oder Codex nutzen.

Entscheiden, wohin eine Regel gehört

• Gilt in jedem Paket und ist kurz: die immer angewendete Regel im Wurzelverzeichnis oder die AGENTS.md dort. Jede Zeile hier kostet in jedem Chat.
• Gilt in einem Paket: eine Glob-Regel für dessen Pfade oder eine eigene AGENTS.md.
• Ein Ablauf, der ab und zu gebraucht wird, etwa eine Migration schreiben: eine Regel nur mit Beschreibung, die der Agent bei Bedarf hinzuzieht, oder eine manuelle Regel.
• Ein Standard über alle Repositories: eine Team Rule, erzwungen, wo sie nicht abschaltbar sein darf. Cursor selbst warnt, dass KI-Anweisungen nicht Ihre einzige Sicherheitskontrolle sein sollten.
• Alles, was ein Linter oder die CI prüfen kann: das Werkzeug, keine Regel. Die Cursor-Dokumentation rät davon ab, Styleguides in Regeln zu kopieren.

Eine Falle: Eine Regel, die eine Datei mit @ erwähnt, sagt dem Agenten, wo er nachsehen soll, fügt den Inhalt der Datei aber nicht ein. Was immer im Kontext sein muss, gehört in den Text der Regel selbst.

Verantwortung, die dem Paket folgt

Regeln verfallen, wenn niemand für sie verantwortlich ist. Ordnen Sie dem Paketteam seine Regeldateien über CODEOWNERS zu und dem Plattform-Team die immer angewendeten Regeln, denn diese kosten alle Kontext. Der Leitfaden von Claude Code zu großen Codebasen beschreibt dieselbe Aufteilung für Anweisungsdateien pro Verzeichnis: Die Verantwortlichen eines Verzeichnisses pflegen dessen Datei.

/.cursor/rules/                  @example-org/platform
/AGENTS.md                       @example-org/platform
/.cursor/rules/billing/          @example-org/billing
/packages/billing/AGENTS.md      @example-org/billing
/.cursor/rules/web/              @example-org/web
/packages/web/AGENTS.md          @example-org/web

GitHub wendet das letzte passende Muster in CODEOWNERS an, deshalb stehen die Paketzeilen nach dem allgemeinen Regelverzeichnis. Cursor empfiehlt, jede Regel unter 500 Zeilen zu halten und große Regeln aufzuteilen, und die Verantwortung nach Paketen macht diese Aufteilung naheliegend.

Überschneidungen finden, bevor der Agent es tut

Da alle zutreffenden Regeln zusammengeführt werden, kann ein Konflikt aus jeder Kombination von Quellen entstehen: Team Rules, die eigenen User Rules eines Engineers, die immer angewendete Regel im Wurzelverzeichnis, AGENTS.md-Dateien im Wurzelverzeichnis und in Unterordnern, Glob-Regeln, Regeln, die der Agent anhand der Beschreibung auswählt, und Regeln, die jemand von Hand erwähnt. Ein typischer Fall im Monorepo sind zwei Globs, die auf dieselbe Datei passen. In einem hypothetischen Repository nutzt web/components.mdc das Muster **/*.tsx und hängt sich damit auch an packages/admin, dessen Team Komponenten anders schreibt. Ein regelmäßiger Check fängt das ab:

1. 1

   Jede Quelle auflisten, die gelten kann

   Team Rules, AGENTS.md- oder CLAUDE.md-Dateien im Wurzelverzeichnis und in Unterordnern sowie jede .mdc-Datei mit ihrem Auslöser: immer, Globs, nur Beschreibung oder manuell. Fragen Sie die Engineers, ob ihre User Rules Coding-Konventionen berühren.

2. 2

   Globs gegen den Verzeichnisbaum auflösen

   Markieren Sie Dateien, auf die Regeln zweier verschiedener Teams passen.

3. 3

   Die immer angewendeten Regeln prüfen

   Markieren Sie jede Zeile, die ein einzelnes Paket nennt; sie gehört in dessen Geltungsbereich.

4. 4

   Eingrenzen und erneut testen

   Hier ändern Sie den Glob auf packages/web/** und prüfen in einem Chat zu einer Admin-Datei, dass die Web-Regel nicht mehr angehängt wird.

Regeln gelten nur für den Agenten im Chat, nicht für Tab-Vervollständigung, Inline Edit oder Bugbot-Reviews. Eine Konvention, an die sich diese Funktionen halten müssen, braucht also einen anderen Mechanismus. Diese Struktur mit Ihren Teams aufzubauen, gehört zu unserer Cursor-Beratung.