Zasady projektu

Zasady projektu to fundament skutecznego rozwoju wspomaganego przez AI. W tym 10-minutowym przewodniku nauczysz się tworzyć zasady które zapewniają spójne generowanie kodu zgodne ze standardami twojego zespołu.

Zrozumienie zasad projektu

Architektura systemu zasad

.cursor/rules/
├── always/              # Stosowane do każdej interakcji AI
├── auto-attached/       # Stosowane na podstawie wzorców plików
├── agent-requested/     # AI decyduje kiedy stosować
└── manual/             # Tylko gdy wyraźnie się odwołujesz

Jak działają zasady

Automatyczny kontekst

Zasady stają się częścią kontekstu AI automatycznie, jak posiadanie seniora zawsze przewodniczącego juniorowi

Kontrola wersji

Sprawdzaj zasady do Git żeby cały zespół korzystał ze wspólnej wiedzy i standardów

Hierarchiczne

Zasady kaskadują od katalogu głównego projektu do podkatalogów, z lokalnymi zasadami nadpisującymi globalne

Dynamiczne aktualizacje

Aktualizuj zasady w locie - AI natychmiast przyjmuje nowe wytyczne bez restartu

Generuj początkowe zasady

Automatyczne generowanie

Otwórz paletę komend: Cmd/Ctrl + Shift + P
Uruchom komendę generowania: “Generate Cursor Rules”

Przejrzyj wygenerowaną strukturę:

.cursor/rules/
├── code-style.mdc
├── architecture.mdc
├── testing.mdc
└── documentation.mdc

Dostosuj wygenerowane zasady: edytuj każdy plik aby pasował do twoich standardów

Co zostaje wygenerowane

Cursor analizuje twoją bazę kodu i tworzy zasady dla:

Stylu kodowania z istniejących wzorców
Architektury ze struktury projektu
Wzorców testowania z plików testowych
Dokumentacji z komentarzy/docs
Zależności z plików pakietów
Konwencji Git z historii commitów

Typy zasad i użycie

1. Zasady Always

Zasady zawsze stosowane

Zasady które stosują się do każdej interakcji AI. Używaj oszczędnie dla uniwersalnych standardów.

---
description: Podstawowe standardy kodowania
alwaysApply: true
---

# Uniwersalne standardy

- Nigdy nie commituj sekretów ani kluczy API
- Zawsze obsługuj błędy jawnie
- Używaj trybu strict TypeScript
- Podążaj za konfiguracją ESLint
- Dołączaj testy jednostkowe dla nowych funkcji

2. Zasady auto-attached

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

# Zasady komponentów React

- Używaj tylko komponentów funkcyjnych
- Implementuj odpowiednie propsy TypeScript
- Dołączaj historie Storybook
- Używaj modułów CSS do stylowania
- Podążaj za zasadami atomic design

## Struktura komponentu
```typescript
interface ComponentProps {
  // Udokumentowane propsy
}

export const Component: FC<ComponentProps> = (props) => {
  // Implementacja
};

---
description: Standardy endpointów API
globs: ["src/api/**/*.ts"]
---

# Zasady rozwoju API

- Używaj konwencji RESTful
- Implementuj odpowiednią obsługę błędów
- Dołączaj dokumentację OpenAPI
- Waliduj wszystkie inputy z Zod
- Zwracaj spójne formaty odpowiedzi

## Format odpowiedzi
```typescript
{
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
  meta?: { page: number; total: number };
}

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

# Zasady bazy danych

- Używaj migracji dla zmian schematu
- Nigdy nie używaj surowego SQL w kodzie aplikacji
- Implementuj soft delete
- Dodawaj indeksy dla kluczy obcych
- Używaj transakcji dla aktualizacji wielu tabel

## Konwencje nazewnictwa
- Tabele: plural_snake_case
- Kolumny: snake_case
- Indeksy: idx_table_columns

3. Zasady agent-requested

---
description: Wytyczne optymalizacji wydajności - AI używa przy optymalizacji kodu
alwaysApply: false
---

# Optymalizacja wydajności

Przy optymalizacji kodu:
- Profiluj przed optymalizacją
- Dokumentuj poprawy wydajności
- Rozważ kompromisy pamięć vs CPU
- Używaj cache strategicznie
- Implementuj lazy loading gdzie odpowiednie

4. Zasady manualne

