Reguły projektu w Cursorze

Reguły projektu Cursora udostępniają agentowi konwencje architektury, stylu i bezpieczeństwa. Ten przewodnik pokazuje tworzenie plików .mdc w .cursor/rules/, dobór zasięgu, łączenie reguł ze skillami oraz weryfikację aktywacji. Szerszy cykl opisuje etap Design.

Reguły projektu to pliki Markdown zapisane w katalogu .cursor/rules/, które automatycznie wstrzykują trwałe instrukcje do kontekstu Cursora. Eliminują konieczność powtarzania tych samych wytycznych w promptach, jednorazowo ucząc model decyzji inżynieryjnych zespołu.

---

Co zapewniają reguły projektu

Ustrukturyzowana konfiguracja reguł zapewnia cztery korzyści:

• Eliminuje powtarzalne promptowanie poprzez zapisanie stosu technologicznego, wzorców plików i konwencji architektonicznych w repozytorium.
• Precyzyjnie zarządza budżetem kontekstu dzięki dopasowaniu masek plików (globs) i aktywacji decydowanej przez agenta.
• Egzekwuje nienaruszalne granice, takie jak zakaz bezpośredniej edycji plików konfiguracyjnych czy instalowania nieautoryzowanych zależności.
• Standaryzuje praktyki zespołowe dzięki kontroli wersji w katalogu .cursor/rules/.

---

Typy reguł i wyzwalacze aktywacji

Cursor obsługuje pliki .mdc z nagłówkiem YAML frontmatter, który kontroluje, kiedy reguła trafia do okna kontekstu agenta.

Poniższa tabela przedstawia cztery typy reguł dostępne w Cursorze:

Typ reguły	Konfiguracja frontmatter	Warunek aktywacji
Always Apply	alwaysApply: true	Dołączana do każdego czatu, sesji Composer i wywołania agenta.
Auto-attached	globs: ["src/components/**/*.tsx"]	Aktywuje się automatycznie, gdy agent odczytuje lub modyfikuje pasujące pliki.
Agent-decided	alwaysApply: false + description	Wstrzykiwana, gdy agent uzna jej zasadność na podstawie opisu.
Manual	alwaysApply: false (brak globs)	Wstrzykiwana wyłącznie po jawnym wskazaniu @NAZWA_REGULY w czacie.

---

Konfiguracja reguł projektu

Wykonaj poniższe kroki, aby wdrożyć reguły w repozytorium.

1. Utwórz katalog reguł

Utwórz katalog .cursor/rules/ w głównym folderze repozytorium:

mkdir -p .cursor/rules

2. Dodaj regułę bazową Always-Apply

Utwórz plik .cursor/rules/core.mdc definiujący standardy obowiązujące w każdej sesji:

---
description: Podstawowe standardy repozytorium i granice bezpieczeństwa
alwaysApply: true
---

# Standardy projektu: NAZWA_PROJEKTU

## Stos technologiczny
- Runtime: Node.js 22 z TypeScript 5.x (tryb strict)
- Framework: Astro 5 z komponentami React 19
- Baza danych: Cloudflare D1 z zapytaniami parametryzowanymi
- Testy: Vitest dla testów jednostkowych, Playwright dla E2E
- Stylowanie: Tailwind CSS

## Konwencje kodu
- Używaj `const` zamiast `let`; zakaz stosowania `var`.
- Stosuj eksporty nazwane zamiast domyślnych.
- Obsługa błędów: rzucaj dedykowane klasy błędów; nigdy nie rzucaj stringów.
- Nazewnictwo plików: kebab-case dla modułów, PascalCase dla komponentów React.

## Granice i zakazy
- Nie instaluj nowych zależności bez wyraźnej prośby.
- Nie modyfikuj plików konfiguracyjnych (`tsconfig.json`, `package.json`, `.dev.vars`) bez zatwierdzonego planu.
- Nigdy nie modyfikuj ani nie usuwaj asercji w istniejących plikach testowych.
- Nigdy nie twórz zapytań do bazy danych bez izolacji tenanta (`organization_id`).

Zastąp NAZWA_PROJEKTU nazwą Twojego projektu.

3. Dodaj reguły dla konkretnych podsystemów

Utwórz reguły aktywowane tylko przy pracy z odpowiednimi plikami:

Komponenty React

---
description: Standardy komponentów React i Tailwind CSS
globs: ["src/components/**/*.tsx", "src/pages/**/*.astro"]
alwaysApply: false
---

# Wytyczne komponentów

- Twórz komponenty funkcyjne z otypowanymi interfejsami propsów.
- Wydzielaj złożony stan do osobnych hooków w tym samym katalogu.
- Zapewnij atrybuty `aria-label` dla wszystkich elementów interaktywnych.
- Stosuj klasy Tailwind; nie twórz stylów inline.

Trasy API

---
description: Wzorce tras API, walidacja i format odpowiedzi błędów
globs: ["src/pages/api/**/*.ts", "src/services/**/*.ts"]
alwaysApply: false
---

# Standardy tras API

- Waliduj payloady żądań za pomocą schematów Zod przed przetwarzaniem.
- Zwracaj ujednolicone odpowiedzi: `{ success: boolean, data?: unknown, error?: unknown }`.
- Stosuj filtr izolacji tenanta w każdym zapytaniu do bazy.
- Nie ujawniaj surowych błędów bazy ani stack trace'ów klientom API.

Operacje bazodanowe

---
description: Konwencje bazy Cloudflare D1 i zapytań SQL
globs: ["src/db/**/*.ts", "migrations/**/*.sql"]
alwaysApply: false
---

# Wytyczne bazy danych

- Wszystkie zapytania muszą być sparametryzowane: `db.prepare(QUERY).bind(PARAM_1)`.
- Zapisuj migracje w `migrations/` z prefiksem czasu: `YYYYMMDD_HHMMSS_OPIS.sql`.
- Zakaz usuwania kolumn bez wieloetapowego planu migracji.

---

Integracja ze Skillami Agenta

Cursor automatycznie wykrywa skille zapisane w .cursor/skills/, .agents/skills/ oraz .claude/skills/.

Podczas gdy reguły (.cursor/rules/*.mdc) stanowią stałe ograniczenia, skille dostarczają procedur krok po kroku dla złożonych przepływów pracy.

Aby włączyć Agent Skills w Cursorze:

1. Otwórz Cursor Settings (Cmd+, lub Ctrl+,).
2. Przejdź do Features > Rules for AI.
3. W sekcji Agent Skills upewnij się, że opcja jest włączona.

---

Weryfikacja konfiguracji reguł

Aby upewnić się, że reguły są aktywne i poprawnie wczytywane:

1. Potwierdź obecność plików .mdc w katalogu .cursor/rules/:

   ls -la .cursor/rules/*.mdc

2. W Cursorze otwórz panel Chat (Cmd+L lub Ctrl+L).
3. Najedź kursorem na wskaźnik aktywnego kontekstu w pasku promptu.
4. Upewnij się, że reguła core.mdc widnieje na liście aktywnych reguł.
5. Otwórz plik pasujący do src/components/**/*.tsx i sprawdź, czy reguła komponentów dołącza się automatycznie.

---

Zastosowanie reguł do zaplanowanej zmiany

Przepływ PRD Przekształcaj wymagania produktowe w uporządkowane plany implementacji przy użyciu trybu Plan w Cursorze.