Niestandardowe reguły i szablony

Biblioteka .cursor/rules/ kodyfikuje wiedzę domenową zespołu, standardy kodowania i konwencje plików, dzięki czemu agent Cursor daje spójne wyniki u każdego dewelopera, zamiast zależeć od umiejętności promptowania. Cursor wspiera cztery tryby reguł — Zawsze stosuj, Stosuj inteligentnie, Zakres glob i Ręczny — każdy ładujący regułę w innych warunkach. Plany Team i Enterprise dodają reguły centralne, nadrzędne wobec reguł projektu i osobistych.

Twój zespół liczy pięciu deweloperów korzystających z Cursora. Jeden z nich zawsze dostaje czyste, dobrze zorganizowane wyniki. Pozostali otrzymują niespójne rezultaty — różne konwencje nazewnictwa, różne wzorce obsługi błędów, różna organizacja plików. Różnica nie polega na umiejętności promptowania. Deweloper z konsekwentnymi wynikami ma katalog .cursor/rules/ z 12 starannie opracowanymi plikami reguł, które uczą agenta, jak twój zespół pisze kod.

Reguły to najskuteczniejsza inwestycja w produktywność z Cursorem. Zachowują się pomiędzy sesjami czatu, stosują się automatycznie na podstawie wzorców plików i zapewniają, że każdy deweloper w zespole otrzymuje tę samą jakość wyników AI.

Co daje ten przewodnik po regułach

• Framework do podejmowania decyzji, co zakodować jako reguły, a co pozostawić jako doraźne prompty
• Strukturę plików reguł z frontmatterem dla wzorców glob, opisów i ustawień automatycznego stosowania
• Gotową bibliotekę reguł przetestowanych w produkcji, które możesz dostosować do swojego projektu
• Techniki organizowania, komponowania i utrzymywania reguł na dużą skalę

Typy reguł i kiedy stosować każdy z nich

Cursor wspiera cztery tryby stosowania reguł:

Typ	Frontmatter	Kiedy stosowany	Użyj do
Zawsze stosuj	alwaysApply: true	Każda sesja czatu	Podstawowe standardy kodowania, konwencje plików
Stosuj inteligentnie	alwaysApply: false + description	Agent decyduje na podstawie trafności	Wzorce domenowe, przewodniki workflow
Zakres glob	globs: "src/api/**/*.ts"	Gdy pasujące pliki są w kontekście	Konwencje specyficzne dla katalogów
Ręczny	Typ reguły ustawiony na Apply Manually (wybrany z listy rozwijanej typów)	Gdy wspomniano @rule-name	Specjalistyczne workflow, szablony

Framework decyzyjny dla reguł

Zadaj sobie pytanie: “Czy każdy pojedynczy prompt korzysta z tej informacji?”

• Tak -> Zawsze stosuj (nazewnictwo plików, styl kodu, struktura projektu)
• Tylko przy pracy w konkretnym obszarze -> Zakres glob (konwencje backendu, wzorce frontendu)
• Tylko dla pewnych typów zadań -> Stosuj inteligentnie (przewodnik migracji, kroki tworzenia API)
• Rzadko, ale krytyczne gdy potrzebne -> Ręczny (checklista audytu bezpieczeństwa, proces wydania)

Budowanie biblioteki reguł

Reguła 1: Przegląd projektu (Zawsze stosuj)

Każdy projekt powinien mieć jedną regułę zawsze stosowaną, która daje agentowi niezbędny kontekst:

Wskazówka

Reguła do skopiowania — przegląd projektu:

Utwórz .cursor/rules/project-overview.mdc:

---
alwaysApply: true
---

This is a Next.js 14 SaaS application using the App Router.

Tech stack:
- Next.js 14 with App Router and Server Components
- TypeScript with strict mode
- Tailwind CSS for styling
- Drizzle ORM with PostgreSQL
- NextAuth.js for authentication
- Stripe for payments
- Vitest for testing

Key directories:
- src/app/ -- Next.js routes and pages
- src/components/ -- Shared React components
- src/lib/ -- Utility functions and service clients
- src/db/ -- Database schema, migrations, and queries
- src/types/ -- Shared TypeScript types

Use the logger from @src/lib/logger.ts instead of console.log.
Error responses must use the format from @src/lib/errors.ts.

Reguła 2: Styl kodu TypeScript (zakres glob)

Ta reguła ma zakres ustawiony przez globs, więc ładuje się tylko wtedy, gdy agent dotyka plików .ts/.tsx — nie musisz za nią płacić przy każdym promptcie. Pamiętaj, że globs i alwaysApply: true wzajemnie się wykluczają: jeśli alwaysApply ma wartość true, reguła wstrzykuje się do każdej sesji, a zakres glob jest ignorowany. Wybierz jeden tryb na regułę.

---
globs: "*.ts,*.tsx"
---

TypeScript conventions for this project:
- Use `interface` for object shapes, `type` for unions and intersections
- Prefer `async/await` over `.then()` chains
- Use `unknown` instead of `any`
- Destructure function parameters when there are more than 2
- All exported functions must have JSDoc comments
- Prefer early returns over nested conditionals

Reguła 3: Przewodnik implementacji funkcji (decyzja agenta)

---
description: Step-by-step guide for implementing a new feature end-to-end
alwaysApply: false
---

When implementing a new feature:

1. Database: Create migration in src/db/migrations/ using Drizzle
2. Types: Add TypeScript types in src/types/
3. API: Create route handler in src/app/api/
4. Service: Add business logic in src/lib/services/
5. UI: Build components in src/components/ and page in src/app/
6. Tests: Write tests adjacent to the source files

