Reguły Projektu

Prosisz AI o utworzenie endpointu API. Generuje kod w stylu Express, gdy twój projekt używa Hono. Umieszcza handler ścieżki w src/routes/, gdy twoją konwencją jest src/api/. Używa var zamiast const. Nazywa plik userController.ts, gdy twój zespół używa kebab-case. Żaden z tych problemów nie jest trudny, ale naprawianie ich za każdym razem to śmierć przez tysiąc cięć. Reguły projektu rozwiązują to na stałe: piszesz instrukcję raz, a AI przestrzega jej w każdej interakcji od tego momentu.

Co Wyniesiesz

• Katalog .cursor/rules/ z praktycznymi regułami, które natychmiast poprawiają jakość wyników AI
• Zrozumienie czterech typów reguł (Always, Auto-attached, Agent-decided, Manual) i kiedy używać każdego
• Gotowe do użycia szablony reguł dla stylu kodu, architektury i testowania
• Workflow do iteracji nad regułami, gdy twój zespół odkrywa nowe wzorce

Jak Działają Reguły w Cursor

Reguły to pliki markdown w .cursor/rules/, które są automatycznie wstrzykiwane do kontekstu AI. Pomyśl o nich jak o trwałych promptach systemowych — instrukcjach, które są stosowane bez konieczności wpisywania ich za każdym razem.

Cursor obsługuje rozszerzenia plików .md i .mdc. Format .mdc dodaje frontmatter do kontrolowania, kiedy reguły są stosowane.

.cursor/rules/
  code-style.mdc        # Stosowane do każdej interakcji
  react-patterns.mdc    # Stosowane podczas edycji plików React
  api-conventions.mdc   # Stosowane podczas edycji ścieżek API
  legacy-handling.md    # Stosowane tylko gdy ręcznie odwołane

Cztery Typy Reguł

Typ	Frontmatter	Kiedy Jest Stosowane
Always Apply	alwaysApply: true	Każdy czat, każdy plik, za każdym razem
Auto-attached	globs: ["src/components/**/*.tsx"]	Gdy agent dotyka plików pasujących do wzorca
Agent-decided	alwaysApply: false + description	Gdy agent określi, że jest istotne na podstawie opisu
Manual	alwaysApply: false, brak globs	Tylko gdy wpiszesz @rule-name w czacie

Tworzenie Pierwszych Reguł

Krok 1: Utwórz Katalog Reguł

Katalog .cursor/rules/ powinien istnieć w głównym katalogu twojego projektu. Cursor tworzy go automatycznie, gdy używasz polecenia “New Cursor Rule”, ale możesz także utworzyć go ręcznie:

mkdir -p .cursor/rules

Krok 2: Zacznij od Reguły Always-Apply

To jest najważniejsza reguła, którą napiszesz. Obejmuje uniwersalne standardy, które nigdy nie powinny być naruszone.

Kopiuj-wklej: szablon podstawowej reguły projektu

Utwórz .cursor/rules/core.mdc z następującą zawartością:

---
description: Podstawowe standardy projektu, które mają zastosowanie do całego kodu
alwaysApply: true
---

# Projekt: [Nazwa Twojego Projektu]

## Stos Technologiczny
- Runtime: Node.js 20 z TypeScript 5.x (tryb ścisły)
- Framework: [Twój framework, np. Next.js 15 App Router]
- Baza danych: [Twoja BD, np. PostgreSQL z Drizzle ORM]
- Testowanie: Vitest dla testów jednostkowych, Playwright dla e2e
- Stylizacja: Tailwind CSS

## Konwencje Kodu
- Używaj const domyślnie, let tylko gdy konieczne jest ponowne przypisanie, nigdy var
- Preferuj async/await nad łańcuchami .then()
- Używaj nazwanych eksportów, nie domyślnych eksportów
- Obsługa błędów: zawsze używaj typowanych błędów, nigdy nie rzucaj surowych stringów
- Nazywanie plików: kebab-case dla plików, PascalCase dla komponentów

## Architektura
- Ścieżki API idą do src/api/
- Logika biznesowa mieszka w src/services/
- Zapytania do bazy danych idą do src/db/
- Współdzielone typy idą do src/types/
- Używaj ponownie istniejących wzorców -- sprawdź podobne implementacje przed tworzeniem nowych

## Czego NIE Robić
- Nie instaluj nowych zależności bez uprzedniego zapytania
- Nie modyfikuj plików konfiguracyjnych (.env, tsconfig, package.json) bez wyraźnej prośby
- Nie usuwaj istniejących testów
- Nie używaj any jako typu -- używaj unknown i zawężaj odpowiednio

