Cursor Rules: guidare l'AI con regole intelligenti

Nelle lezioni precedenti abbiamo imparato a usare Cursor come un editor moderno e intelligente, capace di collaborare con l'AI, sfruttare agenti personalizzati e interagire con modelli avanzati. Ora ci concentriamo su un aspetto fondamentale per padroneggiare Cursor in modo completo: le regole, o come vengono chiamate in inglese, le Cursor Rules.

Queste regole rappresentano un potente meccanismo per influenzare il comportamento dell'AI, mantenere la coerenza nei nostri progetti e migliorare l'affidabilità delle risposte che otteniamo. In questa lezione esploreremo cosa sono, come si creano, come si applicano e in quali contesti ci sono utili. Impareremo anche a distinguere tra regole statiche e dinamiche e a capire come queste influenzano l'autocompletamento e il comportamento degli agenti.

Cosa sono le Cursor Rules

Le Cursor Rules sono istruzioni contestuali persistenti che possiamo definire per guidare l'AI durante la scrittura, l'autocompletamento, la chat o quando lavora come agente. In parole semplici: sono indicazioni personalizzate che l'AI deve sempre considerare quando interagisce con il nostro codice.

Immaginiamole come una sorta di "memoria locale" che istruisce l'assistente virtuale su cosa è accettabile, preferito, obbligatorio o vietato nel nostro codice. Le regole non sono generiche ma legate a file, cartelle o l'intero progetto. Questo ci permette, ad esempio, di:

• Imporre stili di programmazione specifici.
• Evitare librerie o funzioni deprecated.
• Richiedere determinati paradigmi architetturali (es. preferire functional programming a OOP).
• Stabilire convenzioni interne (naming, linting, strutture modulari, ecc.).

E la cosa ancora più interessante: possiamo farlo senza scrivere codice ma definendo semplici istruzioni in linguaggio naturale.

Dove si trovano e come si usano

In Cursor, possiamo definire le regole accedendo alla sezione Context nel pannello laterale e scegliendo la voce Rules. Da qui possiamo:

• Visualizzare tutte le regole attive.
• Aggiungere nuove regole.
• Specificare il contesto a cui si applicano (file, directory o progetto intero).

Le regole sono archiviate in un file .cursor/rules.json che Cursor gestisce automaticamente. Tuttavia, possiamo anche editarlo manualmente se vogliamo avere più controllo.

Per creare una nuova regola possiamo utilizzare la palette dei comandi con Cmd + Shift + J > Rules e premere sul pulsante "+ Add New Rule" come mostrato in figura:

Utilizzando le regole del progetto, otteniamo anche il vantaggio del controllo versione, poiché si tratta semplicemente di un file. Ecco un esempio:

{
  "rules": [
    {
      "path": "src/components",
      "rule": "Usa solo componenti a funzione, non classi."
    },
    {
      "path": "*",
      "rule": "Evita l'uso di console.log, preferisci logger custom."
    }
  ]
}

Nel primo caso, stiamo imponendo una regola specifica alla cartella src/components. Nel secondo, stiamo imponendo una regola valida per tutto il progetto. Cursor tiene sempre in considerazione queste regole durante il completamento, la chat e le azioni degli agenti.

Tipi di regole: Statiche e Dinamiche

Possiamo suddividere le Cursor Rules in due categorie:

Regole Statiche

Queste regole sono definite manualmente e rimangono stabili finché non le modifichiamo. Sono perfette per stabilire policy di lungo termine nel progetto. Alcuni esempi:

"Usa sempre TypeScript invece di JavaScript."

"Non usare librerie esterne senza approvazione."

"Segui la naming convention PascalCase per i componenti."

Regole Dinamiche

Cursor può anche suggerire o adattare regole in base al contesto, ad esempio osservando i pattern esistenti nel progetto. In alcuni casi, possiamo attivare agenti o plugin che generano regole a partire da una base di codice. Possiamo anche creare prompt dinamici, come:

