Reguły projektu w Cursorze

Reguły projektu w Cursorze to pliki .mdc w katalogu .cursor/rules/ repozytorium, które przekazują Agentowi Cursora stałe instrukcje. Frontmatter ustala, kiedy reguła się ładuje: zawsze, dla pasujących plików, według oceny Agenta albo po wywołaniu przez @. Reguły kierują Agentem, a o wdrożeniu nadal decydują testy i CI.

Ta strona jest dla programisty, który konfiguruje Cursora w prawdziwym repozytorium. Sytuacja jest znajoma: trzeci raz w tym tygodniu piszesz „najpierw zwaliduj body Zodem” i „uruchom testy, zanim powiesz, że gotowe”, a Agent i tak tworzy endpoint bez filtra po organizacji. Reguły projektu zapisują te poprawki w repozytorium raz, więc każda sesja Agenta zaczyna od nich, a każdy członek zespołu dostaje te same.

Co dają ci pierwsze reguły projektu

• Trzy działające pliki reguł: krótką regułę bazową ładowaną zawsze, regułę dla jednego obszaru kodu i ręczną procedurę ładowaną na żądanie.
• Tabelę decyzyjną, która mówi, jakiego trybu ładowania potrzebuje każda instrukcja, żeby kontekst nie wypełniał się regułami, które nie mają zastosowania.
• Test kanarkowy, który w niecałą minutę i bez zgadywania pokazuje, które reguły Agent naprawdę wczytał.
• Zadanie próbne z poleceniem, które rozstrzyga, czy reguła zmieniła wynik Agenta, więc weryfikujesz zachowanie zamiast czytać diff.
• Prompty do wklejenia, które szkicują regułę bazową na podstawie twojego repozytorium i testują każdą regułę, którą napiszesz.

Kiedy Cursor ładuje regułę projektu?

Decydują o tym trzy pola frontmattera: alwaysApply, description i globs. Lista typów w edytorze reguł Cursora ustawia je za ciebie; w zwykłym edytorze tekstu wpisujesz je sam.

Typ na liście	alwaysApply	description	globs	Kiedy reguła się ładuje	Do czego jej używać
Always Apply	true	ignorowane	ignorowane	W każdej sesji Agenta	Polecenia potwierdzające, że praca jest skończona, twarde granice
Apply to Specific Files	false	—	ustawione	W kontekście jest plik pasujący do wzorca	Konwencje jednego obszaru: endpointy API, migracje, UI
Apply Intelligently	false	ustawione	—	Agent czyta opis i sam decyduje	Procedura związana z rodzajem zadania
Apply Manually	false	—	—	Wywołujesz regułę w czacie przez @nazwa-reguły	Rzadkie, ryzykowne procedury: backfille, wydania

Na tych pięciu szczegółach potyka się większość pierwszych zestawów reguł:

• Liczą się tylko pliki .mdc. Dokumentacja reguł Cursora mówi: „Project rules live in .cursor/rules as .mdc files” i „A plain .md file in .cursor/rules is ignored by the rules system” (sprawdzono 2026-10-12).
• Kilka globów oddzielasz przecinkami, na przykład src/**/*.ts, src/**/*.tsx. Sam *.ts dopasowuje tylko pliki w katalogu głównym repozytorium.
• Reguły trafiają tylko do Agenta. Pomoc Cursora mówi: „Rules only apply to Agent (Chat). They do not apply to Tab completion, Inline Edit, or Bugbot PR reviews” (sprawdzono 2026-10-12). Bugbot bierze własne wskazówki z .cursor/BUGBOT.md, pliku opisanego ze źródła wtórnego i niesprawdzanego ponownie 2026-10-12; zob. Bugbot.
• Podkatalogi działają. .cursor/rules/frontend/components.mdc też jest regułą projektu, co pomaga, gdy reguł jest więcej niż kilka.
• Pliki z instrukcjami też się liczą. Dokumentacja reguł Cursora mówi: „Cursor supports AGENTS.md in the project root and subdirectories”, a zagnieżdżone pliki „are combined with parent directories, with more specific instructions taking precedence”. Cursor „reads CLAUDE.md files the same way it reads AGENTS.md”, a „CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply frontmatter setting” (sprawdzono 2026-10-12).

