Przejdź do głównej zawartości
AI Developer Toolkit

Własne reguły i szablony w Cursorze

Biblioteka reguł Cursora to zestaw plików .mdc w .cursor/rules/, które przekazują Agentowi konwencje zespołu i szablony zadań krok po kroku, a frontmatter każdego pliku ma decydować, kiedy się ładuje. Taka biblioteka opłaca się tylko wtedy, gdy jest mała, ma wąski zakres i jest sprawdzana w CI, bo reguła, która się nie ładuje albo przeczy kodowi, zawodzi po cichu.

Ta strona jest dla programisty lub tech leada, którego repozytorium ma już kilka reguł projektu i który chce, żeby działały dla całego zespołu. Po pół roku obraz jest znajomy: 20 plików reguł, dwa bez frontmattera, więc nikt nie wie, kiedy się ładują, reguła „API conventions” wskazująca plik usunięty w marcu i wyniki Agenta zależne od tego, kto pisał prompt. Jeśli dopiero piszesz pierwszą regułę, zacznij od reguł projektu w Cursorze i wróć tutaj.

Co daje przetestowana biblioteka reguł

Dział zatytułowany „Co daje przetestowana biblioteka reguł”
  • Tabelę decyzyjną: co trafia do reguły ładowanej zawsze, co do reguły dla wybranych plików, co do szablonu, skilla, a co do lintera.
  • Pięć szablonów reguł do skopiowania i dopasowania: rdzeń, reguła dla plików, szablon zadania, procedura ręczna i lista kontrolna samoprzeglądu.
  • Trzy prompty do wklejenia: wydobycie reguł z historii code review, zamiana wzorcowych plików w szablon i audyt biblioteki.
  • Skrypt CI, który zatrzymuje build, gdy reguła nie ma frontmattera, glob niczego nie dopasowuje albo odwołanie @ prowadzi donikąd.
  • Procedurę sond, która pokazuje, że reguły zmieniają wynik Agenta, sprawdzaną poleceniami, a nie czytaniem diffów.

Nazwy w interfejsie Cursora i opcje reguł często się zmieniają; zanim przeszkolisz zespół, porównaj je z cursor.com/docs/rules.

Który frontmatter decyduje, kiedy reguła się ładuje?

Dział zatytułowany „Który frontmatter decyduje, kiedy reguła się ładuje?”

Frontmatter reguły ma trzy klucze: alwaysApply, description i globs. Szablon pluginów samego Cursora, skill create-plugin w cursor/plugins, zapisuje reguły jako pliki .mdc z description, alwaysApply i opcjonalnym globs (sprawdzone 2026-10-02). Tabela przypisuje czterem kombinacjom zachowanie przy ładowaniu, jakie opisywał dla nich Cursor. Ani tego zachowania, ani nazw z wybieraka reguł nie udało się ponownie sprawdzić w cursor.com/docs/rules na potrzeby tej strony (2026-10-02), więc traktuj pierwszą i ostatnią kolumnę jako oczekiwanie, a nie gwarancję, i potwierdź każdy tryb w swojej wersji sondami opisanymi niżej.

Oczekiwane zachowanie przy ładowaniualwaysApplydescriptionglobsNazwa w wybieraku (zgłaszana, niepotwierdzona)
W każdej sesji AgentatrueopcjonalneniepotrzebneAlways Apply
Gdy w kontekście jest plik pasujący do wzorcafalseopcjonalneustawioneApply to Specific Files
Gdy Agent przeczyta opis i uzna go za trafnyfalseustawione—Apply Intelligently
Tylko gdy ktoś wywoła regułę przez @nazwa-reguły w czaciefalse——Apply Manually