---
description: Obsługa kodu legacy - użyj @legacy-rules
alwaysApply: false
---

# Wytyczne kodu legacy

Przy pracy z kodem legacy:
- Utrzymuj kompatybilność wsteczną
- Dodawaj ostrzeżenia deprecation
- Twórz przewodniki migracji
- Testuj dokładnie przed refaktoryzacją

Tworzenie skutecznych zasad

Najlepsze praktyki pisania zasad

Bądź konkretny i wykonalny

❌ "Pisz dobry kod"
✅ "Używaj const dla wartości niemutowalnych, let dla mutowalnych"

Dołączaj przykłady

## Wzorzec obsługi błędów
```typescript
try {
  const result = await riskyOperation();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operacja zawiodła', { error, context });
  return { success: false, error: error.message };
}

Dostarczaj kontekst

# Dlaczego ta zasada
Używamy dependency injection aby poprawić testowalność
i zmniejszyć sprzężenie między modułami.

Trzymaj zasady skupione
- Jeden temat na plik zasad
- 50-200 linii optymalna długość
- Jasne nagłówki sekcji

Biblioteka szablonów zasad

---
description: Najlepsze praktyki bezpieczeństwa
alwaysApply: true
---

# Standardy bezpieczeństwa

## Uwierzytelnianie
- Używaj tokenów JWT z krótkim wygaśnięciem
- Implementuj rotację refresh tokenów
- Przechowuj wrażliwe dane w zmiennych środowiskowych
- Hashuj hasła z bcrypt (min 10 rund)

## Walidacja input
- Sanityzuj wszystkie inputy użytkownika
- Używaj parametryzowanych zapytań
- Implementuj ograniczenia częstości
- Waliduj uploady plików

## NIGDY
- Nie loguj haseł ani tokenów
- Nie używaj eval() ani dynamicznego wykonania kodu
- Nie ufaj walidacji po stronie klienta
- Nie przechowuj sekretów w kodzie

---
description: Standardy i wzorce testowania
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

# Wytyczne testowania

## Struktura testu
- Używaj wzorca AAA (Arrange, Act, Assert)
- Jedna asercja na test gdy możliwe
- Opisowe nazwy testów które wyjaśniają scenariusz

## Wymagania pokrycia
- Minimalne pokrycie kodu 80%
- 100% pokrycia dla ścieżek krytycznych
- Testuj przypadki brzegowe i scenariusze błędów

## Przykład testu
```typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('powinien zahashować hasło przed zapisem', async () => {
      // Arrange
      const userData = { email: 'test@example.com', password: 'plain' };

      // Act
      const user = await userService.createUser(userData);

      // Assert
      expect(user.password).not.toBe('plain');
      expect(bcrypt.compareSync('plain', user.password)).toBe(true);
    });
  });
});

---
description: Standardy dokumentacji
alwaysApply: false
---

# Wymagania dokumentacji

## Komentarze kodu
- JSDoc dla wszystkich funkcji publicznych
- Wyjaśnij DLACZEGO, nie CO
- Dokumentuj złożone algorytmy
- Dołączaj przykłady dla narzędzi

## Szablon JSDoc

/**
 * Oblicza odsetki składane
 * @param principal - kwota początkowa
 * @param rate - roczna stopa procentowa (jako ułamek dziesiętny)
 * @param time - okres czasu w latach
 * @param n - częstość kapitalizacji na rok
 * @returns końcowa kwota po odsetkach składanych
 * @example
 * calculateCompoundInterest(1000, 0.05, 2, 12) // $1104.94
 */

## Sekcje README
1. Przegląd projektu
2. Szybki start
3. Architektura
4. Dokumentacja API
5. Wytyczne kontrybucji

Dynamiczne zarządzanie zasadami

Aktualizuj zasady z czatu

Podczas rozwoju:

AI: "Użyję PostgreSQL dla tej funkcji"
Ty: "# Zawsze używaj MySQL dla naszych projektów, nie PostgreSQL"

Zasada zostaje dodana:

# Wybór bazy danych
Zawsze używaj MySQL dla naszych projektów, nie PostgreSQL

Natychmiastowy efekt: następne żądanie użyje MySQL

Generuj zasady z rozmów

Po produktywnej sesji:

Uruchom /Generate Cursor Rules w czacie
AI ekstraktuje wzorce i decyzje
Tworzy zasady do przyszłego użycia
Przejrzyj i commituj do Git