Napisz pierwsze trzy reguły projektu

Zacznij od poprawek, które powtarzasz, a nie od przewodnika stylu. Agent zna typowe konwencje; reguła zasługuje na miejsce tylko wtedy, gdy zmienia to, co Agent zrobiłby bez niej.

1. Utwórz katalog i przenieś stary plik reguł. W terminalu, w katalogu głównym repozytorium:

   mkdir -p .cursor/rules
   ls .cursorrules 2>/dev/null && echo "move its content into .cursor/rules/core.mdc"

   Jeśli repozytorium nadal ma jednoplikowy .cursorrules, przenieś jego treść do reguły bazowej poniżej i usuń plik, żeby wszystkie reguły leżały w jednym miejscu, które zespół przegląda. Pomoc Cursora nazywa plik .cursorrules w katalogu głównym projektu „legacy and will be deprecated” i zaleca przeniesienie go do reguły projektu ustawionej na Always Apply (sprawdzono 2026-10-12).

2. Napisz krótką regułę bazową. Zapisz ją jako .cursor/rules/core.mdc. Zawiera tylko to, czego potrzebuje każde zadanie: stos w jednej linii, polecenia definiujące „gotowe” i granice, których Agent nie może przekroczyć. Trzymaj ją poniżej około 40 linii, bo płaci za nią każda sesja.

   ---
   description: Stack, done criteria, and hard boundaries for every task
   alwaysApply: true
   ---
   
   Stack: TypeScript (strict), Next.js App Router, Drizzle on PostgreSQL, Vitest, pnpm.
   
   Done means all of these pass, and you paste the last lines of each:
   - pnpm lint
   - pnpm typecheck
   - pnpm test
   
   Boundaries:
   - Never add a dependency without naming it and the reason in your summary.
   - Never edit a merged migration in src/db/migrations/; add a new one.
   - Never weaken, skip, or delete an existing test to make a check pass.
   - Log with the logger in @src/lib/logger.ts, never console.log.

   Dzięki odwołaniu @src/lib/logger.ts Agent sięga do prawdziwego pliku i nie musisz kopiować kodu do reguły, więc reguła nie starzeje się razem z plikiem. Odwołanie @ wczytuje wskazany plik za każdym razem, gdy ładuje się reguła, więc w regule Always Apply odwołuj się tylko do małych plików.

3. Ogranicz regułę obszaru do jej plików. Zapisz ją jako .cursor/rules/api-routes.mdc. Ładuje się tylko wtedy, gdy w kontekście jest pasujący plik, więc nic nie kosztuje, kiedy Agent pracuje nad UI.

   ---
   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.
   - Every database query filters by organizationId. A route without it is a security bug.
   - Throw AppError from @src/lib/errors.ts; never return raw database errors or stack traces.
   
   Canonical route: @src/app/api/users/route.ts

4. Ryzykowną procedurę zostaw jako ręczną. Zapisz ją jako .cursor/rules/data-backfill.mdc. Bez description i bez globs ładuje się tylko wtedy, gdy ktoś wpisze @data-backfill w czacie.

   ---
   alwaysApply: false
   ---
   
   Data backfill procedure:
   - Write the backfill as a plain Node script (.mjs) 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.
   - Stop after the dry run and show its output. A human runs the real backfill.

5. Zacommituj reguły. Reguły w .cursor/rules/ są pod kontrolą wersji, więc przeglądaj zmianę reguły jak zmianę kodu. Gdy zespół rośnie, dodaj .cursor/rules/ do CODEOWNERS, żeby jedna wskazana osoba zatwierdzała edycje reguł.

Dopasuj ścieżki i polecenia do swojego stosu; liczy się struktura. Możesz też wpisać /create-rule w Agencie i opisać regułę; Agent zapisze plik z frontmatterem w .cursor/rules/. Przejrzyj wynik przed commitem, bo wygenerowana reguła często powtarza konwencje, których Agent i tak przestrzega.