Krok 3: Dodaj Reguły Wzorców Plików

Te reguły aktywują się tylko wtedy, gdy agent pracuje na pasujących plikach.

Komponenty React

---
description: Standardy komponentów React
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
---

# Reguły Komponentów React

- Używaj komponentów funkcyjnych z jawnym interfejsem propsów TypeScript
- Wyodrębnij złożoną logikę do niestandardowych hooków w tym samym katalogu
- Utrzymuj komponenty poniżej 150 linii -- podziel na pod-komponenty, jeśli większe
- Używaj modułów CSS lub klas narzędziowych Tailwind, nigdy stylów inline
- Uwzględnij aria-labels dla elementów interaktywnych

## Szablon Komponentu
Odwołaj się do @src/components/Button.tsx jako kanonicznego przykładu
dla typowania propsów, granic błędów i struktury testów.

Ścieżki API

---
description: Wzorce ścieżek API
globs: ["src/api/**/*.ts", "src/pages/api/**/*.ts"]
---

# Standardy Ścieżek API

- Waliduj wszystkie dane wejściowe schematami Zod
- Zwracaj spójny kształt odpowiedzi: { success, data?, error? }
- Uwzględnij ograniczanie szybkości na endpointach zapisu
- Loguj wszystkie błędy ze strukturalnym kontekstem (requestId, userId, endpoint)
- Nigdy nie ujawniaj wewnętrznych szczegółów błędów klientom