Strategie organizacji zasad

Według funkcji

.cursor/rules/
├── features/
│   ├── authentication/
│   │   ├── jwt-tokens.mdc
│   │   └── oauth-flow.mdc
│   ├── payments/
│   │   ├── stripe-integration.mdc
│   │   └── invoice-generation.mdc
│   └── notifications/
│       ├── email-templates.mdc
│       └── push-notifications.mdc

Według warstwy

.cursor/rules/
├── presentation/
│   ├── components.mdc
│   └── styles.mdc
├── business/
│   ├── services.mdc
│   └── validation.mdc
└── data/
    ├── repositories.mdc
    └── migrations.mdc

Według problemu

.cursor/rules/
├── performance/
│   ├── caching.mdc
│   └── optimization.mdc
├── security/
│   ├── authentication.mdc
│   └── encryption.mdc
└── quality/
    ├── testing.mdc
    └── code-review.mdc

Zaawansowane techniki zasad

Zasady warunkowe

---
description: Zasady specyficzne dla środowiska
globs: ["src/**/*.ts"]
---

# Zasady środowiska

## Development
Gdy NODE_ENV to development:
- Używaj verbose logging
- Włącz endpointy debug
- Pomiń wysyłanie email

## Production
Gdy NODE_ENV to production:
- Używaj strukturalnego logowania
- Wyłącz endpointy debug
- Implementuj ograniczenia częstości

Odwołania do plików zewnętrznych

---
description: Wzorce architektury
---

# Podążaj za naszą architekturą

Implementuj wzorce z:
@architecture/diagrams/system-design.png
@architecture/decisions/adr-001.md

Kluczowe zasady:
- Komunikacja sterowana zdarzeniami
- CQRS dla złożonych domen
- Wzorzec Repository dla dostępu do danych

Progresywne ulepszanie

---
description: Wytyczne refaktoryzacji
globs: ["src/legacy/**/*"]
---

# Refaktoryzacja kodu legacy

## Faza 1: Dodaj typy
- Dodaj typy TypeScript do interfejsów
- Dokumentuj istniejące zachowanie
- Nie zmieniaj funkcjonalności

## Faza 2: Wyodrębnij funkcje
- Rozbij duże funkcje < 50 linii
- Wyodrębnij narzędzia wielokrotnego użytku
- Dodaj testy jednostkowe

## Faza 3: Modernizuj
- Konwertuj na async/await
- Używaj nowoczesnych funkcji JS
- Aktualizuj zależności

Walidacja zasad

Częste problemy których należy unikać

Nadmierna specyfikacja

Nie twórz zasad dla każdego drobnego szczegółu - skup się na ważnych wzorcach

Sprzeczności

Upewnij się że zasady nie kolidują ze sobą lub istniejącymi narzędziami

Przestarzałe zasady

Przeglądaj i aktualizuj zasady kwartalnie gdy projekt ewoluuje

Niejasne instrukcje

Zastąp “pisz czysty kod” konkretnymi, mierzalnymi wytycznymi

Testowanie twoich zasad

Utwórz scenariusz testowy:

"Utwórz nowy endpoint API dla profili użytkownika"

Zweryfikuj że AI podąża za zasadami:
- Sprawdź zgodność stylu kodu
- Zweryfikuj wzorce architektury
- Potwierdź podejście testowe
Iteruj jeśli potrzeba:
- Wyjaśnij niejasne zasady
- Dodaj brakujące przykłady
- Usuń nieefektywne zasady

Współpraca zespołowa

Dzielenie zasad

Commituj do Git:

git add .cursor/rules/
git commit -m "Dodaj standardy kodowania projektu"
git push

Dokumentuj w README:

## Standardy kodowania AI

Ten projekt używa zasad Cursor dla spójnej pomocy AI.
Zasady są w `.cursor/rules/` i stosują się automatycznie.

Aby aktualizować zasady:
1. Edytuj odpowiednie pliki `.mdc`
2. Testuj z AI
3. Commituj zmiany

Regularne przeglądy:
- Miesięczne spotkania przeglądu zasad
- Śledź skuteczność zasad
- Aktualizuj na podstawie feedbacku zespołu

Następne kroki

Kontynuuj do przepływu pracy PRD

Teraz opanujmy przepływ pracy PRD → Plan → Todo który transformuje sposób budowania funkcji.

Przepływ pracy PRD →

Czas: 15 minut