Prompt do wklejenia: szkic reguły bazowej z tego repozytorium

Read package.json, the lint and TypeScript config, the CI workflow files, and the README. Draft .cursor/rules/core.mdc with frontmatter `description: Stack, done criteria, and hard boundaries for every task` and `alwaysApply: true`. The body has three parts, at most 40 lines in total: the stack in one line; the exact commands CI runs that prove a change is done (copy them from the CI workflow, do not invent any); and hard boundaries only where the repository shows a real risk (merged migrations, generated files, secrets files, test files). Leave out anything a linter or the type checker already enforces, and list those separately. Show me the file; do not write it yet.

Jak udowodnić, że reguła projektu się wczytała i zmieniła wynik?

Reguła pozostaje nieprzetestowaną instrukcją, dopóki coś jej nie sprawdzi. Na pierwszy zestaw reguł wystarczą dwie szybkie kontrole: kanarek, który pokazuje, które reguły się wczytały, i zadanie próbne, którego wynik rozstrzyga polecenie.

Sprawdź wczytanie kanarkiem

Cursor umieszcza treść zastosowanych reguł w kontekście modelu, więc Agent może cytować regułę, którą ma. Pytanie „jakie reguły widzisz?” zachęca do wiarygodnie brzmiącego zgadywania; prośba o losowy token, którego nie da się zgadnąć, już nie.

1. Dopisz na końcu każdej reguły tymczasową linię z unikalnym tokenem, na przykład Canary: core-7f3a w core.mdc, Canary: api-19c2 w api-routes.mdc i Canary: backfill-d04e w data-backfill.mdc.
2. Zamknij karty edytora z plikami w src/app/api/, otwórz nowy czat Agenta bez dołączonych plików i wklej prompt poniżej. Powinien wrócić tylko core-7f3a.
3. W kolejnym nowym czacie dołącz src/app/api/users/route.ts i zapytaj ponownie. Teraz powinien pojawić się też api-19c2.
4. W trzecim czacie wpisz @data-backfill i zapytaj ponownie. Powinien pojawić się backfill-d04e.
5. Regule Apply Intelligently też daj kanarek, otwórz nowy czat, wpisz prośbę zgodną z jej opisem (na przykład „Add a new API endpoint end to end”) i wklej prompt ponownie. Jej token powinien się pojawić; jeśli go nie ma, Agent pominął regułę przy tej prośbie.
6. Usuń linie kanarków i zacommituj zmianę.

Jeśli brakuje tokenu, reguła się nie wczytała; sekcja o awariach poniżej mówi dlaczego. Jako drugą opinię otwórz Customize → Rules: widok pokazuje każdą regułę, którą Cursor znalazł, i jej status.

Prompt do wklejenia: test kanarkowy reguł projektu

Without reading any files or running any tools, list every line that starts with "Canary:" in the project rules currently in your context. Quote each line exactly. If you see none, reply "no canaries". Do not guess and do not search the repository.

Sprawdź zachowanie zadaniem próbnym

Wczytanie to jeszcze nie posłuszeństwo. Daj Agentowi małe zadanie, na które reguła powinna wpłynąć, a potem pozwól rozstrzygnąć poleceniu zamiast czytać diff.

Zadanie próbne w nowym czacie	Reguła, którą sprawdza	Polecenie, które rozstrzyga
„Add GET /api/invoices/[id] that returns one invoice”	api-routes.mdc	pnpm test src/app/api/invoices przechodzi, w tym test, w którym użytkownik prosi o fakturę innej organizacji i dostaje 404; rg -c organizationId src/app/api/invoices to tylko szybkie wstępne sprawdzenie
„Log the retry count in the payment service”	core.mdc	git add -N src/lib/services && git diff -U0 -- src/lib/services | rg '^\+.*console\.log' niczego nie znajduje, więc Agent nie dodał console.log, także w nowym pliku (git add -N sprawia, że git diff widzi nieśledzone pliki)
„@data-backfill fill invoices.currency from orders”	data-backfill.mdc	node scripts/backfills/<nazwa>.mjs --dry-run kończy się kodem 0 i wypisuje liczby wierszy, a git status --porcelain --untracked-files=all pokazuje tylko ?? scripts/backfills/<nazwa>.mjs i żadnej ścieżki w src/db/migrations/

