Simboli @ in Cursor

Dopo aver esplorato le varie funzionalità di Cursor, come la collaborazione con l'AI, gli agenti intelligenti e l'autocompletamento contestuale, è giunto il momento di approfondire uno degli strumenti più potenti e distintivi dell'IDE: i simboli @. Essi rappresentano un linguaggio speciale che ci consente di comunicare in modo preciso e diretto con l'intelligenza artificiale integrata in Cursor, migliorando significativamente la nostra produttività e la qualità del codice.

Cosa Sono i simboli @ in Cursor

I simboli @ in Cursor sono comandi speciali che permettono di fare riferimento ad elementi specifici del nostro progetto, come file, cartelle, frammenti di codice, documentazione e altro ancora. Utilizzando questi simboli, possiamo fornire all'AI un contesto preciso, guidandola nella generazione di risposte più accurate e pertinenti. Quando digitiamo @ in uno dei campi di input di Cursor, come Composer, Chat o Cmd K, appare un menu a comparsa con una lista di suggerimenti. Questo menu si aggiorna dinamicamente in base al testo che inseriamo, mostrando le opzioni più rilevanti, come mostrato in figura:

Tipi di simboli @ disponibili

Cursor offre una varietà di simboli @, ciascuno con una funzione specifica:

• @Files: fa riferimento a file specifici nel progetto.
• @Folders: fa riferimento a intere cartelle, utile per fornire un contesto più ampio.
• @Code: fa riferimento a frammenti di codice o simboli specifici.
• @Docs: accede alla documentazione e alle guide.
• @Git: accede alla cronologia e alle modifiche del repository Git.
• @Notepads: accede ai blocchi note.
• @Past Chats: lavora con sessioni di Composer precedenti.
• @Cursor Rules: lavora con le regole di Cursor.
• @Web: fa riferimento a risorse e documentazione esterne.
• @Link (paste): crea link a codice o documentazione specifici.
• @Recent Changes: fa riferimento alle modifiche recenti.
• @Lint Errors: fa riferimento agli errori di linting (solo in Chat).
• @Definitions: cerca le definizioni dei simboli (solo in Cmd K).

Oltre ai simboli @, Cursor supporta anche altri comandi speciali:

• # Files: aggiunge file al contesto senza fare riferimento diretto.
• / Commands: aggiunge file aperti e attivi al contesto.

Per utilizzare i simboli @ possiamo semplicemente digitare @ seguito dal nome dell'elemento a cui vogliamo fare riferimento. Ad esempio, digitando @package.json, possiamo accedere direttamente al file package.json del nostro progetto. Cursor offre anche funzionalità di completamento automatico per i simboli @. Mentre digitiamo, il menu a comparsa si aggiorna per mostrare le opzioni più pertinenti, e possiamo navigare tra queste utilizzando i tasti freccia su/giù e selezionare l'opzione desiderata premendo Enter.

Vantaggi dell'uso dei simboli @

L'utilizzo dei simboli @ in Cursor offre numerosi vantaggi:

• Precisione: fornendo un contesto specifico, l'AI può generare risposte più accurate e pertinenti.
• Efficienza: riduce la necessità di spiegazioni dettagliate, accelerando il processo di sviluppo.
• Organizzazione: aiuta a mantenere il codice e la documentazione ben organizzati e facilmente accessibili.
• Collaborazione: facilita la comunicazione tra i membri del team, rendendo più semplice condividere riferimenti specifici.

Integrazione con altre funzionalità di Cursor

I simboli @ si integrano perfettamente con altre funzionalità di Cursor, come le regole (Cursor Rules) e gli agenti intelligenti. Ad esempio, possiamo utilizzare @Cursor Rules per accedere rapidamente alle regole definite nel progetto o @Git per esaminare le modifiche recenti nel repository. Inoltre, i simboli @ possono essere utilizzati in combinazione con i comandi di Composer e Chat per creare flussi di lavoro personalizzati e automatizzati. Per completezza, vediamo come usare il simbolo @Git:

1. Apriamo il Composer (Cmd + K) o una nuova chat con l’AI in Cursor.
2. Scriviamo il prompt:

@git
Puoi aiutarmi a scrivere una descrizione per la pull request basandoti sulle modifiche recenti?
Evidenzia i cambiamenti principali e spiega il motivo delle modifiche dove è possibile.

Quando usiamo @git, Cursor estrae automaticamente:

• Gli ultimi commit (titolo + diff).
• I file modificati.
• Eventuali messaggi di commit.
• Se disponibile, anche le branch coinvolte e il diff cumulativo.

Questo contesto viene incluso automaticamente nella richiesta all’AI che può quindi generare una descrizione dettagliata e coerente della PR, senza che dobbiamo spiegare tutto noi. Ecco un esempio dell'output che potremmo ricevere:

**Pull Request: Refactoring del modulo di autenticazione e miglioramenti al logging**
Questa pull request include le seguenti modifiche principali:
- Refactoring della funzione `authenticateUser` in `auth.ts` per migliorare la leggibilità e ridurre la duplicazione.
- Rimozione di `console.log` e sostituzione con un logger interno (`logger.info`) per migliorare il tracciamento in produzione.
- Aggiunto supporto per token JWT scaduti, con gestione degli errori più esplicita.
- Aggiornata la documentazione inline nei file `auth.ts` e `utils/token.ts`.
Motivazioni:
- Le modifiche erano necessarie per semplificare la logica di autenticazione, renderla più testabile e conforme alle nostre regole interne (`@rules`).
- Il logging basato su `console.log` stava generando rumore nei log di produzione, rendendo difficile il debugging.

Tutti i test esistenti sono stati eseguiti e superati.

Volendo usare il simbolo @files, proviamo a farci aiutare dall'AI a capire come funziona un componente React chiamato UserCard.tsx, incluso nel progetto, e se ci sono ottimizzazioni possibili. Allo stesso modo di prima:

1. Apriamo il Composer (Cmd + K) o una nuova chat con l’AI in Cursor.
2. Scriviamo il prompt:

@files: src/components/UserCard.tsx
Puoi spiegarmi cosa fa questo componente? Inoltre, ci sono ottimizzazioni che potremmo fare (es. memoizzazione, suddivisione logica, miglioramento performance)?

Quando usiamo @files, Cursor include l'intero contenuto del file specificato nel contesto del modello AI. A differenza di @, che fa riferimento diretto ad un file già noto o usato di recente, @files serve a forzare l’inclusione esplicita del contenuto completo del file. Utile quando vogliamo una visione esaustiva anche per file non modificati di recente.

Conclusioni

I simboli @ rappresentano uno strumento potente e versatile all'interno di Cursor, permettendoci di interagire con l'AI in modo più preciso ed efficiente. Integrandoli nel nostro flusso di lavoro quotidiano, possiamo migliorare la qualità del nostro codice, accelerare lo sviluppo e facilitare la collaborazione con i nostri colleghi.