"Scrivi la regola: Tutte le funzioni async devono essere suffissate con Async."

In questo modo, guidiamo Cursor nella creazione automatica della regola che poi possiamo perfezionare.

Struttura delle regole

Ogni file di regola viene scritto nel formato MDC (.mdc), un formato leggero che ci permette di combinare metadati e contenuto in un unico file. È un sistema semplice ma potente per gestire le nostre regole in modo organizzato.

Le regole possono appartenere a diversi tipi, ognuno con un comportamento specifico rispetto al modo in cui viene incluso nel contesto del modello. Ecco i tipi principali che possiamo usare:

Tipo di regola	Descrizione
Always	Viene sempre inclusa automaticamente nel contesto dell'AI.
Auto Attached	Si attiva solo quando vengono referenziati file che corrispondono a un pattern (glob).
Agent Requested	È disponibile per l'AI, che decide autonomamente se includerla o meno. È necessario fornire una descrizione.
Manual	Viene inclusa solo se la citiamo esplicitamente usando @nomeDellaRegola.

Questa struttura ci offre un controllo granulare su quando e come vogliamo che l'AI tenga conto di una determinata regola, rendendo il nostro flusso di lavoro più flessibile e su misura per il progetto in corso.

Esempio di regola MDC

In questo esempio, definiamo una regola utile per la scrittura di servizi RPC. Dichiariamo che non deve essere sempre applicata (alwaysApply: false), ma può essere richiamata quando necessario. Inoltre, il file @service-template.ts verrà incluso automaticamente come contesto di riferimento quando la regola viene utilizzata.

---
description: RPC Service boilerplate
globs:
alwaysApply: false
---
- Use our internal RPC pattern when defining services
- Always use snake_case for service names.
@service-template.ts

Quando usare le regole

A questo punto, potremmo chiederci: in quali situazioni conviene davvero usare le regole di Cursor? Le regole diventano particolarmente utili quando lavoriamo in team, su progetti di lunga durata o in contesti aziendali dove la standardizzazione è cruciale. Ma anche in progetti personali, ci aiutano a mantenere una direzione coerente, evitando errori comuni e automatizzando decisioni che altrimenti dovremmo ripetere ogni giorno.

Ad esempio:

• In un team frontend, possiamo creare una regola che vieta l'uso di !important nei file CSS, perché ritenuto anti-pattern.
• In un backend Node.js, potremmo vietare direttamente l'utilizzo di eval() o imporre l'uso di una specifica versione di express.

Usare le regole significa ridurre il carico cognitivo: possiamo affidarci all'AI per ricordare e applicare in modo coerente quelle convenzioni che, altrimenti, dovremmo vigilare manualmente.

Integrazione con gli Agenti

Come accennato, Cursor consente agli agenti di leggere e interpretare le regole. Quando un agente viene attivato, può consultare le regole attive e modificarne il comportamento. Questo è particolarmente utile in ambienti in cui vogliamo che ogni modifica al codice sia coerente con il resto del progetto.

Ad esempio, se abbiamo un agente che genera API REST, e nelle regole è specificato di usare camelCase per i parametri delle route, l'agente rispetterà automaticamente quella convenzione. In questo modo, creiamo un ecosistema armonico, dove umani e AI si muovono secondo le stesse regole, senza attriti o correzioni a posteriori.

Conclusioni

Abbiamo visto come le Cursor Rules siano molto più di un semplice strumento di configurazione. Sono una forma di linguaggio che ci permette di comunicare in modo preciso e coerente con l'intelligenza artificiale che ci affianca ogni giorno nello sviluppo.

Attraverso l'uso di regole statiche e dinamiche, la definizione di contesti specifici e l'integrazione con agenti intelligenti, possiamo costruire ambienti di lavoro robusti, scalabili e su misura per le nostre esigenze. È un nuovo modo di progettare, più vicino al design di sistemi intelligenti che alla semplice scrittura.