Regole di Cursor: come mantenere l’AI allineata al tuo codebase

Apri una nuova chat in Cursor e incolli lo stesso blocco di istruzioni che hai già incollato cento volte. Il tuo stack, le tue convenzioni di naming e la struttura delle cartelle che l’AI continua a sbagliare. Poi genera una classe di 40 righe con tre livelli di astrazione per qualcosa che richiedeva solo una funzione.

È ora di svegliarsi da questo incubo. Le regole di Cursor sono file di progetto che rendono inutile incollare istruzioni. Scrivi le tue convenzioni una sola volta e l’output dell’AI si allinea al tuo codebase invece di remargli contro.

Questo tutorial costruisce un set di file di regole .mdc per un progetto web Python con FastAPI e pytest, coprendo contesto di progetto, semplicità del codice e formattazione degli errori API. Se sei alle prime armi con Cursor, ti consiglio di seguire prima il corso Sviluppo software con Cursor, poi apri un progetto e segui passo passo.

Cosa sono le regole di Cursor?

Le regole di Cursor sono file markdown con frontmatter specifico MDC che vivono nel tuo progetto in .cursor/rules/. Prima che il tuo prompt raggiunga il modello, Cursor verifica quali regole corrispondono e antepone il loro contenuto alla finestra di contesto. Le tue istruzioni arrivano per prime, ogni volta.

Ogni file .mdc ha tre campi di frontmatter che controllano l’attivazione: description, globs e alwaysApply. Una regola può attivarsi in ogni conversazione o solo quando certi file sono aperti. Una terza opzione, Applica in modo intelligente, permette all’agente di leggere la descrizione e decidere autonomamente se la regola è pertinente. La prossima sezione copre ogni tipo in pratica.

Cursor supporta quattro categorie di regole:

Le regole di progetto hanno sostituito il vecchio file .cursorrules, un singolo file a livello root senza scoping né metadata, suddividendo le regole in più file .mdc con frontmatter.

AGENTS.md è l’alternativa più semplice per i progetti che non hanno bisogno di scoping con glob. È semplice markdown riconosciuto anche da strumenti di coding con AI oltre a Cursor, e i file più profondi nelle sottodirectory sovrascrivono quelli dei livelli superiori.

Puoi approfondire come i workflow basati su agenti si collegano al tuo processo di sviluppo nella nostra skill track Fondamenti degli agenti AI.

Creare e configurare le regole di progetto di Cursor

Il resto di questo tutorial crea file di regole per un progetto FastAPI che usa pytest. I pattern si adattano a qualsiasi stack.

Impostare la directory e i file delle regole

Crea una directory .cursor/rules/ nella root del progetto. Ogni file .mdc che metti qui diventa una regola che Cursor rileva all’istante, senza bisogno di riavviare.

Il primo file di regole, project-context.mdc, dà all’AI una consapevolezza persistente del tuo stack e della struttura delle cartelle:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Digitare /create-rule in una chat con Agent è un altro modo per iniziare: Cursor te ne propone una bozza tramite un pannello in chat.

Il frontmatter alwaysApply: true significa che questa regola si carica in ogni conversazione. Dai ai file un nome in kebab-case per ambito (project-context.mdc, simplicity.mdc, error-responses.mdc) e mantieni ciascuno sotto le 500 righe. Un file di regole gonfio consuma spazio della finestra di contesto che ti serve per il codice reale e i prompt. Effettua il commit della directory .cursor/rules/ su git.

Configurare i metadata delle regole per un matching accurato

La regola project-context.mdc mostrata sopra usa alwaysApply: true, la modalità più semplice: ogni conversazione la carica a prescindere dai file su cui stai lavorando. È la scelta giusta per il contesto a livello di progetto.

Alcune regole si applicano solo a parti specifiche del codebase. Imposta alwaysApply: false e aggiungi pattern glob come elenco separato da virgole per delimitarle. Una regola con globs: app/routers/**/*.py si attiva solo quando i file corrispondenti (qui: file Python in app/routers/ o sottocartelle) compaiono nel contesto, mantenendo le convenzioni API fuori dalle chat non correlate.

Applica in modo intelligente salta del tutto i pattern dei file. Lasci globs vuoto e scrivi invece una description dettagliata, e l’agente decide se la regola è rilevante per la conversazione corrente. La qualità della descrizione conta: "Error handling rules" è troppo vaga perché l’agente la riconosca in modo affidabile, mentre "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" contiene segnali chiari.

Le regole senza glob, senza una descrizione significativa e con alwaysApply: false diventano solo manuali, caricate quando digiti @rule-name in chat. Utili per materiale di riferimento da richiamare su richiesta.

Scrivere contenuti e vincoli delle regole

Regole scritte con un linguaggio morbido ("cerca di mantenere piccole le funzioni", "preferisci endpoint async") danno all’AI il permesso di ignorarle. Scrivi comandi invece: "Le funzioni devono stare sotto le 30 righe. Tutti gli endpoint devono essere async."

Nell’introduzione si citava l’AI che genera una classe di 40 righe con tre livelli di astrazione. La regola che ferma questo comportamento è simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

La differenza è immediata. L’AI smette di cercare classi astratte di base quando c’è una sola implementazione e usa if quando ci sono due casi.

La terza regola, error-responses.mdc, è limitata da glob per attivarsi solo quando lavori con i file delle route API:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Quando possibile, punta a file esistenti nel tuo codebase invece di copiare codice nelle regole. Una riga come "Vedi app/routers/users.py per la struttura canonica dell’endpoint" resta accurata man mano che il codice evolve, mentre uno snippet copiato diventa obsoleto nel momento in cui qualcuno rifattorizza l’originale.

