Reguły Cursora w monorepo: zakres dla każdego pakietu bez powtarzania wszystkiego

Jak Cursor decyduje, które reguły obowiązują

Cursor ma cztery rodzaje reguł: Team Rules zarządzane w panelu w planach Team i Enterprise, reguły projektu jako pliki .mdc w .cursor/rules, User Rules oraz AGENTS.md. O tym, kiedy reguła projektu się wczytuje, decyduje jej frontmatter. Z alwaysApply ustawionym na true jest w każdym czacie. Z globami dołącza się, gdy pasujący plik jest w kontekście. Z samym opisem decyduje agent. Bez żadnego z nich działa tylko wtedy, gdy ktoś o niej wspomni. Zwykły plik .md w .cursor/rules jest ignorowany.

W monorepo liczą się trzy szczegóły. Wszystkie pasujące reguły są łączone, a przy sprzecznych wskazówkach Team Rules mają pierwszeństwo przed regułami projektu, a te przed User Rules. Reguły są identyfikowane po pełnej ścieżce, więc dwa pliki o tej samej nazwie w różnych folderach obowiązują oba. A CLAUDE.md Cursor traktuje jak AGENTS.md, ale stosuje go zawsze, więc duży CLAUDE.md w katalogu głównym, pisany dla Claude Code, kosztuje kontekst także w każdym czacie Cursora.

Układ zawężający zakres do pakietów

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

Oba sposoby zawężania służą różnym celom. Reguły z globami trzymają konwencje w jednym miejscu w katalogu głównym i mogą celować w rozproszone ścieżki, na przykład w każdy folder migracji. Zagnieżdżony AGENTS.md leży przy pakiecie, który opisuje, a Cursor łączy go z plikami wyżej, dając pierwszeństwo bardziej szczegółowemu. Ten sam plik czytają też inni agenci, co pomaga w monorepo, gdzie część zespołów używa Claude Code albo Codex.

Jak zdecydować, gdzie należy reguła

• Prawdziwe w każdym pakiecie i krótkie: zawsze stosowana reguła w katalogu głównym albo tamtejszy AGENTS.md. Za każdą linię płacisz w każdym czacie.
• Prawdziwe w jednym pakiecie: reguła z globem dla jego ścieżek albo jego własny AGENTS.md.
• Procedura potrzebna od czasu do czasu, na przykład pisanie migracji: reguła z samym opisem, którą agent dociąga w razie potrzeby, albo reguła ręczna.
• Standard dla wszystkich repozytoriów: Team Rule, wymuszona tam, gdzie nie wolno jej wyłączyć. Sam Cursor ostrzega, że wskazówki dla AI nie powinny być twoim jedynym zabezpieczeniem.
• Wszystko, co może sprawdzić linter albo CI: narzędzie, a nie reguła. Dokumentacja Cursora odradza kopiowanie przewodników stylu do reguł.

Jedna pułapka: reguła, która wspomina plik przez @, mówi agentowi, gdzie szukać, ale treść pliku nie jest wklejana. To, co musi być zawsze w kontekście, trzeba zapisać w treści reguły.

Własność, która podąża za pakietem

Reguły psują się, gdy nikt za nie nie odpowiada. Przypisz zespołowi pakietu jego pliki reguł przez CODEOWNERS, a zespołowi platformowemu reguły stosowane zawsze, bo one kosztują kontekst wszystkich. Poradnik Claude Code o dużych bazach kodu opisuje ten sam podział dla plików instrukcji w katalogach: plik katalogu utrzymuje jego właściciel.

/.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 stosuje ostatni pasujący wzorzec w CODEOWNERS, dlatego linie pakietów są po ogólnym katalogu reguł. Cursor zaleca, by każda reguła miała mniej niż 500 linii, a duże dzielić, i własność według pakietów sprawia, że ten podział jest naturalny.

Znajdź nakładanie się reguł, zanim zrobi to agent

Ponieważ łączone są wszystkie pasujące reguły, konflikt może wynikać z dowolnego zestawu źródeł: Team Rules, własnych User Rules inżyniera, zawsze stosowanej reguły w katalogu głównym, plików AGENTS.md w katalogu głównym i w podkatalogach, reguł z globami, reguł wybieranych przez agenta na podstawie opisu i reguł wspominanych ręcznie. Typowy przypadek w monorepo to dwa globy pasujące do tego samego pliku. W hipotetycznym repozytorium web/components.mdc używa **/*.tsx, więc dołącza się też do packages/admin, którego zespół pisze komponenty inaczej. Okresowe sprawdzenie to wyłapuje:

1. 1

   Wypisz każde źródło, które może obowiązywać

   Team Rules, pliki AGENTS.md lub CLAUDE.md w katalogu głównym i w podkatalogach oraz każdy plik .mdc z jego wyzwalaczem: zawsze, globy, sam opis albo ręcznie. Zapytaj inżynierów, czy ich User Rules dotyczą konwencji kodowania.

2. 2

   Rozwiń globy na drzewie plików

   Oznacz pliki, do których pasują reguły należące do dwóch różnych zespołów.

3. 3

   Sprawdź reguły stosowane zawsze

   Oznacz każdą linię, która wymienia pojedynczy pakiet; należy ona do zakresu tego pakietu.

4. 4

   Zawęź i przetestuj ponownie

   Tutaj zmień glob na packages/web/** i w czacie o pliku z admina sprawdź, że reguła web już się nie dołącza.

Reguły dotyczą tylko agenta w czacie, a nie podpowiedzi Tab, Inline Edit ani review Bugbota, więc konwencja, której mają przestrzegać te funkcje, wymaga innego mechanizmu. Zbudowanie takiej struktury z waszymi zespołami to część naszego doradztwa w zakresie Cursora.