02 - Cursor Rules: Configurare AI per il tuo Progetto
Ogni sviluppatore ha le proprie convenzioni, pattern architetturali e standard di qualità. Quando lavori con un collega umano, queste regole vengono comunicate attraverso code review, pair programming e documentazione. Ma come puoi comunicare le stesse aspettative a un agente AI? La risposta di Cursor e il sistema di Rules: un meccanismo potente e flessibile che permette di istruire l'AI su come deve generare, modificare e ragionare sul codice del tuo progetto.
In questo articolo esploreremo ogni aspetto del sistema di Rules di Cursor: dalla sua evoluzione storica alle strategie avanzate di configurazione, passando per esempi pratici per Angular, React, Python, backend API e molto altro. Alla fine avrai tutti gli strumenti per trasformare l'AI di Cursor in un collaboratore che rispetta le convenzioni del tuo team come se le avesse sempre conosciute.
Cosa Imparerai in Questo Articolo
- L'evoluzione del sistema di Rules: da
.cursorrulesalla directory.cursor/rules/ - I quattro tipi di rule: Always, Auto Attached, Agent Requested e Manual
- La differenza tra User Rules e Project Rules e quando usare ciascun tipo
- Come scrivere rule efficaci con frontmatter, globs e descrizioni
- Esempi completi per Angular, React, Python, FastAPI e API REST
- Strategie avanzate: conditional rules, rule inheritance, generazione automatica
- Workflow di team: condivisione via git, onboarding e convenzioni condivise
- Confronto con CLAUDE.md e altri sistemi di istruzioni AI
Panoramica della Serie Cursor IDE e AI-Native Development
| # | Articolo | Focus |
|---|---|---|
| 1 | Guida Completa Cursor IDE | Panoramica completa |
| 2 | Sei qui - Cursor Rules | Configurazione AI personalizzata |
| 3 | Agent Mode | Automazione avanzata |
| 4 | Plan Mode | Pianificazione assistita |
| 5 | Hooks e MCP | Estensibilita e integrazioni |
| 6 | Workflow Professionali | Best practices produttive |
L'Evoluzione del Sistema di Rules in Cursor
Il sistema di Rules di Cursor ha attraversato un'evoluzione significativa dalla sua introduzione iniziale. Comprendere questa storia e fondamentale per capire perchè il sistema attuale e strutturato in un certo modo e per evitare confusione tra le diverse generazioni di configurazione.
La Prima Generazione: il File .cursorrules
Nella prima implementazione, Cursor supportava un unico file .cursorrules nella root del progetto.
Questo file conteneva istruzioni in testo libero che venivano iniettate nel contesto di ogni interazione AI.
Era semplice e diretto: scrivi le tue regole in un file, e l'AI le seguira.
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
Questo approccio aveva un limite evidente: tutte le regole finivano in un unico file monolitico.
In un progetto complesso con frontend Angular, backend Python, infrastruttura Docker e pipeline CI/CD,
il file .cursorrules diventava rapidamente enorme e difficile da gestire. Inoltre, tutte le regole
venivano sempre inviate all'AI, anche quando non erano rilevanti per il contesto corrente.
La Seconda Generazione: Project Rules con .cursor/rules/
Per risolvere queste limitazioni, Cursor ha introdotto il sistema di Project Rules basato sulla
directory .cursor/rules/. Questo nuovo approccio permette di organizzare le regole in file separati,
con metadati strutturati e attivazione condizionale basata su pattern di file.
La directory .cursor/rules/ e pensata per essere committata nel repository git, in modo che tutti
i membri del team condividano automaticamente le stesse istruzioni AI. Ogni file nella directory e un file
.mdc (Markdown with Context) che contiene un frontmatter YAML e il corpo delle istruzioni in Markdown.
perchè .mdc e Non .md?
Il formato .mdc (Markdown with Context) e un'estensione proprietaria di Cursor che aggiunge
un frontmatter strutturato al Markdown standard. Il frontmatter definisce metadati come la descrizione della
rule, i pattern glob per l'attivazione automatica e il flag alwaysApply. Cursor interpreta
questi metadati per decidere quando e come applicare ciascuna rule.
I Quattro Tipi di Rule
Il sistema moderno di Cursor definisce quattro modalità di attivazione delle rule, ciascuna progettata per un caso d'uso specifico. Scegliere il tipo giusto e cruciale per bilanciare la pertinenza delle istruzioni con il consumo di contesto AI.
1. Always Rules
Le rule di tipo Always vengono incluse in ogni interazione con l'AI, indipendentemente dal file su cui stai lavorando o dalla richiesta che fai. Sono ideali per convenzioni universali del progetto che devono essere sempre rispettate.
---
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
Attenzione al Consumo di Contesto
Le rule Always vengono sempre inviate all'AI, consumando token del contesto in ogni interazione. Usa questo tipo solo per regole veramente universali. Se una regola si applica solo a certi file o situazioni, preferisci Auto Attached o Agent Requested per ottimizzare l'uso del contesto.
2. Auto Attached Rules
Le rule Auto Attached vengono attivate automaticamente quando lavori su file che corrispondono a specifici pattern glob. Sono perfette per regole specifiche di un linguaggio, framework o tipo di file.
---
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)
Il campo globs supporta pattern glob standard. Puoi usare wildcard semplici come *.ts
o pattern complessi come {**/*.service.ts,**/*.guard.ts}. Quando apri un file
che corrisponde al pattern, la rule viene automaticamente inclusa nel contesto AI.
3. Agent Requested Rules
Le rule Agent Requested sono visibili all'AI attraverso la loro descrizione, ma vengono incluse nel contesto solo quando l'agente decide che sono rilevanti per il task corrente. Questo tipo e ideale per regole specialistiche che non servono sempre ma che l'AI deve poter consultare quando necessario.
---
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
In questo esempio, la rule non ha globs e ha alwaysApply: false. L'AI vedra solo la
descrizione "Regole per la creazione e gestione delle migrazioni database con Prisma" e decidera autonomamente
se includere il contenuto completo della rule quando il task riguarda operazioni sul database. Questo approccio
e particolarmente efficiente: l'AI ha accesso a un catalogo di conoscenze specialistiche senza sprecare contesto
quando non servono.
4. Manual Rules
Le rule Manual non vengono mai incluse automaticamente. Devono essere richiamate esplicitamente
dallo sviluppatore usando il riferimento @ruleName nel prompt. Sono utili per template,
snippet o istruzioni che vuoi usare solo in situazioni specifiche.
---
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
Per usare questa rule, lo sviluppatore scrivera nel prompt qualcosa come: "Crea una nuova feature per il profilo utente seguendo @new-feature-template". L'AI includera il contenuto della rule nel contesto e generera il codice secondo il template.
Riepilogo dei Tipi di Rule
| Tipo | Attivazione | Caso d'Uso | Consumo Contesto |
|---|---|---|---|
| Always | Sempre inclusa | Convenzioni universali del progetto | Alto (sempre attiva) |
| Auto Attached | Pattern glob su file | Regole specifiche per linguaggio/framework | Medio (solo file rilevanti) |
| Agent Requested | L'AI decide in base alla descrizione | Conoscenze specialistiche on-demand | Basso (solo quando serve) |
| Manual | Richiamo esplicito con @nome | Template, snippet, istruzioni rare | Minimo (solo su richiesta) |
User Rules vs Project Rules
Cursor distingue tra due livelli di configurazione: le User Rules che si applicano a tutti i tuoi progetti e le Project Rules che sono specifiche per un singolo repository. Comprendere quando usare l'uno o l'altro e fondamentale per una configurazione efficace.
User Rules: Le Tue Preferenze Globali
Le User Rules si configurano in Cursor Settings > General > Rules for AI. Queste regole
definiscono le tue preferenze personali che restano costanti indipendentemente dal progetto su cui lavori.
Non sono file nel repository: vivono nella configurazione locale di Cursor.
## 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
Project Rules: Convenzioni del Repository
Le Project Rules vivono nella directory .cursor/rules/ del progetto e vengono committate
nel repository git. Questo significa che ogni membro del team che clona il repository avra automaticamente
le stesse istruzioni AI, garantendo consistenza nella generazione del codice.
User Rules vs Project Rules: Quando Usare Cosa
| Aspetto | User Rules | Project Rules |
|---|---|---|
| Scope | Tutti i progetti | Singolo repository |
| Posizione | Cursor Settings | .cursor/rules/*.mdc |
| Condivisione | Solo locale | Via git (team) |
| Precedenza | Base (sovrascritta dal progetto) | Alta (specifica del contesto) |
| Esempio | Lingua, stile di risposta, principi generali | Framework, architettura, pattern specifici |
La precedenza funziona in modo intuitivo: le Project Rules hanno la priorità sulle User Rules quando c'è un conflitto. Se le tue User Rules dicono "usa classi" ma le Project Rules dicono "usa funzioni", l'AI seguira le Project Rules. Questo permette a ogni progetto di avere le proprie convenzioni senza dover modificare le preferenze globali.
Anatomia di una Rule Efficace
Scrivere una rule che l'AI possa seguire correttamente richiede attenzione alla struttura, alla chiarezza e alla secificità delle istruzioni. Una rule ben scritta e la differenza tra un'AI che genera codice generico e un'AI che genera codice perfettamente allineato ai tuoi standard.
Struttura del File .mdc
Ogni file .mdc e composto da due parti: il frontmatter YAML delimitato da
--- e il corpo in Markdown con le istruzioni vere e proprie.
---
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
Best Practices per Scrivere Rules Efficaci
Dopo aver configurato centinaia di rule in progetti reali, ho identificato cinque principi fondamentali che determinano l'efficacia di una rule.
1. Sii specifico, non generico. Una rule che dice "scrivi codice pulito" e inutile. Una rule che dice "ogni funzione deve avere al massimo 4 parametri, ognuno con tipo esplicito e JSDoc" e azionabile dall'AI.
2. Mostra, non solo dire. Includi sempre almeno un esempio concreto di codice che rispetta la rule. L'AI apprende meglio dagli esempi che dalle descrizioni astratte.
3. Definisci anche gli anti-pattern. Indica esplicitamente cosa NON fare. Se la rule dice "usa signals" ma non dice "non usare BehaviorSubject", l'AI potrebbe mescolare i due approcci.
4. Una rule, un tema. Non creare file monolitici che coprono tutto. Dividi le regole per area: una rule per il testing, una per il CSS, una per l'architettura. Questo facilità la manutenzione e permette l'attivazione selettiva tramite globs.
5. Scrivi la descrizione pensando all'AI. Il campo description nel frontmatter
e quello che l'AI legge per decidere se includere una rule Agent Requested. Deve essere concisa ma
sufficientemente informativa per permettere all'AI di capire quando la rule e rilevante.
Rules per Angular: Esempio Completo
Angular e un framework con convenzioni precise e un ecosistema in rapida evoluzione. Con il passaggio a standalone components, signals e la nuova control flow syntax, e fondamentale che l'AI generi codice che segue le best practice moderne. Ecco un set completo di rules per un progetto 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(() =>
`