Cztery zasady kształtują każdą decyzję poniżej:

  • Używaj .mdc z frontmatterem. W tym formacie zapisuje reguły szablon pluginów samego Cursora, z description, globs i alwaysApply we frontmatterze. Reguła bez frontmattera nie daje Cursorowi niczego, po czym mógłby ograniczyć jej zakres.
  • Kilka globów zapisuj w jednej linii globs, rozdzielając je przecinkami: src/**/*.tsx, src/**/*.css. Skrypt CI poniżej przyjmuje taką listę po przecinkach, listę YAML pod pustym globs: i wzorce z nawiasami klamrowymi, takie jak src/**/*.{ts,tsx}.
  • Reguły są pisane dla Agenta. Dokumentacja Cursora nazywa je „system-level instructions to Agent”. Nie udało się potwierdzić, czy trafiają też do uzupełniania Tab (linia Cursor 3.x, sprawdzone 2026-09-26), więc nie licz na to. Przegląd pull requestów należy do Bugbota, który ma własne wytyczne (zobacz Bugbot).
  • Kilka źródeł może działać jednocześnie. Team Rules, reguły projektu i User Rules mogą trafić do tej samej sesji. Zanim oprzesz się na jakiejś kolejności, sprawdź, która reguła wygrywa w twojej wersji Cursora (linia 3.x, sprawdzone 2026-09-26), sondą, w której dwie reguły dają sprzeczne polecenia.

Co powinno trafić do reguły, a co nie?

Dział zatytułowany „Co powinno trafić do reguły, a co nie?”

Większość słabych bibliotek bierze się z umieszczenia dobrej instrukcji w złym miejscu. Zapytaj, co najlepiej wymusi daną instrukcję, i wybierz najtańszy mechanizm, który to zrobi.

Instrukcja jest…Umieść ją wDlaczego
Potrzebna prawie w każdym zadaniu: stos technologiczny, polecenia, graniceRegule ładowanej zawsze (alwaysApply: true), do ok. 40 liniiKażda sesja płaci za nią kontekstem
Prawdziwa tylko w jednym obszarze: trasy API, migracje, komponenty UIRegule dla wybranych plików (globs)Ma się ładować tylko tam, gdzie ma znaczenie
Procedurą wieloetapową: „dodaj endpoint”, „dodaj feature flag”Regule dopasowywanej po opisie, wskazującej wzorcowe plikiDecyduje opis, treść zostaje krótka
Rzadka, ale ryzykowna: backfill danych, wydanieRegule ręcznej (bez description i bez globs)Ma się ładować tylko na żądanie
Długim, powtarzalnym procesem ze skryptamiSkilluReguły pasują do krótkich wytycznych; skille niosą procedury wieloetapowe i ich skrypty
Sprawdzalna mechanicznie: kolejność importów, any, nazewnictwoLinterze lub regule typówSprawdzenie działa przy każdym commicie, a nie tylko wtedy, gdy Agent pamięta
Czymś, co Agent i tak robi domyślnieNigdzieKosztuje kontekst i niczego nie uczy

Najważniejsze są dwa ostatnie wiersze. Styl zostaw linterowi, a regułę dodawaj dopiero wtedy, gdy Agent powtarza ten sam błąd. Przycinanie plików kontekstu wyjaśnia, dlaczego dowody przemawiają dziś za mniejszą liczbą ostrzejszych instrukcji.

Krótkie procedury, które głównie wskazują wzorcowe pliki, mogą zostać regułami dopasowywanymi po opisie. Gdy procedura potrzebuje skryptów albo przekracza ok. 40 linii, zamień ją w skill. Niektóre wersje Cursora mają do tego polecenie /migrate-to-skills; wpisz / w czacie Agenta, żeby sprawdzić, czy twoja je ma.

Zbuduj bibliotekę z pięciu szablonów

Dział zatytułowany „Zbuduj bibliotekę z pięciu szablonów”

Zacznij od dowodów, nie od przewodnika stylu. Wypisz poprawki, które recenzenci powtarzają; pierwszy prompt pod szablonami robi to na podstawie komentarzy z przeglądów scalonych pull requestów, więc każda reguła odpowiada na prawdziwy błąd. Potem napisz szablony w tej kolejności.

  1. Napisz jedną krótką regułę rdzenia. Zapisz ją jako .cursor/rules/core.mdc. Zawiera tylko to, czego potrzebuje każde zadanie: polecenia, które dowodzą, że praca jest skończona, i granice, których Agent nie może przekroczyć.

    ---
    description: Commands, done criteria and hard boundaries for every task
    alwaysApply: true
    ---
    

    Stack: TypeScript (strict), Next.js App Router, Drizzle on PostgreSQL, Vitest.
    

    Done means all of these pass:
    - pnpm lint
    - pnpm typecheck
    - pnpm test
    

    Boundaries:
    - Never edit files under src/db/migrations/ that are already merged; add a new migration.
    - Never add a dependency without saying why in the summary.
    - Log with the logger in @src/lib/logger.ts, never console.log.
    

    Before you report a task as done, follow @.cursor/rules/self-review.mdc.

  2. Ogranicz konwencje obszaru do jego plików. Jedna reguła na obszar, nazwana od obszaru (tu .cursor/rules/api-routes.mdc), wskazująca wzorcowy plik zamiast go kopiować.

    ---
    globs: src/app/api/**/*.ts
    alwaysApply: false
    ---
    

    API route conventions:
    - Validate the request body with a Zod schema from @src/lib/validators/index.ts before any other work.
    - Throw AppError from @src/lib/errors.ts; the route wrapper turns it into the JSON error shape.
    - Every query filters by organizationId. A route without it is a security bug.
    

    Canonical route: @src/app/api/users/route.ts

  3. Zamień powtarzalne procedury w szablony zadań. Ten zapisz jako .cursor/rules/new-endpoint.mdc. Agent ma dopasowywać zadanie do opisu, więc napisz go tak, jak ktoś poprosiłby o to zadanie.

    ---
    description: Adding a new API endpoint or resource end to end (schema, route, service, tests)
    alwaysApply: false
    ---
    

    When adding an endpoint:
    1. Schema: add the Drizzle table or column and a new migration in src/db/migrations/.
    2. Validation: add the Zod schema next to the others in src/lib/validators/.
    3. Service: business logic in src/lib/services/, no HTTP types in it.
    4. Route: follow @src/app/api/users/route.ts exactly; copy its structure, not its logic.
    5. Tests: one success path and one AppError path per handler, next to the route.
    Finish by running the commands under "Done means" in the core rule and reporting their output.

  4. Ryzykowne procedury zostaw jako ręczne. Listę kontrolną backfillu zapisz jako .cursor/rules/data-backfill.mdc, żeby ładowała się, w zamierzeniu, tylko po wpisaniu @data-backfill.

    ---
    alwaysApply: false
    ---
    

    Data backfill procedure:
    - Write the backfill as a script in scripts/backfills/ with a --dry-run flag that prints row counts.
    - Batch writes in chunks of 1,000 and make the script safe to re-run.
    - Never change a column type in place: add a new column, backfill, switch reads, then drop.
    - Stop after the dry run and show its output; a human runs the real backfill.

  5. Zamykaj każde zadanie samoprzeglądem. Listę kontrolną, którą Agent przykłada do własnego diffu, zapisz jako .cursor/rules/self-review.mdc. Opis jest po to, żeby Agent mógł wybrać ją przy oddawaniu pracy, a ostatnia linia reguły rdzenia też ją wymienia. Nie zakładaj, że ta linia z @ wczytuje plik: sonda samoprzeglądu poniżej pokazuje, czy lista kontrolna zadziałała, bo tylko ta reguła prosi o blok CHANGED FILES:. Przegląd samego pull requestu to zadanie Bugbota; zobacz Bugbot.

    ---
    description: Final self-review before reporting a task as done
    alwaysApply: false
    ---
    

    Before you say the task is done:
    - Run the commands under "Done means" in the core rule and paste the last lines of each.
    - Write a line that says exactly CHANGED FILES: and under it every file you created, changed or deleted, one repository-relative path per line with no bullets, then one blank line. Then give one line per file on why.
    - Name any test you skipped, weakened or deleted. The answer should be none.
    - Name every new dependency, environment variable or migration.