## Format Odpowiedzi Błędu
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Format email jest nieprawidłowy"
  }
}
```

Baza Danych

---
description: Konwencje bazy danych i ORM
globs: ["src/db/**/*.ts", "drizzle/**/*", "prisma/**/*"]
---

# Reguły Bazy Danych

- Wszystkie zmiany schematu przechodzą przez migracje, nigdy ręczne instrukcje ALTER
- Używaj transakcji dla zapisów wielotabelowych
- Dodawaj indeksy dla kolumn używanych w klauzulach WHERE i JOINach
- Implementuj miękkie usuwanie (kolumna deletedAt) dla danych zwróconych do użytkownika
- Nazwy tabel: liczba mnoga snake_case (user_profiles, nie UserProfile)
- Nazwy kolumn: snake_case (created_at, nie createdAt)

Krok 4: Dodaj Regułę Agent-Decided

Te reguły mają opis, który agent czyta, aby zdecydować o istotności. Używaj ich dla wytycznych, które mają znaczenie tylko w konkretnych kontekstach.

---
description: Wytyczne optymalizacji wydajności na wypadek, gdy użytkownik pyta o wydajność, opóźnienie lub ulepszenia szybkości
alwaysApply: false
---

# Wytyczne Wydajności

Podczas optymalizacji kodu:
- Profiluj przed optymalizacją -- nie zgaduj wąskich gardeł
- Preferuj ulepszenia algorytmiczne nad mikro-optymalizacjami
- Cachuj kosztowne obliczenia na odpowiedniej warstwie
- Używaj leniwego ładowania dla komponentów niewidocznych przy początkowym renderowaniu
- Dokumentuj poprawę wydajności z metrykami przed/po

Najlepsze Praktyki dla Reguł

Utrzymuj Reguły Skoncentrowane i Krótkie

Zespół Cursor zaleca utrzymywanie reguł poniżej 500 linii. W praktyce 50-200 linii na plik reguły działa najlepiej. Jeden temat na plik.

Odwołuj się do Plików Zamiast Kopiować Kod

Zamiast wklejać cały szablon komponentu do reguły, wskaż kanoniczny przykład:

## Wzorzec Komponentu
Postępuj zgodnie ze strukturą w @src/components/DataTable.tsx dla wszystkich nowych komponentów tabel.

To utrzymuje reguły krótkie i zapobiega ich starzeniu się, gdy referowany kod się zmienia.

Zacznij Prosto, Dodawaj Reguły, Gdy Widzisz Błędy

Nie próbuj pisać z góry każdej możliwej reguły. Zacznij od podstawowej reguły z Kroku 2, używaj Cursor przez tydzień i zauważaj, gdzie AI konsekwentnie dokonuje złego wyboru. Każdy błąd jest sygnałem do dodania reguły.

Uwaga

Typowe anty-wzorce reguł, których należy unikać:

• Kopiowanie całych przewodników stylu: AI już zna typowe konwencje. Dokumentuj tylko to, co jest specyficzne dla twojego projektu.
• Reguły, które sobie przeczą: Jeśli twoja podstawowa reguła mówi “używaj nazwanych eksportów”, ale twoja reguła React mówi “używaj domyślnych eksportów dla stron”, AI się myli.
• Reguły dotyczące rzeczy wyłapywanych przez twój linter: Nie duplikuj reguł ESLint lub Prettier. AI automatycznie uruchamia twój linter.
• Mgliste instrukcje: “Pisz czysty kod” jest bez znaczenia. “Utrzymuj funkcje poniżej 30 linii i wyodrębniaj złożone warunki do nazwanych zmiennych” jest wykonalne.

Commituj Reguły do Git

Reguły należą do kontroli wersji. To wiedza zespołowa:

git add .cursor/rules/
git commit -m "Dodaj reguły projektu dla generowania kodu AI"

Gdy AI popełni błąd, któremu reguła powinna była zapobiec, zaktualizuj regułę i commituj poprawkę. Z czasem twoje reguły stają się żywym dokumentem konwencji twojego zespołu.

AGENTS.md: Prosta Alternatywa

Jeśli twój projekt potrzebuje minimalnych reguł, Cursor obsługuje również prosty plik AGENTS.md w głównym katalogu projektu. Bez frontmatter, bez globs — tylko instrukcje markdown, które zawsze są stosowane.

# Instrukcje Projektu

- To jest projekt Next.js 15 App Router z TypeScript
- Używaj Drizzle ORM dla zapytań do bazy danych
- Wszystkie ścieżki API używają walidacji Zod
- Testuj z Vitest, uruchamiaj testy za pomocą `npm test`

AGENTS.md jest dobry do szybkiego startu. Migruj do .cursor/rules/, gdy potrzebujesz targetowania wzorców plików lub kontroli typu reguły.

Agent Skills: Rozszerzanie Reguł ze Społeczności

Cursor obsługuje Agent Skills — otwarty standard importowania wielokrotnego użytku reguł z zewnętrznych źródeł. To reguły wnoszone przez społeczność, które agent stosuje, gdy określi, że są istotne.

Aby włączyć lub wyłączyć Agent Skills:

1. Otwórz Cursor Settings, następnie Rules
2. Znajdź sekcję Import Settings
3. Przełącz Agent Skills na włączone lub wyłączone

Możesz także importować reguły bezpośrednio z repozytoriów GitHub przez Cursor Settings, następnie Rules, Commands, następnie Add Rule, następnie Remote Rule.

Prompt do skopiowania do generowania reguł z twojej bazy kodu

Otwórz tryb Agent i wklej:

Przeanalizuj tę bazę kodu i wygeneruj reguły projektu Cursor na podstawie wzorców,
które znajdziesz. Utwórz osobne pliki .mdc w .cursor/rules/ dla:
1. Podstawowych konwencji kodowania (zawsze stosuj)
2. Wzorców komponentów frontendowych (auto-dołącz do src/components/)
3. Standardów ścieżek API (auto-dołącz do src/api/)
4. Konwencji testowania (auto-dołącz do plików testowych)

Używaj istniejącego kodu jako przykładów tego, co należy przestrzegać. Utrzymuj każdą regułę poniżej 100 linii.

Kiedy To Nie Działa

Reguły nie są stosowane: Sprawdź, czy plik jest w .cursor/rules/ (nie .cursor/rule/ lub głównym katalogu projektu). Zweryfikuj składnię frontmatter — brakujący ogranicznik --- psuje parsowanie. Najedź na wskaźnik kontekstu w polu promptu, aby zobaczyć, które reguły są aktywne.

Reguły kolidują ze sobą: Agent próbuje przestrzegać wszystkich aktywnych reguł jednocześnie. Jeśli masz sprzeczne instrukcje, zachowanie jest nieprzewidywalne. Audytuj swoje reguły pod kątem konfliktów.

Reguły czynią AI zbyt sztywnymi: Jeśli AI odmawia zrobienia czegoś rozsądnego, ponieważ reguła mówi, żeby nie, albo uczyń regułę bardziej konkretną, albo dodaj wyjątek. Reguły powinny kierować, nie krępować.

Wygenerowane reguły są zbyt ogólne: Reguły generowane przez AI często zaczynają się mgliste. Traktuj je jako pierwszy szkic i edytuj intensywnie. Zastąp “przestrzegaj najlepszych praktyk” konkretnymi, mierzalnymi instrukcjami.

Co Dalej

Workflow PRD Przekształć mgliste prośby o funkcje w systematyczne plany implementacji używając trybu Plan w Cursor i metodologii PRD.