02 - Reguli cursor: Configurarea AI pentru proiectul dvs
Fiecare dezvoltator are propriile convenții, modele arhitecturale și standarde de calitate. Când lucrezi cu un coleg uman, aceste reguli sunt comunicate prin revizuirea codului, programarea perechilor și documentația. Dar cum poți comunica aceleași așteptări unui agent AI? Răspunsul cursorului și Sistemul de reguli: un mecanism puternic și flexibil care vă permite să instruiți AI cum trebuie să genereze, să modifice și să argumenteze despre codul proiectului tău.
În acest articol vom explora fiecare aspect al sistemului Cursor Rules: din evoluția sa istorică la strategii avansate de configurare, trecând prin exemple practice pentru backend-uri Angular, React, Python, API si multe altele. În cele din urmă veți avea toate instrumentele pentru a transforma Cursor AI într-un colaborator care respectați convențiile echipei dvs. de parcă le-ar fi cunoscut dintotdeauna.
Ce veți învăța în acest articol
- Evoluția sistemului de Reguli: de la
.cursorrulesla director.cursor/rules/ - Cele patru tipuri de reguli: Întotdeauna, Atașat automat, Solicitat de agent și Manual
- Diferența dintre Regulile utilizatorului și Regulile proiectului și când să utilizați fiecare tip
- Cum să scrieți reguli eficiente cu frontmatter, globuri și descrieri
- Exemple complete pentru Angular, React, Python, FastAPI și REST API
- Strategii avansate: reguli condiționale, moștenire de reguli, generare automată
- Flux de lucru în echipă: partajare prin git, onboarding și convenții partajate
- Comparație cu CLAUDE.md și alte sisteme de instrucțiuni AI
Prezentare generală a seriei Cursor IDE și AI-Native Development
| # | Articol | Concentrează-te |
|---|---|---|
| 1 | Ghid complet al cursorului IDE | Prezentare generală completă |
| 2 | Sunteți aici - Regulile cursorului | Configurare personalizată AI |
| 3 | Modul agent | Automatizare avansată |
| 4 | Modul Plan | Planificare asistată |
| 5 | Cârlige și MCP | Extensibilitate și integrări |
| 6 | Fluxuri de lucru profesionale | Cele mai bune practici de producție |
Evoluția sistemului de reguli în Cursor
Sistemul de reguli ale cursorului a trecut printr-o evoluție semnificativă de la introducerea sa inițială. Înțelegerea acestei istorii este fundamentală pentru a înțelege de ce sistemul actual este structurat într-un anumit fel și pentru a evita confuzia între diferitele generații de configurație.
Prima generație: fișierul .cursorrules
În prima implementare, Cursor a acceptat un singur fișier .cursorrules în rădăcina proiectului.
Acest fișier conținea instrucțiuni de text liber care au fost injectate în contextul fiecărei interacțiuni AI.
A fost simplu și direct: scrieți-vă regulile într-un fișier, iar AI le va urma.
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
Această abordare a avut o limitare evidentă: toate regulile au ajuns într-un singur fișier monolitic.
Într-un proiect complex cu front-end Angular, backend Python, infrastructură Docker și conductă CI/CD,
dosarul .cursorrules a devenit rapid uriaș și greu de gestionat. De asemenea, toate regulile
au fost întotdeauna trimise către AI, chiar și atunci când nu erau relevante pentru contextul actual.
A doua generație: Reguli de proiect cu .cursor/rules/
Pentru a rezolva aceste limitări, Cursor a introdus Regulile proiectului bazat pe
director .cursor/rules/. Această nouă abordare vă permite să organizați regulile în fișiere separate,
cu metadate structurate și activare condiționată bazată pe modele de fișiere.
Directorul .cursor/rules/ și menit să fie angajat în depozitul git, astfel încât toată lumea
membrii echipei partajează automat aceleași instrucțiuni AI. Fiecare fișier din director este un fișier
.mdc (Markdown cu context) care conține un frontmatter YAML și corpul declarațiilor din Markdown.
De ce .mdc și nu .md?
Formatul .mdc (Markdown with Context) este o extensie proprietară Cursor care adaugă
un frontmatter standard structurat Markdown. Frontmatter-ul definește metadatele ca descriere a
regula, modelele glob pentru activare automată și steag alwaysApply. Cursorul interpretează
aceste metadate pentru a decide când și cum se aplică fiecare regulă.
Cele patru tipuri de regulă
Sistemul modern Cursor definește patru moduri de activare a regulilor, fiecare proiectat pentru un caz de utilizare specific. Alegerea tipului potrivit este crucială pentru a echilibra relevanța instrucțiunilor cu consumul de context AI.
1. Întotdeauna reguli
Regulile tipului Întotdeauna sunt incluse în fiecare interacțiune cu AI, indiferent din dosarul la care lucrezi sau din cererea pe care o faci. Sunt ideale pentru convențiile universale ale proiect care trebuie întotdeauna respectat.
---
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
Atenție la consumul de context
Regulile vin mereu Întotdeauna trimis către AI, consumând jetoane de context în fiecare interacțiune. Utilizați acest tip numai pentru reguli cu adevărat universale. Dacă o regulă se aplică numai anumitor fișiere sau situații, preferați Auto Attached sau Agent Requested pentru a optimiza utilizarea contextului.
2. Reguli atașate automat
Regulile Atașat automat sunt activate automat atunci când lucrați la fișiere care se potrivesc la modele glob specifice. Sunt perfecte pentru reguli specifice unui limbaj, cadru sau tip de fișier.
---
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)
Câmpul globs acceptă modele glob standard. Puteți folosi metacaractere simple, cum ar fi *.ts
sau modele complexe precum {**/*.service.ts,**/*.guard.ts}. Când deschideți un fișier
care se potrivește cu modelul, regula este inclusă automat în contextul AI.
3. Reguli solicitate de agent
Regulile Agent solicitat sunt vizibili AI prin descrierea lor, dar vin incluse în context numai atunci când agentul decide că sunt relevante pentru sarcina curentă. Acest tip și ideal pentru regulile de specialitate care nu sunt întotdeauna necesare, dar pe care AI trebuie să le poată consulta atunci când este necesar.
---
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
În acest exemplu, regula nu are globs si are alwaysApply: false. AI-ul va vedea doar
descriere „Reguli pentru crearea și gestionarea migrărilor de baze de date cu Prisma” și va decide independent
dacă să includă întregul conținut al regulii atunci când sarcina implică operațiuni de bază de date. Această abordare
și deosebit de eficient: AI are acces la un catalog de cunoștințe de specialitate fără a pierde contextul
când nu sunt necesare.
4. Reguli manuale
Regulile Manual nu sunt niciodată incluse automat. Ele trebuie menționate în mod explicit
de către dezvoltator folosind referința @ruleName în prompt. Sunt utile pentru șabloane,
fragmente sau instrucțiuni pe care doriți să le utilizați numai în situații specifice.
---
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
Pentru a utiliza această regulă, dezvoltatorul va scrie ceva de genul: „Creați o nouă funcție pentru profilul dvs. de utilizator urmând @new-feature-template”. AI va include conținutul regulii în context și va genera codul conform șablonului.
Rezumatul tipurilor de reguli
| Tip | Activare | Caz de utilizare | Contextul de consum |
|---|---|---|---|
| Întotdeauna | Întotdeauna inclus | Convenții universale de proiectare | Ridicat (întotdeauna activ) |
| Atașat automat | Model Glob în dosar | Reguli specifice limbii/cadru | Mediu (numai fișierele relevante) |
| Agent solicitat | AI decide pe baza descrierii | Cunoștințe de specialitate la cerere | Scăzut (doar când este necesar) |
| Manual | Apel explicit cu @name | Șabloane, fragmente, instrucțiuni rare | Minimum (doar la cerere) |
Reguli utilizator vs. Reguli de proiect
Cursorul distinge între două niveluri de configurare: le Regulile utilizatorului care se aplică tuturor proiectele tale și Regulile proiectului care sunt specifice unui singur depozit. Înțelegerea când să utilizați una sau alta este esențială pentru o configurare eficientă.
Reguli utilizator: Preferințele tale globale
Regulile utilizatorului sunt configurate în Cursor Settings > General > Rules for AI. Aceste reguli
ele vă definesc preferințele personale care rămân constante indiferent de proiectul la care lucrați.
Nu sunt fișiere din depozit: ele trăiesc în configurația locală a Cursorului.
## 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
Regulile proiectului: Convenții de depozit
Regulile proiectului se află în director .cursor/rules/ a proiectului și sunt angajați
în depozitul git. Aceasta înseamnă că fiecare membru al echipei care clonează depozitul va avea automat
aceleași instrucțiuni AI, asigurând consistența în generarea codului.
Regulile utilizatorului vs Regulile proiectului: Când să folosiți Ce
| astept | Regulile utilizatorului | Regulile proiectului |
|---|---|---|
| Mături | Toate proiectele | Un singur depozit |
| Poziţie | Setări cursor | .cursor/reguli/*.mdc |
| Partajarea | Numai local | Prin git (echipă) |
| Prioritate | Bază (înlocuită de proiect) | Ridicată (specifică contextului) |
| Exemplu | Limbajul, stilul de răspuns, principiile generale | Cadru, arhitectură, modele specifice |
La prioritate Funcționează intuitiv: Regulile proiectului au prioritate față de Regulile utilizatorului când există un conflict. Dacă regulile dvs. de utilizator spun „utilizați clase”, dar Regulile de proiect spun „utilizați funcții”, AI va urma regulile proiectului. Acest lucru permite fiecărui proiect să aibă propriile convenții fără trebuind să schimbe preferințele globale.
Anatomia unei reguli eficiente
Scrierea unei reguli pe care AI o poate respecta corect necesită atenție la structură și claritate și simplitatea instrucțiunilor. O regulă bine scrisă este diferența dintre un AI care generează cod generic și o IA care generează cod perfect aliniat cu standardele dumneavoastră.
Structura fișierului .mdc
Fiecare dosar .mdc și compus din două părți: cel problema principală YAML delimitat de
--- iar cel corp în Markdown cu instrucțiuni reale.
---
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
Cele mai bune practici pentru scrierea unor reguli eficiente
După ce am configurat sute de reguli în proiecte reale, am identificat cinci principii fundamentale care determină eficacitatea unei reguli.
1. Fii specific, nu generic. O regulă care spune „scrie cod curat” este inutilă. O regulă care spune „fiecare funcție trebuie să aibă maximum 4 parametri, fiecare cu un tip explicit și JSDoc” și operabil de AI.
2. Arată, nu spune doar. Includeți întotdeauna cel puțin un exemplu concret de cod care respecta regula. AI învață mai bine din exemple decât din descrieri abstracte.
3. Definiți, de asemenea, anti-modeluri. Spuneți în mod explicit ce NU trebuie să faceți. Dacă regula spune „utilizați semnale”, dar nu spune „nu folosiți BehaviorSubject”, AI ar putea amesteca cele două abordări.
4. O regulă, o temă. Nu creați fișiere monolitice care acoperă totul. Împărțiți regulile pe zonă: o regulă pentru testare, una pentru CSS, una pentru arhitectură. Acest lucru facilitează întreținerea si permite activarea selectiva prin globuri.
5. Scrieți descrierea având în vedere AI. Câmpul description în prim-plan
și ce citește AI pentru a decide dacă să includă o regulă solicitată de agent. Trebuie să fie concis dar
suficient de informativ pentru a permite AI să înțeleagă când regula este relevantă.
Reguli pentru Angular: Exemplu complet
Angular este un cadru cu convenții precise și un ecosistem în evoluție rapidă. Cu trecerea la componentele independente, semnalele și noua sintaxă a fluxului de control, este esențial ca AI să genereze cod care urmează cele mai bune practici moderne. Iată un set complet de reguli pentru un proiect 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%
Reguli pentru Python: Exemplu complet
Python este un limbaj cu o filozofie precisă (Zenul lui Python) și convenții consolidate (PEP 8). Regulile pentru Python trebuie să captureze aceste convenții și să adauge specificul proiectului.
---
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"}
Reguli pentru React/Next.js: Exemplu complet
Ecosistemul React este în continuă evoluție: Componente Server, App Router, React 19 cu Acțiuni. Regulile trebuie să surprindă convențiile moderne și să evite modelele moștenite.
---
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)
Reguli pentru backend și API-ul REST
API-urile sunt contractul dintre frontend și backend. Reguli bine definite garantează coerența răspunsurilor, în tratarea erorilor și autentificare.
---
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
Migrare din fișierul .cursorrules moștenit
Dacă utilizați fișierul vechi .cursorrules, vestea bună este că Cursor îl păstrează
compatibilitate inversă: fișierul moștenit continuă să funcționeze. Totuși, migrați la noul sistem
.cursor/rules/ oferă avantaje semnificative în ceea ce privește organizarea și flexibilitatea.
Strategia de migrație
Migrația nu trebuie să fie o operațiune de totul sau nimic. Puteți continua treptat urmând acești pași.
- Creați directorul
.cursor/rules/în proiectul tău - Identificați categoriile în dosarul dvs
.cursorrules: convenții generale, reguli pentru limbaj, model de testare, stil de răspuns - Extrage fiecare categorie într-un dosar
.mdcseparate cu materialul frontal corespunzător - Atribuiți tipurile corecte: Întotdeauna pentru convenții universale, atașat automat cu globuri pentru reguli specifice limbii, agent solicitat pentru cunoștințe de specialitate
- Cap că AI respectă noile reguli în diferite contexte
- Elimina dosarul
.cursorrulescând ești mulțumit de migrare
Conflict între .cursorrules și .cursor/rules/
Dacă ambele sunt prezente, Cursor va încărca ambele fișiere .cursorrules că fișierele în
.cursor/rules/. Acest lucru poate cauza instrucțiuni duplicate sau contradictorii. În timpul
migrare, comentați secțiunile din .cursorrules pe măsură ce le extrageți în fișiere noi
.mdcși eliminați fișierul moștenit numai când migrarea este finalizată.
Strategii avansate de reguli
Modele Glob avansate
Modelele glob sunt cel mai puternic instrument pentru direcționarea precisă a regulilor. Iată modelele mai util pentru scenarii din lumea reală.
# 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
Reguli condiționale pentru tipul de fișier
O strategie eficientă este de a crea reguli care sunt activate în funcție de contextul fișierului. De exemplu, puteți avea reguli diferite pentru fișierele de migrare a bazei de date decât pentru fișierele logice ale aplicației, chiar dacă ambele sunt fișiere Python.
---
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
Componabilitate a regulilor: Reguli care se completează reciproc
Regulile nu sunt izolate: ele sunt combinate în contextul AI. O strategie eficientă și reguli de proiectare care se completează reciproc, creând un sistem coerent de instrucțiuni.
De exemplu, puteți avea o regulă Întotdeauna pentru convențiile generale, o regulă atașată automat pentru
specificații de limbă și o regulă solicitată de agent pentru modelele arhitecturale. Când lucrezi
pe o componentă Angular, AI va primi: convenții generale (Întotdeauna) + reguli unghiulare
(Atașat automat de la glob **/*.component.ts) + eventual regulile arhitecturale
(dacă agentul le consideră relevante pentru sarcină).
Generați reguli automat
Cursorul include o comandă încorporată pentru a genera reguli din baza de cod existentă:
/Generate Cursor Rules. Această comandă analizează proiectul dvs., identifică modele
recurent și generează un set inițial de reguli care surprind convențiile deja utilizate.
Cum să utilizați comanda
- Deschideți panoul de chat al cursorului (
Cmd+L/Ctrl+L) - Tip
/Generate Cursor Rules - AI va analiza baza de cod și va propune un set de reguli
- Examinați, modificați și salvați regulile propuse în director
.cursor/rules/
Sfat: Începeți de la baza de cod existentă
Comanda /Generate Cursor Rules și mai ales utilă pentru proiectele existente unde
convențiile sunt implicite în cod, dar nu sunt documentate. AI va identifica modele precum
structura componentelor, denumirea, modelele de tratare a erorilor și le va transforma în reguli explicite.
Considerați rezultatul ca un punct de plecare care trebuie rafinat, nu ca o configurație definitivă.
Generare asistată cu prompt
De asemenea, puteți crea reguli manual, solicitând AI-ului Cursor să vă ajute. Vă rugăm să furnizați un fișier exemplu care reprezintă stilul tău ideal și cere AI să extragă convențiile.
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
Flux de lucru în echipă: reguli comune
Unul dintre cele mai semnificative avantaje ale Regulilor de proiect este capacitatea de a le partaja prin git. Acest lucru deschide posibilități uriașe pentru alinierea echipelor și integrarea de noi dezvoltatori.
Strategie de partajare
Directorul .cursor/rules/ ar trebui să fie trimis în depozit ca
.editorconfig, .eslintrc o tsconfig.json. Aceste reguli
acestea devin parte din definirea proiectului și se asigură că fiecare membru al echipei, când
utilizați Cursorul, primiți aceleași instrucțiuni 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
Integrarea cu reguli
Regulile de proiect pot accelera dramatic integrarea noilor dezvoltatori. Unul nou membrul echipei care clonează depozitul și începe să folosească Cursor va avea imediat acces la toate convențiile de proiect prin AI. Nu trebuie să citească un document de înscriere de 50 de pagini: ori de câte ori scrieți cod, AI va aplica automat convențiile corecte.
Beneficiile regulilor partajate
- Consecvență: Tot codul generat de AI urmează aceleași standarde, indiferent de către dezvoltator
- Incorporare rapidă: Dezvoltatorii noi produc cod compatibil din prima zi
- Reducerea revizuirii codului: Mai puține comentarii despre stil și convenții, mai mult accent pe logică
- Documentație live: Regulile sunt documentație executabilă care se actualizează odată cu proiectul
- Evolutie controlata: Modificările aduse convențiilor trec prin git review ca orice altceva schimbare
Comparație cu CLAUDE.md și alte sisteme
Sistemul de reguli ale cursorului nu este singura modalitate de a educa un AI despre contextul proiectului.
Claude Code folosește fișierul CLAUDE.md, GitHub Copilot a introdus
.github/copilot-instructions.md și utilizări Windsurf .windsurfrules.
Să vedem cum se compară.
Comparația sistemelor de configurare AI
| Caracteristică | Regulile cursorului | CLAUDE.md | Instrucțiuni pentru copilot |
|---|---|---|---|
| Mai multe fișiere | Da (.cursor/rules/) | Da (directorul .claude/) | Un singur dosar |
| Tipuri de activare | 4 tipuri (Întotdeauna, Auto, Agent, Manual) | Întotdeauna activ + memorie | Întotdeauna activ |
| Modele de glob | Da (globurile de frontmatter) | No | No |
| Partajarea Git | Si | Si | Si |
| Reguli la nivel de utilizator | Da (Setări) | Da (~/.claude/) | Limitat |
| Format | .mdc (YAML frontmatter + MD) | .md (pură Markdown) | .md (pură Markdown) |
| Generare automată | Da (/Generează reguli cursor) | Nu (dar /init disponibil) | No |
Cea mai semnificativă diferență este sistemul activare condiționată de Cursor.
În timp ce instrucțiunile CLAUDE.md și Copilot sunt întotdeauna active (consumând context în fiecare interacțiune),
Cursorul vă permite să activați regulile numai atunci când acestea sunt relevante. Într-un proiect full-stack cu frontend
Angular, backend Python și infrastructură Terraform, regulile Angular vor fi incluse numai atunci când
lucra la dosare .component.ts, salvând context valoros pentru instrucțiunile relevante.
Un alt avantaj unic al Cursorului este tipul Agent solicitat. AI poate decide în mod autonom ce reguli să se consulte în funcție de sarcină, creând un sistem de cunoștințe la cerere care scala fără limite fără a consuma contextul în mod inutil.
Exemple practice complete
În această secțiune colectăm o colecție de reguli gata de utilizare pentru scenarii comune.
Fiecare exemplu este complet și poate fi copiat direct în directorul dvs .cursor/rules/.
Regula: stil CSS cu BEM și proprietăți personalizate
---
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)
Regula: Docker și Containerizare
---
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)
Regula: Securitate și autentificare
---
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
Regula: gestionarea erorilor în mai multe limbi
---
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": "..." } }
```
Cele mai bune practici și greșeli comune
Greșeli de evitat
- Prea multe Întotdeauna: Dacă toate regulile tale sunt Întotdeauna, irosești contextul. AI primește mii de jetoane de instrucțiuni chiar și atunci când solicitați redenumirea unei variabile
- Reguli prea vagi: „Scrieți un cod bun” nu ajută AI. Fii specific: „Funcții cu până la 4 parametri, fiecare cu un tip explicit”
- Reguli contradictorii: Dacă o regulă spune „utilizați clase” și alta spune „utilizați funcții”, AI-ul devine confuz. Examinați regulile pentru consecvență
- Lipsa exemplelor: Regulile fără exemple concrete sunt respectate într-un mod inconsecventă. Includeți întotdeauna cel puțin un exemplu pozitiv și unul negativ
- Nu actualizați regulile: Regulile trebuie să evolueze odată cu proiectul. Dacă migrezi de la Angular 17 la 19, actualizați regulile pentru a reflecta noile modele
Lista de verificare pentru o configurație eficientă
- Definiți 1-3 Întotdeauna reguli cu convenții universale de proiect
- Creați reguli de atașare automată pentru fiecare limbă/cadru din proiect
- Adăugați reguli solicitate de agent pentru cunoștințe de specialitate (bază de date, implementare, securitate)
- Pregătiți reguli manuale pentru șabloane și fluxuri de lucru repetitive
- Angajați totul în
.cursor/rules/și comunicați-l echipei - Examinați și actualizați regulile la fiecare sprint sau lansare
- STATELE UNITE ALE AMERICII
/Generate Cursor Rulesca punct de plecare pentru noi proiecte
Concluzii
Sistemul Cursor's Rules reprezintă un salt calitativ în modul în care dezvoltatorii interacționează cu AI. Nu este vorba doar de a da instrucțiuni unui chatbot: este vorba doar de codificați convențiile echipei într-un format pe care AI îl poate înțelege și aplica automat.
Cele patru tipuri de reguli (Întotdeauna, Atașat automat, Solicitat de agent, Manual) oferă un nivel de granularitate pe care nici un alt instrument AI nu o oferă în prezent. Capacitatea de a activa reguli condiționat, bazat pe tipul de fișier, combinat cu direcționarea solicitată de agent, creează a sistem dinamic de cunoștințe care se scalează cu complexitatea proiectului fără a se degrada Performanță AI.
Cel mai important sfat? Începe acum, începe simplu. Creați o regulă Întotdeauna cu cele mai importante 10 convenții ale proiectului dvs., adăugați o regulă de atașare automată pentru limba principală și repetați de acolo. Nu aveți nevoie de o configurație perfectă din prima zi: regulile evoluează odată cu proiectul, la fel ca și codul.
În următorul articol din serie vom exploraModul agent: cum să delegați sarcini complexe la IA lui Cursor, de la refactorizarea întregii funcții până la generarea de suite de testare completă. Regulile pe care le-am configurat în acest articol vor deveni fundamentul pe care agentul își va construi munca.
Resurse suplimentare
- Documentația oficială a cursorului: docs.cursor.com/context/rules-for-ai
- Exemplu de depozit: github.com/cursor-rules-examples
- Comunitate: forum.cursor.com pentru a partaja și a descoperi reguli
- Articolul următor: Modul agent - Editați baza de cod cu o comandă