Prompt do wklejenia: zadanie próbne dla reguły obszaru

Add GET /api/invoices/[id] that returns one invoice for the signed-in user's organization. Follow the project rules for API routes. Add a test in which a user from another organization requests the invoice and gets 404. When you are done, run pnpm lint, pnpm typecheck, and pnpm test, paste the last lines of each, and list every file you changed with one line on why.

Uruchamiaj zadania próbne ponownie po każdej zmianie reguły. Nieudana próba oznacza, że reguła jest niejasna, nie wczytała się albo kłóci się z inną regułą lub z kodem.

Co nadal sprawdza kod, gdy reguły już działają?

Reguły kierują Agentem, ale niczego nie egzekwują. Wytyczne samego Cursora mówią, że wskazówki dla AI nie powinny być twoją jedyną kontrolą bezpieczeństwa. Reguła bazowa prosi Agenta o uruchomienie poleceń „gotowe”, ale to te same polecenia w CI blokują zły merge. Granica, której nie wolno przekroczyć, należy do bramki CI albo do funkcji dopasowania (fitness function), a reguła jest tylko wskazówką, która trzyma Agenta z daleka. Osoba, która merguje pull request, podpisuje się pod zielonymi bramkami, a nie pod tym, że przeczytała każdą linię.

Reguła, skill czy sprawdzenie lintera?

Większość słabych zestawów reguł bierze się z umieszczenia rozsądnej instrukcji w złym miejscu.

Instrukcja jest…	Umieść ją w	Dlaczego
Potrzebna niemal w każdym zadaniu	Regule Always Apply	Krótka, a płaci za nią każda sesja
Prawdziwa w jednym obszarze kodu	Regule Apply to Specific Files	Ładuje się tylko tam, gdzie ma znaczenie
Długą, wieloetapową procedurą ze skryptami	Skillu (Agent Skills)	Skille ładują zasoby na żądanie i działają w agentach obsługujących standard
Sprawdzalna mechanicznie: nazewnictwo, importy, any	Regule lintera albo typów	Działa przy każdym commicie, a nie tylko wtedy, gdy Agent pamięta
Czymś, co Agent już robi poprawnie	Nigdzie	Kosztuje kontekst i niczego nie zmienia

Według dokumentacji Cursora Cursor wczytuje skille projektu z .agents/skills/ i .cursor/skills/ (na poziomie użytkownika: ~/.agents/skills/ i ~/.cursor/skills/) oraz „for compatibility” z .claude/skills/ i .codex/skills/ (a także z ~/.claude/skills/ i ~/.codex/skills/). Zagnieżdżone katalogi skilli projektu obowiązują tylko w swoim poddrzewie. Wśród wbudowanych skilli są /create-rule, /create-skill i /migrate-to-skills (sprawdzono 2026-10-12). Na 2026-09-26 dokumentacja opisywała /migrate-to-skills jako zamianę kwalifikujących się reguł dynamicznych i poleceń slash w skille. Instalację i udostępnianie skilli opisuje przegląd skilli.

Kiedy reguły projektu w Cursorze nie działają

Reguła nigdy się nie wczytuje. Plik ma rozszerzenie .md zamiast .mdc albo frontmatter jest uszkodzony (brak zamykającego ---, tabulator w YAML-u). Naprawa: zmień nazwę na .mdc, popraw frontmatter i powtórz test kanarkowy.