Always check for existing patterns before creating new ones.
Reference @src/app/api/users/route.ts as the canonical API example.
Reference @src/components/UserProfile.tsx as the canonical component example.

Reguła 4: Konwencje testowe (zakres glob)

---
globs: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
---

Testing conventions:
- Use Vitest with happy-dom for DOM tests
- Test file lives adjacent to source: foo.ts -> foo.test.ts
- Use descriptive test names: "should return 401 when token is expired"
- Mock external services, never make real HTTP calls in unit tests
- Use factory functions for test data, not inline object literals
- Test error paths, not just happy paths

See @src/lib/services/__tests__/user-service.test.ts for a complete example.

Referencje do plików w regułach

Reguły mogą odwoływać się do innych plików za pomocą składni @filename. Jest to znacznie lepsze niż kopiowanie kodu do reguły, ponieważ referencja zawsze wskazuje na aktualną wersję:

---
description: Create a new API endpoint
alwaysApply: false
---

Follow the pattern in @src/app/api/users/route.ts exactly:
- Same error handling structure
- Same response format
- Same middleware chain
- Same validation approach using Zod schemas from @src/lib/validators/

Do not copy the user-specific logic. Only copy the structural patterns.

Uwaga

Utrzymuj reguły poniżej 500 linii. Jeśli reguła się rozrasta, podziel ją na kilka bardziej skoncentrowanych reguł. Reguła licząca 200 linii, która obejmuje wszystko o twoim API, jest trudniejsza do zastosowania przez agenta niż trzy reguły po 60 linii dotyczące tras, walidacji i obsługi błędów osobno.

Reguły zespołowe (plany Team i Enterprise)

Plany Team i Enterprise wspierają scentralizowane reguły zarządzane z panelu Cursor. Reguły te stosują się we wszystkich projektach dla każdego członka zespołu.

Reguły zespołowe są przydatne do:

• Standardów kodowania obowiązujących w całej organizacji
• Polityk bezpieczeństwa
• Wymagań compliance
• Wspólnych konwencji obejmujących wiele repozytoriów

Kolejność priorytetów

Gdy reguły są sprzeczne, stosowane są w następującej kolejności:

1. Reguły zespołowe (najwyższy priorytet)
2. Reguły projektowe (.cursor/rules/)
3. Reguły użytkownika (osobiste preferencje)

Oznacza to, że administrator zespołu może wymuszać standardy, których indywidualni deweloperzy nie mogą nadpisać.

Wskazówka

Prompt do skopiowania — generowanie reguł z istniejącego kodu:

Analyze the patterns in @src/app/api/ and generate a Cursor rule file (.mdc format) that documents:
1. The route handler structure (how handlers are organized)
2. The error handling pattern (how errors are caught and formatted)
3. The validation approach (how request bodies are validated)
4. The response format (how successful responses are structured)

Output the rule as a markdown file with appropriate frontmatter (description, globs for src/app/api/**/*.ts). Keep it under 100 lines.

Importowanie i udostępnianie reguł

Zdalne reguły z GitHub

Importuj reguły bezpośrednio z repozytoriów GitHub:

1. Otwórz Cursor Settings > Rules, Commands
2. Kliknij + Add Rule obok Project Rules
3. Wybierz Remote Rule (GitHub)
4. Wklej URL repozytorium

Zaimportowane reguły są synchronizowane z repozytorium źródłowym. Aktualizacje zdalnej reguły są automatycznie odzwierciedlane w twoim projekcie.

Integracja z Agent Skills

Cursor może ładować reguły z Agent Skills, otwartego standardu rozszerzania agentów AI. Włącz je w Cursor Settings > Rules > Import Settings > Agent Skills. Są traktowane jako reguły decydowane przez agenta — Cursor określa, kiedy są istotne na podstawie kontekstu.

Kiedy niestandardowe reguły zawodzą

Reguły nie są stosowane. Sprawdź, czy plik reguły znajduje się w .cursor/rules/ z poprawnym rozszerzeniem (.md lub .mdc). Dla plików .mdc zweryfikuj składnię frontmatteru. Podgląd stosowanych reguł uzyskasz, najeżdżając kursorem na wskaźnik kontekstu w polu promptu.

Reguły są ze sobą sprzeczne. Podziel sprzeczne reguły na bardziej szczegółowe wzorce glob. Reguła dla src/api/**/*.ts i reguła dla src/frontend/**/*.tsx nigdy nie będą kolidować, ponieważ celują w różne pliki.

Reguły są zbyt ogólne, by były przydatne. Najczęstszy błąd: pisanie reguł, które brzmią jak przewodnik po stylu bez konkretnych przykładów. Zamiast “stosuj prawidłową obsługę błędów” napisz “opakuj wszystkie wywołania bazy danych w try/catch i rzuć AppError z @src/lib/errors.ts z odpowiednim kodem statusu HTTP.”

Agent ignoruje reguły. Reguły decydowane przez agenta (alwaysApply: false z opisem) zależą od oceny trafności przez agenta. Jeśli reguła nie jest pobierana dla odpowiednich zadań, ustaw ją jako zawsze stosowaną lub dodaj bardziej szczegółowe wzorce glob.

Dokąd dalej z regułami i szablonami

• Współpraca zespołowa — Udostępniaj reguły zespołowi i wymuszaj standardy
• Strategie dla dużych baz kodu — Reguły są kluczowe dla nawigacji w dużych projektach
• Zarządzanie tokenami — Reguły zużywają tokeny kontekstu; optymalizuj pod kątem trafności