Testare e verificare l’aggancio delle regole

Cursor non ha un indicatore integrato che mostri quali regole siano attive in una conversazione. La verifica si fa testando il comportamento.

Apri una nuova chat con Agent e scrivi un prompt che dovrebbe attivare una delle tue regole. Per error-responses.mdc prova: "Aggiungi un endpoint DELETE per rimuovere un utente per ID in app/routers/users.py." Se la gestione degli errori generata non somiglia alla struttura JSON della tua regola o salta HTTPException con il dict detail, qualcosa nel matching non va.

Le regole limitate da glob richiedono un file corrispondente menzionato nel prompt o aperto nell’editor. Testare error-responses.mdc senza menzionare alcun file sotto app/routers/ significa che la regola non si attiva mai. 

Le regole "Applica in modo intelligente" sono invece basate sul tema: prova un prompt attinente alla descrizione della regola, poi uno non correlato, e confronta gli output. L’agente dovrebbe seguire la regola nel primo caso e ignorarla nel secondo.

Mantenere efficaci le tue regole di Cursor

Regole che funzionavano il mese scorso possono fuorviare l’AI dopo un refactor o un rinominare di cartelle.

Risoluzione dei problemi di matching

La ragione più comune per cui una regola non si attiva è l’estensione del file: le regole devono usare .mdc e i semplici file .md in .cursor/rules/ vengono ignorati senza avviso.

Oltre a questo:

• Glob troppo ampi come **/*.py agganciano la regola a ogni file Python del progetto. Restringi a app/routers/**/*.py o tests/**/*.py, così la regola si attiva solo dove serve.

• Noterai che le regole "Applica in modo intelligente" saltano conversazioni quando la descrizione è troppo generica. Gli esempi di descrizioni buone/cattive della sezione sui metadata qui sopra valgono anche qui.

• Le regole in conflitto sono più difficili da individuare. Quando due regole danno istruzioni contraddittorie per gli stessi file, l’AI ne sceglie una (di solito quella caricata per ultima). Risolvi restringendo l’ambito dei glob in modo che le regole non si sovrappongano, oppure unificando le indicazioni correlate in un unico file.

Una particolarità da conoscere: a volte le modifiche ai file .mdc spariscono senza essere salvate. Se le modifiche non vengono mantenute, chiudi completamente Cursor, seleziona "Override" nel pop-up delle modifiche non salvate e riapri.

Far rispettare le regole a conversazione in corso

Una regola può attivarsi correttamente all’inizio di una conversazione e venire comunque ignorata cinque messaggi dopo. La causa è il bias di recency della finestra di contesto: con il crescere della conversazione, il modello dà priorità ai messaggi recenti rispetto alle istruzioni inserite in cima. È il problema più comune nella community di Cursor, e non c’è un’impostazione che lo risolva.

Il workaround è il rinforzo. Quando l’output inizia ad allontanarsi dalle tue regole, aggiungi una riga come "segui le regole del progetto per le risposte d’errore" al tuo prossimo prompt. Questo riporta l’istruzione nel contesto recente del modello. 

Per le regole che contano su ogni risposta (formattazione, naming), una formulazione più breve e diretta regge meglio nelle conversazioni lunghe rispetto a paragrafi dettagliati.

Le regole con esempi di codice resistono alla deriva meglio delle sole istruzioni testuali. Invece di scrivere "usa early return per la gestione degli errori", includi un breve blocco prima/dopo che mostri il pattern desiderato. Il modello si ancora al codice reale in modo più affidabile rispetto alle descrizioni in prosa, soprattutto quando il contesto si accumula.

Manutenzione e potatura delle regole

Rivedi le regole dopo ogni refactor importante, aggiornamento di dipendenze o ristrutturazione di cartelle. Una regola che fa riferimento ad API deprecate o file rimossi fornirà istruzioni errate all’AI. I glob obsoleti sono ancora più silenziosi quando falliscono: rinomina app/api/ in app/routers/ e una regola limitata al vecchio percorso smette semplicemente di attivarsi senza avviso.

La potatura va anche nella direzione opposta. Con il migliorare dei modelli, colgono le convenzioni comuni senza bisogno di esplicitarle. Se l’AI segue già le indicazioni di una regola spontaneamente, eliminala e recupera i token. Un set di regole sano si riduce nel tempo, non cresce soltanto.

Scalare le regole negli ambienti di team

Tratta le regole come codice applicativo. Le modifiche passano tramite pull request e il team concorda un pattern prima che arrivi in .cursor/rules/.

Per le organizzazioni con piani Business o Enterprise, le Regole di Team permettono agli admin di far rispettare le regole a tutti i membri dal dashboard di Cursor. "Abilita immediatamente" rende una regola attiva di default lasciando agli utenti la possibilità di disattivarla. "Imponi questa regola" rimuove l’opt-out, utile per convenzioni non negoziabili come pratiche di sicurezza e requisiti di conformità.

Conclusione

Inizia con una o due regole per i pattern che correggi più spesso. Se continui a modificare lo stesso tipo di output dell’AI in ogni sessione (formato degli errori sbagliato, astrazioni inutili), quella è una regola che aspetta solo di essere scritta. Aggiungine altre quando noti errori ricorrenti e taglia quelle che non rendono più.

I file .mdc di questo tutorial si adattano a un progetto FastAPI. I tuoi avranno un aspetto diverso per un frontend Next.js o uno strumento CLI in Rust, e questo è il punto: codificano le convenzioni del tuo team, non best practice generiche. 

Se vuoi approfondire Cursor, dai un’occhiata alla nostra guida a Cursor 2.0. Per un confronto con altri assistenti di coding AI, ti consiglio di leggere i nostri articoli comparativi:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf