02 - Reguły kursora: Konfiguracja AI dla Twojego projektu
Każdy deweloper ma swoje własne konwencje, wzorce architektoniczne i standardy jakości. Kiedy pracujesz z ludzkim współpracownikiem, zasady te są przekazywane poprzez przegląd kodu, programowanie w parach i dokumentację. Ale jak przekazać te same oczekiwania agentowi AI? Odpowiedź kursora i System reguł: potężny i elastyczny mechanizm, który pozwala instruować sztuczną inteligencję, jak to zrobić musi wygenerować, zmodyfikować i uzasadnić kod swojego projektu.
W tym artykule zbadamy każdy aspekt systemu reguł kursora: począwszy od jego historycznej ewolucji do zaawansowanych strategii konfiguracyjnych, przechodząc przez praktyczne przykłady Angular, React, Python, backendy API i wiele więcej. W końcu będziesz mieć wszystkie narzędzia, dzięki którym Cursor AI stanie się współpracownikiem szanuj konwencje swojego zespołu tak, jakby znali je od zawsze.
Czego dowiesz się w tym artykule
- Ewolucja systemu reguł: od
.cursorrulesdo katalogu.cursor/rules/ - Cztery typy reguł: Zawsze, Dołączane automatycznie, Żądanie agenta i Ręczne
- Różnica między regułami użytkownika a regułami projektu oraz kiedy używać każdego typu
- Jak pisać skuteczne reguły z frontmatterem, globami i opisami
- Kompletne przykłady dla Angular, React, Python, FastAPI i REST API
- Zaawansowane strategie: reguły warunkowe, dziedziczenie reguł, automatyczne generowanie
- Przepływ pracy w zespole: udostępnianie za pośrednictwem gita, wdrażanie i wspólne konwencje
- Porównanie z CLAUDE.md i innymi systemami instrukcji AI
Przegląd serii Cursor IDE i AI-Native Development
| # | Przedmiot | Centrum |
|---|---|---|
| 1 | Kompletny przewodnik po IDE kursora | Pełny przegląd |
| 2 | Jesteś tutaj - Reguły kursora | Niestandardowa konfiguracja AI |
| 3 | Tryb agenta | Zaawansowana automatyzacja |
| 4 | Tryb planu | Wspomagane planowanie |
| 5 | Haczyki i MCP | Rozszerzalność i integracje |
| 6 | Profesjonalne przepływy pracy | Najlepsze praktyki produkcyjne |
Ewolucja systemu reguł w kursorze
System reguł kursora przeszedł znaczącą ewolucję od czasu jego pierwszego wprowadzenia. Zrozumienie tej historii ma fundamentalne znaczenie dla zrozumienia, dlaczego obecny system ma określoną strukturę oraz aby uniknąć pomyłek między różnymi generacjami konfiguracji.
Pierwsza generacja: plik .cursorrules
W pierwszej implementacji Cursor obsługiwał pojedynczy plik .cursorrules w katalogu głównym projektu.
Plik ten zawierał instrukcje tekstowe, które zostały wstawione w kontekst każdej interakcji AI.
To było proste i jednoznaczne: zapisz swoje zasady w pliku, a sztuczna inteligencja będzie ich przestrzegać.
Sei uno sviluppatore senior specializzato in Angular e TypeScript.
Regole di codice:
- Usa sempre standalone components
- Preferisci signals rispetto a BehaviorSubject
- Usa OnPush change detection in tutti i componenti
- Scrivi sempre i test unitari per i servizi
- Segui le convenzioni di naming Angular (kebab-case per i file)
Stile di risposta:
- Rispondi in italiano
- Spiega il ragionamento dietro ogni scelta
- Includi gestione degli errori in ogni esempio
Podejście to miało oczywiste ograniczenia: wszystkie reguły znalazły się w jednym, monolitycznym pliku.
W złożonym projekcie z frontendem Angular, backendem Pythona, infrastrukturą Docker i potokiem CI/CD,
plik .cursorrules szybko stał się ogromny i trudny do zarządzania. Poza tym wszystkie zasady
zawsze były wysyłane do sztucznej inteligencji, nawet jeśli nie były istotne w bieżącym kontekście.
Druga generacja: reguły projektu z .cursor/rules/
Aby rozwiązać te ograniczenia, Cursor wprowadził Regulamin projektu oparty na
katalog .cursor/rules/. To nowe podejście pozwala organizować reguły w oddzielnych plikach,
ze strukturalnymi metadanymi i warunkową aktywacją na podstawie wzorców plików.
Katalog .cursor/rules/ i miał być przypisany do repozytorium git, aby wszyscy
członkowie zespołu automatycznie dzielą się tymi samymi instrukcjami AI. Każdy plik w katalogu jest plikiem
.mdc (Markdown with Context), który zawiera frontman YAML i treść instrukcji w Markdown.
Dlaczego .mdc, a nie .md?
Format .mdc (Markdown with Context) to zastrzeżone rozszerzenie kursora, które dodaje
standardowy frontmatter o strukturze Markdown. Frontmatter definiuje metadane jako opis
regułę, wzorce globu dla automatycznej aktywacji i flagę alwaysApply. Kursor interpretuje
te metadane, aby zdecydować, kiedy i jak zastosować każdą regułę.
Cztery typy reguł
Nowoczesny system Cursor definiuje cztery tryby aktywacji reguł, z których każdy jest przeznaczony konkretny przypadek użycia. Wybór odpowiedniego typu ma kluczowe znaczenie, aby zrównoważyć znaczenie instrukcji z wykorzystaniem kontekstu AI.
1. Zawsze rządzi
Typ rządzi Zawsze są uwzględniane w każdej interakcji z sztuczną inteligencją z pliku, nad którym pracujesz, lub z złożonego żądania. Idealnie wpasowują się w uniwersalne konwencje projekt, który zawsze należy szanować.
---
description: Convenzioni globali del progetto
alwaysApply: true
---
# Convenzioni Progetto
## Linguaggio
- Rispondi sempre in italiano
- Usa commenti in inglese nel codice
- Variabili e funzioni in inglese (camelCase)
## Architettura
- Pattern: Feature-based folder structure
- State management: Signals (Angular) / Zustand (React)
- Testing: Ogni modulo deve avere copertura > 80%
## Git
- Commit messages in conventional commits format
- Prefissi: feat, fix, refactor, docs, test, chore
- Branch naming: feature/xxx, bugfix/xxx, hotfix/xxx
Uwaga na zużycie kontekstu
Zasady Zawsze przyjdź Zawsze wysyłane do sztucznej inteligencji, zużywając w każdym tokeny kontekstu interakcja. Używaj tego typu tylko dla naprawdę uniwersalnych reguł. Jeśli reguła dotyczy tylko niektórych plików lub sytuacji, wybierz opcję Dołącz automatycznie lub Żądanie agenta, aby zoptymalizować wykorzystanie kontekstu.
2. Reguły dołączane automatycznie
Zasady Dołączane automatycznie są automatycznie aktywowane podczas pracy nad pasującymi plikami do określonych wzorców globu. Doskonale nadają się do reguł specyficznych dla języka, frameworku lub typu pliku.
---
description: Regole per componenti Angular
globs: ["**/*.component.ts", "**/*.component.html"]
alwaysApply: false
---
# Componenti Angular
## Struttura
- Usa SEMPRE standalone components (no NgModule)
- Implementa OnPush change detection strategy
- Preferisci signals() e computed() per lo stato reattivo
- Usa input() e output() signal-based (non @Input/@Output decorators)
## Template
- Usa la nuova control flow syntax: @if, @for, @switch
- Preferisci @defer per lazy loading di sezioni pesanti
- Non usare mai ngIf, ngFor, ngSwitch (legacy)
## Naming
- File: kebab-case (es. user-profile.component.ts)
- Selettore: prefisso app- (es. app-user-profile)
- Classe: PascalCase (es. UserProfileComponent)
Pole globs obsługuje standardowe wzorce globalne. Możesz używać prostych symboli wieloznacznych, takich jak *.ts
lub złożone wzory, takie jak {**/*.service.ts,**/*.guard.ts}. Kiedy otwierasz plik
pasujący do wzorca, reguła zostanie automatycznie uwzględniona w kontekście AI.
3. Zasady wymagane przez agenta
Zasady Prośba o agenta są widoczne dla AI poprzez opis, ale przychodzą włączane do kontekstu tylko wtedy, gdy agent uzna, że są one istotne dla bieżącego zadania. Ten facet i idealne rozwiązanie w przypadku przepisów specjalistycznych, które nie zawsze są potrzebne, ale w razie potrzeby sztuczna inteligencja musi mieć możliwość konsultacji.
---
description: Regole per la creazione e gestione delle migrazioni database con Prisma
alwaysApply: false
---
# Migrazioni Database
## Creazione Migrazioni
- Usa sempre `prisma migrate dev --name descrizione-cambiamento`
- Nomi migrazioni: snake_case, descrittivi (es. add_user_roles_table)
- Non modificare MAI migrazioni già applicate in produzione
## Schema Prisma
- Ogni modello deve avere: id, createdAt, updatedAt
- Usa @@map per nomi tabella in snake_case
- Relazioni: definisci sempre entrambi i lati
- Indici: aggiungi @@index per campi usati in WHERE e JOIN
## Rollback
- Testa sempre il rollback prima di applicare in staging
- Documenta i passaggi manuali necessari nel file di migrazione
W tym przykładzie reguła nie ma globs i ma alwaysApply: false. Sztuczna inteligencja będzie widzieć tylko
opis „Zasady tworzenia i zarządzania migracjami baz danych za pomocą Prisma” i zadecyduję samodzielnie
czy uwzględnić pełną treść reguły, gdy zadanie obejmuje operacje na bazie danych. To podejście
i szczególnie wydajne: AI ma dostęp do katalogu wiedzy eksperckiej bez marnowania kontekstu
kiedy nie są potrzebne.
4. Zasady ręczne
Zasady Podręcznik nigdy nie są one uwzględniane automatycznie. Należy o nich wyraźnie wspomnieć
przez programistę za pomocą odniesienia @ruleName w monicie. Przydają się do szablonów,
fragmenty lub instrukcje, których chcesz używać tylko w określonych sytuacjach.
---
description: Template per la creazione di una nuova feature Angular completa
alwaysApply: false
---
# Template Nuova Feature
Quando creo una nuova feature Angular, genera i seguenti file:
## Struttura Directory
```
src/app/features/[feature-name]/
[feature-name].component.ts # Componente principale
[feature-name].component.html # Template
[feature-name].component.css # Stili
[feature-name].component.spec.ts # Test componente
[feature-name].service.ts # Servizio dati
[feature-name].service.spec.ts # Test servizio
[feature-name].routes.ts # Routing lazy-loaded
[feature-name].model.ts # Interfacce e tipi
```
## Checklist
- [ ] Componente standalone con OnPush
- [ ] Servizio con HttpClient e gestione errori
- [ ] Route lazy-loaded registrata in app.routes.ts
- [ ] Test unitari per componente e servizio
- [ ] Interfacce per i modelli dati
Aby skorzystać z tej reguły, programista napisze coś takiego: „Utwórz nową funkcję dla swojego profilu użytkownika, postępując zgodnie z @new-feature-template”. AI uwzględni treść reguły w kontekście i wygeneruje kod zgodnie z szablonem.
Podsumowanie typów reguł
| Typ | Aktywacja | Przypadek użycia | Kontekst konsumpcji |
|---|---|---|---|
| Zawsze | Zawsze w cenie | Uniwersalne konwencje projektowe | Wysoki (zawsze aktywny) |
| Dołączane automatycznie | Wzór globu w pliku | Zasady specyficzne dla języka/frameworka | Średni (tylko istotne pliki) |
| Prośba o agenta | AI podejmuje decyzję na podstawie opisu | Wiedza ekspercka na żądanie | Niski (tylko w razie potrzeby) |
| Podręcznik | Wyraźne wywołanie z @name | Szablony, fragmenty, rzadkie instrukcje | Minimalna (tylko na żądanie) |
Reguły użytkownika a zasady projektu
Kursor rozróżnia dwa poziomy konfiguracji: le Regulamin użytkownika które dotyczą każdego Twoje projekty i Regulamin projektu które są specyficzne dla pojedynczego repozytorium. Zrozumienie, kiedy używać jednego lub drugiego, ma kluczowe znaczenie dla skutecznej konfiguracji.
Reguły użytkownika: Twoje preferencje globalne
Reguły użytkownika są konfigurowane w Cursor Settings > General > Rules for AI. Te zasady
określają Twoje osobiste preferencje, które pozostają niezmienne niezależnie od projektu, nad którym pracujesz.
Nie są to pliki w repozytorium: znajdują się w lokalnej konfiguracji kursora.
## Preferenze Generali
- Rispondi sempre in italiano per le spiegazioni
- Scrivi commenti nel codice in inglese
- Quando generi codice, aggiungi sempre la gestione degli errori
- Preferisci l'immutabilita: crea nuovi oggetti invece di mutare quelli esistenti
- Usa TypeScript strict mode in tutti i progetti TypeScript
- Segui i principi SOLID e clean code
- Quando suggerisci soluzioni, spiega il ragionamento
## Formato Preferito
- Funzioni brevi (<50 righe)
- File focalizzati (<400 righe)
- Nesting massimo: 4 livelli
- Naming esplicito e descrittivo
Zasady projektu: Konwencje dotyczące repozytoriów
Zasady projektu znajdują się w katalogu .cursor/rules/ projektu i są zaangażowani
w repozytorium git. Oznacza to, że każdy członek zespołu, który sklonuje repozytorium, automatycznie będzie miał takie repozytorium
te same instrukcje AI, zapewniając spójność w generowaniu kodu.
Reguły użytkownika a reguły projektu: kiedy czego używać
| Czekam | Regulamin użytkownika | Regulamin projektu |
|---|---|---|
| Miotły | Wszystkie projekty | Pojedyncze repozytorium |
| Pozycja | Ustawienia kursora | .cursor/rules/*.mdc |
| Partycypujący | Tylko lokalnie | Przez git (zespół) |
| Pierwszeństwo | Baza (zastąpiona przez projekt) | Wysoka (w zależności od kontekstu) |
| Przykład | Język, styl reakcji, zasady ogólne | Framework, architektura, konkretne wzorce |
La pierwszeństwo Działa to intuicyjnie: Reguły projektu mają pierwszeństwo przed Regułami użytkownika kiedy jest konflikt. Jeśli Twoje Reguły użytkownika mówią „użyj klas”, ale Twoje Reguły projektu mówią „użyj funkcji”, sztuczna inteligencja będzie przestrzegać Zasad projektu. Dzięki temu każdy projekt może mieć swoje własne konwencje bez konieczność zmiany preferencji globalnych.
Anatomia skutecznej reguły
Napisanie reguły, której sztuczna inteligencja może prawidłowo przestrzegać, wymaga zwrócenia uwagi na strukturę i przejrzystość i prostota instrukcji. Dobrze napisana zasada jest różnicą między sztuczną inteligencją generującą kod generyczne i sztuczna inteligencja generująca kod idealnie dostosowany do Twoich standardów.
Struktura pliku .mdc
Każdy plik .mdc i składa się z dwóch części: Frontman YAML ograniczony przez
--- e il ciało w Markdown z aktualnymi instrukcjami.
---
description: [Descrizione concisa per l'AI - usata per Agent Requested]
globs: ["pattern1", "pattern2"]
alwaysApply: true|false
---
# Titolo della Rule
## Sezione 1: Istruzioni Generali
- Istruzione chiara e specifica
- Esempio concreto se necessario
## Sezione 2: Pattern da Seguire
- Pattern preferito con esempio
- Anti-pattern da evitare con spiegazione
## Sezione 3: Eccezioni
- Quando NON applicare queste regole
- Casi limite e come gestirli
Najlepsze praktyki dotyczące pisania skutecznych reguł
Po skonfigurowaniu setek reguł w rzeczywistych projektach zidentyfikowałem pięć podstawowych zasad które decydują o skuteczności reguły.
1. Bądź konkretny, a nie ogólny. Reguła mówiąca „pisz czysty kod” jest bezużyteczna. Reguła mówiąca, że „każda funkcja musi mieć maksymalnie 4 parametry, każdy z jawnym typem i JSDoc” i obsługiwane przez sztuczną inteligencję.
2. Pokaż, a nie tylko opowiadaj. Zawsze dołączaj co najmniej jeden konkretny przykład kodu, który szanuj zasadę. AI uczy się lepiej na przykładach niż na abstrakcyjnych opisach.
3. Zdefiniuj także anty-wzorce. Wyraźnie określ, czego NIE robić. Jeśli reguła mówi „używaj sygnałów”, ale nie mówi „nie używaj BehaviorSubject”, sztuczna inteligencja może mieszać te dwa podejścia.
4. Reguła, temat. Nie twórz monolitycznych plików obejmujących wszystko. Podziel zasady na obszar: jedna reguła dla testowania, jedna dla CSS, jedna dla architektury. Ułatwia to konserwację i umożliwia selektywną aktywację poprzez kule.
5. Napisz opis z myślą o AI. Pole description na pierwszym planie
oraz co czyta sztuczna inteligencja, aby zdecydować, czy uwzględnić regułę „Żądanie agenta”. To musi być zwięzłe, ale
wystarczająco pouczające, aby umożliwić sztucznej inteligencji zrozumienie, kiedy przepis ma zastosowanie.
Reguły dla Angulara: kompletny przykład
Angular to framework z precyzyjnymi konwencjami i szybko rozwijającym się ekosystemem. Z przejściem do niezależnych komponentów, sygnałów i nowej składni przepływu sterowania, istotne jest, aby sztuczna inteligencja generowała kod zgodnie z nowoczesnymi najlepszymi praktykami. Oto kompletny zestaw reguł dla projektu Angular.
---
description: Architettura e pattern generali del progetto Angular
alwaysApply: true
---
# Architettura Angular
## Versione e Stack
- Angular 19+ con standalone components
- TypeScript 5.7+ in strict mode
- Stato: Angular Signals (signal, computed, effect)
- HTTP: HttpClient con interceptor funzionali
- Routing: Lazy loading con loadComponent/loadChildren
## Struttura Cartelle
```
src/app/
core/ # Servizi singleton, guard, interceptor
shared/ # Componenti, pipe, direttive condivise
features/ # Feature modules (una cartella per feature)
feature-a/
components/
services/
models/
feature-a.routes.ts
layouts/ # Layout components (header, footer, sidebar)
```
## Principi
- NESSUN NgModule: tutto standalone
- Lazy loading per ogni feature route
- Servizi in core/ forniti in root (providedIn: 'root')
- Componenti condivisi in shared/ senza logica di business
- Un componente = un file .ts + .html + .css + .spec.ts
---
description: Regole per l'uso di Angular Signals e reattività
globs: ["**/*.component.ts", "**/*.service.ts"]
alwaysApply: false
---
# Angular Signals
## Stato Reattivo
- USA: signal() per stato locale del componente
- USA: computed() per valori derivati
- USA: effect() SOLO per side effects (logging, localStorage)
- NON USARE: BehaviorSubject per stato locale
- NON USARE: getter con logica complessa (usa computed)
## Input/Output Signal-based
- USA: input() e input.required() per gli input
- USA: output() per gli eventi
- NON USARE: @Input() e @Output() decorators (deprecati)
- USA: model() per two-way binding
## Esempio Corretto
```typescript
export class UserCardComponent {
// Input signal-based
readonly user = input.required<User>();
readonly showAvatar = input(true);
// Computed da input
readonly displayName = computed(() =>
`${this.user().firstName} ${this.user().lastName}`
);
// Output signal-based
readonly selected = output<User>();
onSelect(): void {
this.selected.emit(this.user());
}
}
```
## Anti-pattern da Evitare
```typescript
// SBAGLIATO: decoratori legacy
@Input() user!: User;
@Output() selected = new EventEmitter<User>();
// SBAGLIATO: BehaviorSubject per stato locale
private userSubject = new BehaviorSubject<User | null>(null);
```
---
description: Convenzioni per i test unitari Angular con Jest/Vitest
globs: ["**/*.spec.ts"]
alwaysApply: false
---
# Testing Angular
## Framework
- Test runner: Jest o Vitest (NO Karma/Jasmine)
- Asserzioni: expect() nativo
- Mocking: jest.mock() o vi.mock()
## Struttura Test
- Raggruppa con describe() per metodo/feature
- Naming: "should [expected behavior] when [condition]"
- AAA pattern: Arrange, Act, Assert
- Un assert per test (quando possibile)
## Componenti
- Usa TestBed.configureTestingModule con standalone: true
- Mock tutti i servizi iniettati
- Testa il rendering del template con fixture.debugElement
- Testa gli input/output signal-based con componentRef.setInput()
## Servizi
- Usa TestBed.inject() per ottenere il servizio
- Mock HttpClient con HttpClientTestingModule
- Testa tutti i path: successo, errore, edge case
- Verifica le chiamate HTTP con expectOne()
## Copertura Minima
- Servizi: 90%
- Componenti: 80%
- Utility: 95%
Reguły dla Pythona: kompletny przykład
Python to język o precyzyjnej filozofii (Zen Pythona) i utrwalonych konwencjach (PEP 8). Reguły Pythona muszą uwzględniać te konwencje i dodawać specyfikę projektu.
---
description: Convenzioni Python per il progetto backend
globs: ["**/*.py"]
alwaysApply: false
---
# Convenzioni Python
## Versione e Stile
- Python 3.12+
- Segui PEP 8 rigorosamente
- Type hints su TUTTE le funzioni e variabili di classe
- Usa f-string per la formattazione (mai .format() o %)
- Line length massimo: 100 caratteri
## Type Hints
```python
def get_user_by_id(user_id: int) -> User | None:
"""Recupera un utente per ID."""
...
def process_items(items: list[Item], *, limit: int = 100) -> list[Result]:
"""Processa una lista di item con limite opzionale."""
...
```
## Struttura Classi
- Usa dataclasses o Pydantic models per i dati
- Protocol per le interfacce (non ABC, salvo casi specifici)
- Metodi privati con prefisso _ (singolo underscore)
- Nessun metodo > 30 righe
## Import
- Ordine: stdlib, third-party, local (separati da riga vuota)
- Import assoluti (mai relativi con .)
- Usa `from __future__ import annotations` per type hints moderni
## Error Handling
- Cattura eccezioni specifiche (mai bare except)
- Usa custom exceptions per errori di dominio
- Logging strutturato con structlog
---
description: Pattern e convenzioni per le API FastAPI
globs: ["**/api/**/*.py", "**/routes/**/*.py", "**/endpoints/**/*.py"]
alwaysApply: false
---
# Pattern FastAPI
## Struttura Endpoint
```python
@router.get(
"/users/{user_id}",
response_model=UserResponse,
summary="Get user by ID",
responses={404: {"model": ErrorResponse}},
)
async def get_user(
user_id: int = Path(..., gt=0),
db: AsyncSession = Depends(get_db),
current_user: User = Depends(get_current_user),
) -> UserResponse:
"""Recupera un utente specifico per ID."""
user = await user_service.get_by_id(db, user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
return UserResponse.model_validate(user)
```
## Convenzioni
- Usa Pydantic v2 per request/response models
- Dependency Injection per DB, auth, config
- Async per TUTTE le operazioni I/O
- Response models espliciti (mai dict generici)
- Validazione input con Field() e Path()
- HTTP status codes corretti (201 create, 204 delete, etc.)
## Error Handling
- HTTPException per errori HTTP standard
- Custom exception handlers per errori di dominio
- Formato errore standard: {"detail": "message", "code": "ERROR_CODE"}
Reguły dla React/Next.js: Kompletny przykład
Ekosystem React stale się rozwija: komponenty serwera, router aplikacji, React 19 z akcjami. Zasady muszą uwzględniać współczesne konwencje i unikać starszych wzorców.
---
description: Convenzioni React e Next.js per il progetto frontend
globs: ["**/*.tsx", "**/*.jsx"]
alwaysApply: false
---
# React / Next.js Conventions
## Framework
- Next.js 15+ con App Router
- React 19+ con Server Components di default
- TypeScript strict mode
- Styling: Tailwind CSS v4
## Componenti
- Server Components per default (niente "use client" se non necessario)
- Client Components SOLO per interattivita (click, form, state)
- Named export per i componenti (non default export)
- Props tipizzate con interface (non type alias)
## Pattern Preferiti
```tsx
// Server Component (default)
interface UserProfileProps {
readonly userId: string;
}
export async function UserProfile({ userId }: UserProfileProps) {
const user = await getUser(userId);
return (
<section className="p-4">
<h2>{user.name}</h2>
<UserActions user={user} />
</section>
);
}
```
## State Management
- React useState/useReducer per stato locale
- Zustand per stato globale client-side
- Server Actions per mutazioni (form, POST)
- NON usare useEffect per fetch dati (usa Server Components)
## Anti-pattern
- NO default export per componenti
- NO useEffect per data fetching
- NO index.tsx come nome componente
- NO prop drilling > 3 livelli (usa context o composition)
Reguły dla Backendu i REST API
API to umowa pomiędzy frontendem i backendem. Dobrze zdefiniowane reguły gwarantują spójność odpowiedzi, w obsłudze błędów i uwierzytelnianiu.
---
description: Convenzioni API REST per tutti gli endpoint
globs: ["**/controllers/**", "**/routes/**", "**/api/**"]
alwaysApply: false
---
# API REST Conventions
## URL Design
- Risorse in plurale: /users, /products, /orders
- Nesting massimo: 2 livelli (/users/{id}/orders)
- Verbi HTTP per le azioni: GET (read), POST (create), PUT (replace),
PATCH (update), DELETE (remove)
- Query params per filtering, sorting, pagination
## Response Format Standard
```json
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 150
}
}
```
## Error Response Format
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Email format is invalid",
"details": [
{ "field": "email", "message": "Must be a valid email address" }
]
}
}
```
## Status Codes
- 200: Success (GET, PUT, PATCH)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Bad Request (validazione fallita)
- 401: Unauthorized (non autenticato)
- 403: Forbidden (non autorizzato)
- 404: Not Found
- 409: Conflict (duplicato, stato inconsistente)
- 422: Unprocessable Entity (logica di business)
- 500: Internal Server Error (mai esporre dettagli)
## Paginazione
- Usa cursor-based pagination per dataset grandi
- Offset-based per casi semplici
- Includi sempre: page, limit, total, hasNext
Migracja ze starszego pliku .cursorrules
Jeśli używasz starego pliku .cursorrules, dobra wiadomość jest taka, że Cursor go zachowuje
kompatybilność wsteczna: starszy plik nadal działa. Jednak migruj do nowego systemu
.cursor/rules/ oferuje znaczne korzyści w zakresie organizacji i elastyczności.
Strategia migracji
Migracja nie musi być operacją typu „wszystko albo nic”. Możesz postępować stopniowo, wykonując poniższe kroki.
- Utwórz katalog
.cursor/rules/w swoim projekcie - Zidentyfikuj kategorie w swoim pliku
.cursorrules: konwencje ogólne, zasady języka, wzór testowania, styl odpowiedzi - Wyodrębnij każdą kategorię w pliku
.mdcoddzielone odpowiednim frontem - Przypisz odpowiednie typy: Zawsze dla uniwersalnych konwencji, automatycznie dołączane z kulkami w przypadku reguł specyficznych dla języka, Agent Prośba o wiedzę ekspercką
- Głowa że sztuczna inteligencja przestrzega nowych zasad w różnych kontekstach
- Usunąć plik
.cursorruleskiedy będziesz zadowolony z migracji
Konflikt pomiędzy .cursorrules i .cursor/rules/
Jeśli oba są obecne, Cursor załaduje oba pliki .cursorrules że pliki w
.cursor/rules/. Może to powodować powielanie lub sprzeczne instrukcje. Podczas
migracji, skomentuj sekcje w .cursorrules podczas wyodrębniania ich do nowych plików
.mdci usuń starszy plik dopiero po zakończeniu migracji.
Zaawansowane strategie reguł
Zaawansowane wzory globu
Wzory globalne są najpotężniejszym narzędziem do precyzyjnego kierowania regułami. Oto wzory bardziej przydatne w scenariuszach ze świata rzeczywistego.
# File specifici per tipo
**/*.component.ts # Tutti i componenti Angular
**/*.service.ts # Tutti i servizi Angular
**/*.spec.ts # Tutti i file di test
**/*.stories.tsx # Tutti gli Storybook stories
# Directory specifiche
src/app/core/** # Tutto nella directory core
src/app/features/**/*.ts # Solo TypeScript nelle features
# Combinazioni multiple
**/*.{ts,tsx} # TypeScript e TypeScript React
**/{api,routes}/**/*.py # File Python in api/ o routes/
# Esclusioni con negazione (in alcuni contesti)
!**/*.spec.ts # Escludi i file di test
!**/node_modules/** # Escludi node_modules
Reguły warunkowe dotyczące typu pliku
Skuteczną strategią jest tworzenie reguł aktywowanych na podstawie kontekstu pliku. Na przykład możesz mieć inne reguły dla plików migracji baz danych niż dla plików logiki aplikacji, mimo że oba są plikami Pythona.
---
description: Regole specifiche per file di migrazione Alembic
globs: ["**/alembic/versions/**/*.py", "**/migrations/**/*.py"]
alwaysApply: false
---
# Migrazioni Database (Alembic)
## Struttura
- Ogni migrazione deve avere upgrade() e downgrade()
- Commenta SEMPRE la motivazione della migrazione
- Usa batch operations per SQLite compatibility
## Naming
- Formato: YYYYMMDD_HHMM_descrizione_breve.py
- Descrizione in snake_case, max 50 caratteri
## Safety
- Mai DROP TABLE senza backup esplicito
- Mai ALTER COLUMN che rimuove dati senza migrazione dati
- Testa SEMPRE downgrade() prima di committare
Możliwość układania reguł: reguły, które się uzupełniają
Reguły nie są izolowane: są łączone w kontekście sztucznej inteligencji. Skuteczna strategia i zasady projektowania które uzupełniają się, tworząc spójny system instrukcji.
Na przykład możesz mieć regułę Zawsze dla konwencji ogólnych i regułę Dołączane automatycznie dla
specyfikacje językowe i reguła Agent Request dla wzorców architektonicznych. Kiedy pracujesz
w komponencie Angular AI otrzyma: ogólne konwencje (Zawsze) + reguły Angular
(Automatycznie dołączone z glob **/*.component.ts) + ewentualnie zasady architektoniczne
(jeśli agent uzna je za istotne dla zadania).
Generuj reguły automatycznie
Kursor zawiera wbudowane polecenie umożliwiające generowanie reguł na podstawie istniejącej bazy kodu:
/Generate Cursor Rules. To polecenie analizuje Twój projekt, identyfikuje wzorce
powtarzające się i generuje początkowy zestaw reguł, które uwzględniają już używane konwencje.
Jak korzystać z polecenia
- Otwórz panel czatu kursora (
Cmd+L/Ctrl+L) - Typ
/Generate Cursor Rules - Sztuczna inteligencja przeanalizuje Twój kod i zaproponuje zestaw reguł
- Przejrzyj, zmodyfikuj i zapisz proponowane reguły w katalogu
.cursor/rules/
Wskazówka: Zacznij od istniejącej bazy kodu
Polecenie /Generate Cursor Rules i szczególnie przydatne w przypadku istniejących projektów, gdzie
konwencje są ukryte w kodzie, ale nie są udokumentowane. Sztuczna inteligencja zidentyfikuje wzorce takie jak
strukturę komponentów, nazewnictwo, wzorce obsługi błędów i przekształci je w jawne reguły.
Potraktuj wynik jako punkt wyjścia do udoskonalenia, a nie jako ostateczną konfigurację.
Wspomagane generowanie z podpowiedzią
Możesz także tworzyć reguły ręcznie, prosząc o pomoc sztuczną inteligencję Cursora. Proszę o przykładowy plik który reprezentuje Twój idealny styl i poproś sztuczną inteligencję o wyodrębnienie konwencji.
Analizza il file user.service.ts e genera un file .mdc per
.cursor/rules/ che catturi tutte le convenzioni che vedi:
- Pattern di gestione errori
- Struttura dei metodi
- Uso di tipi e interfacce
- Pattern di dependency injection
- Formato dei commenti e della documentazione
Il file deve essere Auto Attached per tutti i file *.service.ts
Przepływ pracy zespołu: wspólne zasady
Jedną z najważniejszych zalet zasad projektu jest możliwość udostępniania ich za pośrednictwem gita. Otwiera to ogromne możliwości dostosowania zespołu i wdrażania nowych programistów.
Strategia udostępniania
Katalog .cursor/rules/ powinien zostać zapisany w repozytorium jako
.editorconfig, .eslintrc o tsconfig.json. Te zasady
stają się częścią definicji projektu i zapewniają, że każdy członek zespołu, kiedy
użyj Kursora, otrzymuj te same instrukcje AI.
.cursor/
rules/
# Always Rules - Convenzioni universali
01-project-overview.mdc # Descrizione del progetto e stack
02-coding-standards.mdc # Standard di codice condivisi
03-git-workflow.mdc # Convenzioni git e PR
# Auto Attached - Per linguaggio/framework
angular-components.mdc # Regole componenti Angular
angular-services.mdc # Regole servizi Angular
angular-testing.mdc # Regole test Angular
css-conventions.mdc # Regole CSS/SCSS
api-endpoints.mdc # Regole API REST
# Agent Requested - Conoscenze specialistiche
database-schema.mdc # Schema e migrazioni DB
deployment-pipeline.mdc # Pipeline CI/CD
security-guidelines.mdc # Linee guida sicurezza
# Manual - Template e snippet
new-feature-template.mdc # Template nuova feature
bug-fix-checklist.mdc # Checklist per bug fix
code-review-criteria.mdc # Criteri per code review
Wdrożenie z zasadami
Zasady projektu mogą radykalnie przyspieszyć wdrażanie nowych programistów. Nowy członek zespołu, który sklonuje repozytorium i zacznie korzystać z Kursora, natychmiast będzie miał dostęp do nich wszystkich konwencje projektowe poprzez sztuczną inteligencję. Nie musi czytać 50-stronicowego dokumentu wprowadzającego: za każdym razem, gdy napiszesz kod, sztuczna inteligencja automatycznie zastosuje odpowiednie konwencje.
Korzyści ze wspólnych zasad
- Konsystencja: Niezależnie od tego cały kod wygenerowany przez sztuczną inteligencję podlega tym samym standardom przez dewelopera
- Szybkie wdrożenie: Nowi programiści tworzą zgodny kod od pierwszego dnia
- Redukcja przeglądu kodu: Mniej komentarzy na temat stylu i konwencji, więcej skupienia się na logice
- Dokumentacja na żywo: Reguły to wykonywalna dokumentacja, która jest aktualizowana wraz z projektem
- Kontrolowana ewolucja: Zmiany w konwencjach podlegają przeglądowi git jak wszystko inne zmienić
Porównanie z CLAUDE.md i innymi systemami
System reguł kursora nie jest jedynym sposobem na edukację sztucznej inteligencji na temat kontekstu projektu.
Claude Code używa tego pliku CLAUDE.md, GitHub Copilot wprowadził
.github/copilot-instructions.md i windsurfingu .windsurfrules.
Zobaczmy, jak się porównują.
Porównanie systemów konfiguracji AI
| Charakterystyczny | Reguły kursora | CLAUDE.md | Instrukcje drugiego pilota |
|---|---|---|---|
| Wiele plików | Tak (.cursor/rules/) | Tak (katalog .claude/) | Pojedynczy plik |
| Rodzaje aktywacji | 4 typy (zawsze, automatycznie, agent, ręcznie) | Zawsze aktywny + pamięć | Zawsze aktywny |
| Wzory globusów | Tak (kulki frontmaterii) | No | No |
| Udostępnianie Gita | Si | Si | Si |
| Reguły na poziomie użytkownika | Tak (Ustawienia) | Tak (~/.claude/) | Ograniczony |
| Format | .mdc (treść YAML + MD) | .md (czysty Markdown) | .md (czysty Markdown) |
| Automatyczne generowanie | Tak (/Generuj reguły kursora) | Nie (ale opcja /init jest dostępna) | No |
Najważniejszą różnicą jest system aktywacja warunkowa Kursora.
Podczas gdy instrukcje CLAUDE.md i Copilot są zawsze aktywne (zużywają kontekst w każdej interakcji),
Kursor umożliwia aktywację reguł tylko wtedy, gdy są one istotne. W projekcie full-stack z frontendem
Angular, backend Pythona i infrastruktura Terraform, reguły Angular zostaną uwzględnione tylko wtedy, gdy
pracować na plikach .component.ts, oszczędzając cenny kontekst dla odpowiednich instrukcji.
Kolejną wyjątkową zaletą Cursora jest typ Prośba o agenta. AI może decydować autonomicznie, które reguły należy konsultować w oparciu o zadanie, tworząc system wiedzy na żądanie, który skalować bez ograniczeń, bez niepotrzebnego zużywania kontekstu.
Kompletne przykłady praktyczne
W tej sekcji zebraliśmy zbiór gotowych do użycia reguł dla typowych scenariuszy.
Każdy przykład jest kompletny i można go skopiować bezpośrednio do katalogu .cursor/rules/.
Reguła: styl CSS z BEM i właściwościami niestandardowymi
---
description: Convenzioni CSS con BEM naming e custom properties
globs: ["**/*.css", "**/*.scss"]
alwaysApply: false
---
# CSS Conventions
## Naming: BEM (Block-Element-Modifier)
- Block: .card, .nav, .form
- Element: .card__title, .card__body, .nav__link
- Modifier: .card--featured, .nav__link--active
## Custom Properties (Design Tokens)
- Colori: --color-primary, --color-surface, --color-text
- Spacing: --space-xs (4px), --space-sm (8px), --space-md (16px)
- Typography: --font-heading, --font-body
- Breakpoints: --bp-mobile (768px), --bp-tablet (1024px)
## Regole
- Mobile-first: min-width per media queries
- No !important (mai, salvo utility override)
- No nesting > 3 livelli in SCSS
- Usa logical properties (margin-inline, padding-block)
- Preferisci Grid e Flexbox (no float)
Reguła: Docker i konteneryzacja
---
description: Regole per Dockerfile e docker-compose
globs: ["**/Dockerfile*", "**/docker-compose*.yml", "**/.dockerignore"]
alwaysApply: false
---
# Docker Conventions
## Dockerfile
- Multi-stage build SEMPRE (build + runtime)
- Immagine base: usa versioni specifiche (node:20-alpine, non node:latest)
- USER non-root: crea e usa un utente applicativo
- COPY selettivo: prima package*.json, poi npm ci, poi il resto
- .dockerignore: escludi node_modules, .git, test, docs
## Esempio Struttura
```dockerfile
# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build
# Stage 2: Runtime
FROM node:20-alpine AS runtime
RUN addgroup -S app && adduser -S app -G app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER app
EXPOSE 3000
CMD ["node", "dist/main.js"]
```
## docker-compose
- Usa version "3.8" o superiore
- Health checks per tutti i servizi
- Named volumes per dati persistenti
- Environment variables via .env file (non inline)
Reguła: Bezpieczeństwo i uwierzytelnianie
---
description: Linee guida di sicurezza per autenticazione, autorizzazione e protezione dati
alwaysApply: false
---
# Security Guidelines
## Autenticazione
- JWT con refresh token rotation
- Access token: breve durata (15 min)
- Refresh token: durata media (7 giorni), one-time use
- Password: bcrypt con salt rounds >= 12
- NESSUN segreto hardcoded nel codice
## Autorizzazione
- RBAC (Role-Based Access Control) come base
- Verifica permessi a livello di controller E service
- Principio del minimo privilegio: concedi solo ciò che serve
- Audit log per operazioni sensibili
## Input Validation
- Valida TUTTI gli input a livello di boundary (controller)
- Sanitizza HTML per prevenire XSS
- Query parametrizzate SEMPRE (mai concatenazione SQL)
- Rate limiting su tutti gli endpoint pubblici
## Headers di Sicurezza
- Content-Security-Policy
- X-Content-Type-Options: nosniff
- Strict-Transport-Security
- X-Frame-Options: DENY
Reguła: Obsługa błędów międzyjęzykowych
---
description: Pattern di gestione errori consistente tra frontend e backend
alwaysApply: true
---
# Error Handling Pattern
## Principi
- Non ingoiare MAI un errore silenziosamente
- Log dettagliato server-side, messaggio user-friendly client-side
- Errori previsti: gestione esplicita con recovery
- Errori imprevisti: catch globale + logging + notifica
## Frontend (Angular/React)
- HttpClient: gestisci errori con catchError/try-catch
- Mostra toast/snackbar per errori utente
- Retry automatico per errori di rete (max 3 tentativi)
- Fallback UI per stati di errore (ErrorBoundary/error template)
## Backend (Node/Python)
- Custom exception classes per errori di dominio
- Global exception handler come middleware
- Structured logging: livello, timestamp, correlation-id, stack trace
- Non esporre MAI stack trace o dettagli interni al client
## Formato Standard
```
Log: [LEVEL] [TIMESTAMP] [CORRELATION-ID] [SERVICE] Message {context}
API: { "success": false, "error": { "code": "XXX", "message": "..." } }
```
Najlepsze praktyki i typowe błędy
Błędy, których należy unikać
- Za dużo Zawsze: Jeśli wszystkie twoje reguły to Zawsze, marnujesz kontekst. Sztuczna inteligencja otrzymuje tysiące tokenów instrukcji, nawet jeśli poprosisz o zmianę nazwy zmiennej
- Zasady zbyt niejasne: „Napisz dobry kod” nie pomaga sztucznej inteligencji. Bądź konkretny: „Funkcje z maksymalnie 4 parametrami, każdy z jawnym typem”
- Sprzeczne zasady: Jeśli jedna reguła mówi „użyj klas”, a inna mówi „użyj funkcji”, sztuczna inteligencja jest zdezorientowana. Przejrzyj zasady spójności
- Brak przykładów: Zasady bez konkretnych przykładów są przestrzegane w pewien sposób niespójne. Zawsze dołączaj co najmniej jeden pozytywny i jeden negatywny przykład
- Nie aktualizuj zasad: Zasady muszą ewoluować wraz z projektem. Jeśli migrujesz od Angular 17 do 19, zaktualizuj reguły, aby odzwierciedlić nowe wzorce
Lista kontrolna skutecznej konfiguracji
- Zdefiniuj reguły 1-3 Zawsze z uniwersalnymi konwencjami projektowymi
- Utwórz reguły dołączane automatycznie dla każdego języka/frameworka w projekcie
- Dodaj reguły wymagane przez agenta w celu uzyskania wiedzy eksperckiej (baza danych, wdrożenie, bezpieczeństwo)
- Przygotuj reguły ręczne dla powtarzalnych szablonów i przepływów pracy
- Zaangażuj wszystko
.cursor/rules/i przekaż to zespołowi - Przeglądaj i aktualizuj reguły w każdym sprincie lub wydaniu
- USA
/Generate Cursor Rulesjako punkt wyjścia dla nowych projektów
Wnioski
System reguł Cursora stanowi jakościowy skok w sposobie działania programistów wchodzić w interakcję z AI. Nie chodzi tylko o wydawanie poleceń chatbotowi: chodzi o to kodyfikować konwencje zespołu do formatu zrozumiałego i zastosowanego przez sztuczną inteligencję automatycznie.
Cztery typy reguł (Zawsze, Dołączane automatycznie, Żądanie agenta, Ręczne) oferują poziom szczegółowość, której nie zapewnia obecnie żadne inne narzędzie AI. Możliwość aktywacji reguł warunkowo na podstawie typu pliku, w połączeniu z kierowaniem na żądanie agenta, tworzy plik dynamiczny system wiedzy, który skaluje się wraz ze złożonością projektu bez pogorszenia Wydajność sztucznej inteligencji.
Najważniejsza wskazówka? Zacznij teraz, zacznij prosto. Utwórz regułę Zawsze z 10 najważniejszymi konwencjami swojego projektu, dodaj regułę automatycznego dołączania dla główny język i stamtąd iteruj. Nie potrzebujesz idealnej konfiguracji od pierwszego dnia: zasady ewoluują wraz z projektem, podobnie jak kod.
W następnym artykule z tej serii omówimyTryb agenta: jak delegować zadania kompleksów do sztucznej inteligencji Cursora, od refaktoryzacji całych funkcji po generowanie zestawów testów kompletny. Reguły, które skonfigurowaliśmy w tym artykule, staną się podstawą agent zbuduje swoją pracę.
Dodatkowe zasoby
- Oficjalna dokumentacja kursora: https://docs.cursor.com/context/rules-for-ai
- Przykładowe repozytorium: github.com/cursor-rules-examples
- Wspólnota: forum.cursor.com, aby udostępniać i odkrywać zasady
- Następny artykuł: Tryb agenta — edytuj bazę kodu za pomocą polecenia