Reguła dla plików nigdy się nie uruchamia. Glob to *.ts, który dopasowuje tylko katalog główny repozytorium, albo wskazuje katalog, który został przeniesiony. Naprawa: użyj **/*.ts albo prefiksu katalogu, na przykład src/app/api/**/*.ts. Dla zgrubnego sprawdzenia wypisz pasujące pliki poleceniem shopt -s globstar; ls src/app/api/**/*.ts w bashu. Potem potwierdź to testem kanarkowym, bo glob w bashu tylko przybliża dopasowanie Cursora.

Reguła Apply Intelligently jest pomijana w zadaniu, dla którego powstała. Jej opis nazywa temat („sprawy API”), a nie zadanie. Naprawa: przepisz opis jako prośbę, którą wpisałby programista, na przykład „Adding a new API endpoint end to end”, albo ogranicz regułę przez globs.

Agent przestrzega reguły sprzecznej z kodem. Reguła opisuje wzorzec sprzed kwartału. Naprawa: zastąp wklejony kod odwołaniami @ do wzorcowego pliku i usuń nieaktualne linie.

Kontekst zapełnia się, zanim zadanie się zacznie. Reguła ładowana zawsze rosła linia po linii. Naprawa: przenieś linie dotyczące jednego obszaru do reguł z globami, procedury do skilli, a odwołania @ wynieś z reguły ładowanej zawsze; zarządzanie kontekstem w Cursorze pokazuje, jak sprawdzić, co niesie sesja.

Zespół oczekuje reguł w Tab, Inline Edit albo w Bugbocie. Reguły działają tylko w Agencie (pomoc Cursora, sprawdzono 2026-10-12). Naprawa: wskazówki do przeglądu pull requestów umieść we własnym pliku wskazówek Bugbota (zob. Bugbot), a styl egzekwuj linterem.

Team Rule wygrywa z twoją regułą projektu. W planach Teams i Enterprise Team Rules mają pierwszeństwo przed regułami projektu, a te przed User Rules: strona pomocy Cursora o regułach mówi „When rules conflict, precedence is: Team Rules > Project Rules > User Rules” (odczyt 2026-10-13). Od Cursora 3.21 (2026-09-17, notatki o wydaniach Cursora) team rule z wzorcami plików obowiązuje tylko dla pasujących plików. Naprawa: poproś administratora, żeby Team Rules dotyczyły polityk, a konwencje kodu zostały w repozytorium.

Uwaga

Wszystko, co nie może się wydarzyć nigdy, na przykład sekret w commicie albo migracja usuwająca kolumnę, wymaga mechanicznej bramki w CI albo hooka. Reguła zmniejsza prawdopodobieństwo błędu, ale go nie wyklucza.

Źródła

Na 2026-10-12 dokumentacja i pomoc Cursora potwierdziły format .mdc z frontmatterem description, globs i alwaysApply, działanie AGENTS.md i CLAUDE.md, plik .cursorrules jako legacy, zakres tylko dla Agenta oraz katalogi skilli wymienione na tej stronie. Nazwy typów reguł na liście, sposób ładowania każdego typu i widok Customize → Rules sprawdzono ostatnio 2026-09-26 w plikach reguł z oficjalnego repozytorium Cursora cursor/plugins i w nieoficjalnej kopii cursor.com/docs/rules z 2026-09-26 (Cursor 3.x); porównaj nazwy z cursor.com/docs/rules we własnej wersji.

Co dalej z regułami projektu

• Niezbędna konfiguracja: krok wcześniejszy, jeśli Cursor nie jest jeszcze skonfigurowany.
• Od PRD do planu i zadań: następny krok, czyli zamiana wymagania w plan, który kształtują te reguły.
• Własne reguły i szablony: rozbudowa tych plików w przetestowaną bibliotekę ze sprawdzeniem w CI i Team Rules.
• Wspólne reguły agentów i jedno źródło reguł dla wszystkich agentów: gdy w tym samym repozytorium pracują też Claude Code albo Codex.
• Ta sama idea w innych narzędziach: system pamięci Claude Code (CLAUDE.md) i AGENTS.md w Codexie.
• Design: etap cyklu, na którym zapadają decyzje o konwencjach i granicach, zanim staną się regułami.