Zacommituj każdy plik w .cursor/rules/, żeby zespół przeglądał zmiany reguł jak kod.

Prompty zostają po angielsku, tak jak reguły, które generują.

Jak udowodnić, że reguły działają, bez czytania każdego diffu?

Dział zatytułowany „Jak udowodnić, że reguły działają, bez czytania każdego diffu?”

Reguła jest nieprzetestowaną instrukcją, dopóki coś jej nie sprawdzi. Użyj dwóch warstw: statycznej kontroli, że bibliotekę da się wczytać, i sond zachowania, które pokazują, że Agent się do niej stosuje.

Zatrzymaj CI, gdy biblioteka się rozjedzie

Dział zatytułowany „Zatrzymaj CI, gdy biblioteka się rozjedzie”

Zapisz ten plik jako scripts/check-cursor-rules.mjs i uruchamiaj node scripts/check-cursor-rules.mjs w tym samym jobie CI co linter. Wymaga Node 22 lub nowszego ze względu na fs.globSync.

// Fails CI when the .cursor/rules library drifts. Node 22 or later.
import { existsSync, globSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';


const MAX_LINES = 200; // keep each rule short; tune to your library
const ALWAYS_BUDGET = 120; // lines loaded into every Agent session
const errors = [];
const warnings = [];
let alwaysLines = 0;


// Accepts `globs: a, b`, `globs: ["a", "b"]`, brace globs such as
// `src/**/*.{ts,tsx}`, an empty `globs:`, and a YAML list under `globs:`.
function readGlobs(fm) {
  const line = fm.match(/^globs:[ \t]*(.*)$/m);
  if (!line) return [];
  const value = line[1].trim();
  let items;
  if (value) {
    items = value.replace(/^\[|\]$/g, '').split(/,(?![^{]*\})/);
  } else {
    items = [];
    for (const next of fm.slice(line.index + line[0].length).split(/\r?\n/).slice(1)) {
      const item = next.match(/^\s*-\s*(.+)$/);
      if (!item) break;
      items.push(item[1]);
    }
  }
  return items.map((g) => g.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
}


for (const file of globSync('.cursor/rules/**/*.{md,mdc}')) {
  const text = readFileSync(file, 'utf8');
  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
  if (fm === undefined) {
    if (file.endsWith('.md')) {
      warnings.push(`${file}: no frontmatter, so it cannot be scoped; prefer .mdc with description, globs or alwaysApply`);
    } else {
      errors.push(`${file}: no frontmatter`);
    }
    continue;
  }
  const lines = text.split('\n').length;
  if (lines > MAX_LINES) errors.push(`${file}: ${lines} lines (max ${MAX_LINES})`);
  if (/^alwaysApply:\s*true\b/m.test(fm)) alwaysLines += lines;
  for (const g of readGlobs(fm)) {
    if (globSync(g, { exclude: (p) => p.includes('node_modules') }).length === 0) {
      errors.push(`${file}: glob "${g}" matches no file`);
    }
  }
  for (const [, ref] of text.matchAll(/(?:^|\s)@([\w./-]+\.\w+)/gm)) {
    if (!existsSync(ref) && !existsSync(join(dirname(file), ref))) {
      errors.push(`${file}: @${ref} does not exist`);
    }
  }
}
if (alwaysLines > ALWAYS_BUDGET) {
  errors.push(`always-apply rules total ${alwaysLines} lines (budget ${ALWAYS_BUDGET})`);
}
for (const w of warnings) console.warn(`warning: ${w}`);
console.log(errors.length ? errors.join('\n') : 'cursor rules: OK');
process.exit(errors.length ? 1 : 0);

Oba limity to punkty wyjścia: 200 linii na regułę i budżet 120 linii dla reguł ładowanych zawsze dostrój do własnego zużycia tokenów. Dodaj .cursor/rules/ do CODEOWNERS, żeby każdą zmianę reguł zatwierdzał jeden wskazany właściciel.

Sprawdzaj zachowanie poleceniami, a nie czytaniem

Dział zatytułowany „Sprawdzaj zachowanie poleceniami, a nie czytaniem”

Trzymaj w repozytorium krótki plik docs/rule-probes.md. Każdy wiersz to zadanie, które dajesz Agentowi w nowym czacie, i polecenie, którego wynik rozstrzyga, czy reguły zadziałały.

Zadanie sondyReguła, którą sprawdzaSprawdzenie deterministyczne
„Add GET /api/invoices/[id]”Trasy API i szablon endpointupnpm test src/app/api/invoices przechodzi, a rg -c organizationId src/app/api/invoices zwraca co najmniej 1
„Log the retry count in the payment service”Reguła rdzeniarg -n "console\.log" src/lib/services/payment* niczego nie znajduje
„@data-backfill: fill invoices.currency”Procedura ręcznarg -l -- --dry-run scripts/backfills/ zwraca nowy skrypt, a git diff --stat nie pokazuje zastosowanej migracji ani zmiany danych
Dowolne z powyższych zadańReguła samoprzeglądu się wczytałaPolecenie poniżej kończy się kodem 0

Przy wierszu samoprzeglądu zapisz końcową wiadomość Agenta jako /tmp/summary.txt. Polecenie porównuje blok CHANGED FILES: z tym, co widzi git, łącznie z nowymi i usuniętymi plikami. Brak bloku też kończy się błędem i oznacza, że reguła się nie wczytała.

Okno terminala
diff <(sed -n '/^CHANGED FILES:$/,/^$/p' /tmp/summary.txt | sed '1d;/^$/d' | sort -u) \
     <(git ls-files --modified --deleted --others --exclude-standard | sort -u) \
  && echo "self-review: file list matches"

Sprawdzenia są poleceniami, ale ktoś nadal musi uruchomić każde zadanie. Żeby sondy działały bez człowieka, oskryptuj je przez Cursor SDK: pakiet @cursor/sdk wywołuje agenta Cursora z twojego kodu (Node 22.13 lub nowszy), więc zaplanowany job może dać Agentowi każde zadanie sondy w nowym uruchomieniu na czystym checkoucie, a potem wykonać kolumnę sprawdzeń. SDK pozwala wybrać, które warstwy ustawień obowiązują (projekt, użytkownik, zespół, pluginy), więc upewnij się, że uruchomienie wczytuje warstwę projektu z .cursor/rules/. Uruchamiaj job sond w jednorazowym sandboksie albo w agencie w chmurze, bez produkcyjnych sekretów w środowisku i z tokenem repozytorium tylko do odczytu.

Uruchamiaj sondy po każdej zmianie reguł i zanim przeniesiesz regułę do Team Rules. Nieudana sonda oznacza, że reguła jest niejasna, nigdy się nie wczytała albo przeczy jej inna reguła; następna sekcja pomaga ustalić, która z tych przyczyn zachodzi. Ten sam pomysł dla Claude Code, Codeksa i Cursora opisuje strona o dowodzeniu, że każdy agent wczytał wspólne reguły.

Jak udostępnić reguły innym repozytoriom i zespołowi?

Dział zatytułowany „Jak udostępnić reguły innym repozytoriom i zespołowi?”

Wybieraj według tego, kto musi przestrzegać reguły i czy może z niej zrezygnować.

  • Jedno repozytorium: reguły projektu w .cursor/rules/, zacommitowane i przypisane właścicielowi przez CODEOWNERS.
  • Każde repozytorium, decyzją administratorów: Team Rules, zarządzane z panelu Cursora. Obowiązują we wszystkich repozytoriach zespołu i mogą wygrać z regułą projektu, więc sprawdź kolejność w swojej wersji i przenoś regułę do Team Rules dopiero wtedy, gdy przejdzie sondy w jednym repozytorium.
  • Pakiet wielokrotnego użytku: żeby używać tego samego zestawu reguł w wielu repozytoriach, spakuj je w plugin z katalogiem rules/ pełnym plików .mdc. Dokumentacja Cursora opisuje pluginy jako pakujące „rules, skills, agents, commands, MCP servers, and hooks into distributable bundles”. Własne repozytorium Cursora, cursor/plugins, dostarcza reguły właśnie tak (każda reguła ma description i alwaysApply), a jego szablon create-plugin wymienia globs jako pole opcjonalne.
  • Kilku agentów w jednym repozytorium: trzymaj jedno źródło i generuj z niego pliki Cursora; zobacz jedno źródło reguł dla każdego agenta.

Wdrożenie w zespole, własność reguł i zasady przeglądu opisuje strona o współpracy zespołowej w Cursorze.

Co psuje się w bibliotece reguł Cursora?

Dział zatytułowany „Co psuje się w bibliotece reguł Cursora?”

Reguła nigdy się nie ładuje albo ładuje się wszędzie. Frontmatter jest zepsuty albo go brakuje: nie ma ograniczników ---, pole ma literówkę albo zwykły plik .md w ogóle nie ma frontmattera. Naprawa: zapisz regułę jako .mdc z description, globs lub alwaysApply i uruchom skrypt CI; zgłasza reguły bez frontmattera.

Reguła dopasowywana po opisie jest pomijana w zadaniu, dla którego powstała. Jej opis nazywa temat („API stuff”), a nie zadanie. Naprawa: przepisz opis tak, jak programista sformułowałby prośbę, i powtórz sondę. Jeśli nadal nie działa, ogranicz regułę przez globs.

Reguła z globem nigdy się nie uruchamia. Wzorzec wskazuje ścieżkę, którą przeniesiono, albo jest szerszy lub węższy, niż myślisz. Naprawa: wybieraj jawne wzorce, takie jak src/**/*.ts, i pozwól skryptowi CI potwierdzić, że każdy glob dopasowuje pliki.

Agent stosuje regułę sprzeczną z kodem. Reguła opisuje zeszłoroczny wzorzec, a wzorcowy plik się zmienił. Naprawa: zastąp wklejony kod odwołaniami @, żeby reguła podążała za plikiem, i usuń reguły, które prompt audytowy oznaczy jako sprzeczne.

Kontekst zapełnia się, zanim zadanie się zacznie. Reguły ładowane zawsze rosły linia po linii. Naprawa: przenieś linie dotyczące jednego obszaru do reguł z globem, procedury do skilli i pilnuj budżetu reguł ładowanych zawsze w CI.

Team Rule może nadpisać regułę projektu. Jeśli w twojej wersji wygrywają Team Rules, ogólna reguła organizacji może pokonać precyzyjną regułę repozytorium. Naprawa: uruchom sondę ze sprzecznymi poleceniami, żeby sprawdzić, która wygrywa, w Team Rules trzymaj politykę (bezpieczeństwo, obsługa danych), a konwencje kodu zostaw regułom projektu.

Zespół oczekuje reguł w Tab albo w przeglądzie pull requestów. Reguły są pisane dla Agenta; Bugbot ma własne wytyczne, a działania reguł w Tab nie udało się potwierdzić (linia Cursor 3.x, sprawdzone 2026-09-26). Naprawa: daj Bugbotowi własne wytyczne do przeglądu (zobacz Bugbot), a styl wymuszaj linterem.

Dokąd dalej po regułach Cursora

Dział zatytułowany „Dokąd dalej po regułach Cursora”

Autor:

Zobacz co nowego na platformie.

Polityka prywatności Regulamin Ustawienia cookie