Cursor Rules: Come scrivere file .cursor/rules che funzionano davvero

Ogni utente di Cursor prima o poi si scontra con lo stesso ostacolo. L'IA genera codice che tecnicamente funziona, ma ignora le convenzioni del tuo progetto — percorsi di importazione sbagliati, pattern obsoleti, componenti che non assomigliano per nulla al resto della tua codebase. Le Cursor Rules risolvono questo problema fornendo all'IA un contesto persistente su come funziona il tuo progetto.

Cosa sono le Cursor Rules e perché sono importanti?

Le Cursor Rules sono file Markdown che fungono da prompt di sistema permanente, iniettato prima di ogni interazione con l'IA — chat, completamento automatico, generazione di codice, tutto. Pensale come la documentazione di onboarding per l'IA. Invece di correggere gli stessi errori ogni sessione, scrivi l'istruzione una volta e rimane.

Il vecchio approccio era un singolo file .cursorrules nella directory radice del progetto. Funziona ancora, ma è deprecato. Il sistema attuale usa una directory .cursor/rules/ con file .mdc individuali (Markdown Cursor), ciascuno circoscritto a situazioni specifiche. È una configurazione molto migliore perché non devi stipare tutte le istruzioni in un unico file gigante — dividi le regole per responsabilità e Cursor carica solo quelle rilevanti per quello che stai facendo in quel momento.

Se hai lavorato con il context engineering per strumenti IA, il concetto è familiare: un contesto di input migliore produce output notevolmente migliori. Le regole sono context engineering per l'intero flusso di lavoro di sviluppo.

Configurare il primo file di regole

Crea la directory .cursor/rules/ nella radice del tuo progetto:

mkdir -p .cursor/rules

Ogni regola è un file .mdc con frontmatter YAML seguito da contenuto Markdown. Ecco lo scheletro:

---
description: "Quando questa regola deve applicarsi"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Le tue istruzioni vanno qui in Markdown semplice.

Tre campi del frontmatter controllano tutto:

Puoi anche creare regole attraverso Cursor stesso — digita /create-rule nella chat e descrivi cosa vuoi. Ma scriverle a mano ti dà più controllo.

I quattro tipi di regole spiegati

Come si attiva una regola dipende dalla configurazione del frontmatter. Ci sono quattro modalità, e scegliere quella giusta conta per il tuo budget della finestra di contesto.

Applica sempre

---
alwaysApply: true
---

Caricata in ogni singola richiesta IA. Usala con parsimonia — per i fondamentali a livello di progetto come la dichiarazione del tuo stack tecnologico o le convenzioni critiche che si applicano ovunque. Ogni regola sempre attiva consuma token da ogni interazione, che sia rilevante o meno.

Allegata automaticamente (basata su glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Si attiva solo quando stai modificando file che corrispondono ai pattern glob. Questo è il tipo di regola più usato. Le tue convenzioni per i componenti React vengono caricate quando sei nei file dei componenti, i tuoi pattern API quando sei negli handler delle route, le tue regole di test quando stai scrivendo test.

Richiesta dall'agente (intelligente)

---
description: "Pattern di migrazione database con Drizzle ORM"
alwaysApply: false
---

Nessun glob, nessun always-apply — solo una descrizione. L'agente di Cursor legge la descrizione e decide se la regola è rilevante per il compito attuale. Se gli chiedi di scrivere una migrazione, carica questa regola. Se stai stilizzando un pulsante, la salta. Funziona sorprendentemente bene per regole che non si mappano facilmente su percorsi di file.

Manuale

---
---

Nessun campo frontmatter impostato (o frontmatter vuoto). Queste regole si attivano solo quando le menzioni esplicitamente con @nome-regola nella chat. Utile per istruzioni raramente usate ma importanti — come checklist di deployment o guide di refactoring di cui hai bisogno solo occasionalmente.

Pattern glob che funzionano davvero

I glob determinano quali file attivano le regole allegate automaticamente. Se sono sbagliati, le tue regole non si attivano mai o si attivano ovunque. Ecco cosa funziona:

# Tutti i file TypeScript in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Solo file di componenti
globs: ["**/components/**/*.tsx"]

# File Python, escludendo i test
globs: ["**/*.py", "!**/test_*.py"]

# Più directory specifiche
globs: ["src/api/**", "src/services/**"]

Alcune insidie dall'uso reale:

• src/* corrisponde solo a un livello di directory. Quasi sempre vorrai src/**/* per la corrispondenza ricorsiva.
• *.js non corrisponde a file .jsx o .ts. Sii esplicito sulle estensioni.
• I glob devono essere una lista YAML. La sintassi con le graffe come {src,lib}/**/*.ts può fallire silenziosamente — usa voci di lista separate.
• Il prefisso ! esclude i pattern, utile per ignorare file generati o codice legacy.

Esempi pratici di regole

Qui la teoria incontra la realtà. Queste sono regole che puoi inserire in un progetto e vedere immediatamente output IA migliori.

Regola base a livello di progetto (Applica sempre)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Tieni questo sotto le 30 righe. Viene caricato con ogni richiesta, quindi ogni parola costa token.

Regola per i componenti React (Allegata automaticamente)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Regola API Python (Allegata automaticamente)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Regola servizio Go (Allegata automaticamente)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Gestire il costo in token

Ecco qualcosa che la maggior parte delle guide a Cursor omette: ogni regola che scrivi costa token. Un progetto con 20 regole sempre attive può bruciare **più di 2.000 token per richiesta** solo per le istruzioni — prima ancora che l'IA guardi il tuo codice.

Questo conta perché il contesto di chat di Cursor è circa 20.000 token in modalità standard. Se le tue regole ne consumano il 25%, hai perso un quarto dello "spazio di pensiero" dell'IA per la tua domanda reale. Noterai una qualità di output peggiore man mano che le regole si accumulano, soprattutto nelle conversazioni più lunghe.

Tre principi per mantenere sano il tuo budget di token:

**1. Usa le regole allegate automaticamente e richieste dall'agente senza risparmio.** Solo la dichiarazione dello stack di progetto dovrebbe essere sempre attiva. Tutto il resto dovrebbe caricarsi in modo condizionale. Quella regola dei componenti React? Non ha bisogno di essere nel contesto quando stai scrivendo migrazioni SQL.

**2. Scrivi denso, non prolisso.** Sostituisci "Si raccomanda vivamente che gli sviluppatori utilizzino le interfacce TypeScript anziché gli alias di tipo quando definiscono i contratti API pubblici" con "Prefer `interface` over `type` for public APIs." L'IA non ha bisogno di essere convinta — ha bisogno di istruzioni.

**3. Applica la Regola del Tre.** Codifica un pattern come regola solo dopo che l'IA lo ha sbagliato tre volte. Se Cursor gestisce già correttamente le tue convenzioni di denominazione senza una regola, salta la regola. Ogni regola inutile è contesto sprecato.

Puoi monitorare l'utilizzo dei token nella barra di stato in fondo al pannello di chat di Cursor. Tieni d'occhio quando si avvicina al 100% — è il segnale per fare una potatura.

## Organizzare le regole per un progetto reale

Un progetto in produzione di solito ha bisogno di 5-8 file di regole. Ecco una struttura che funziona bene:

```text
.cursor/rules/
  base.mdc            # Stack tecnologico, always-apply (< 30 righe)
  components.mdc      # Pattern React/Vue, glob alle directory dei componenti
  api.mdc             # Convenzioni backend, glob alle directory API
  database.mdc        # Pattern ORM, glob a models/migrations
  testing.mdc         # Convenzioni di test, glob ai file di test
  deployment.mdc      # Pattern CI/CD, attivazione manuale
  personal.mdc        # Le tue preferenze (gitignored)

Committa tutto nel controllo versione eccetto personal.mdc. In questo modo l'intero team ottiene lo stesso comportamento dell'IA — che è il punto. Come dice un utente del forum di Cursor, buone regole significano che "accetti più suggerimenti così com'è, con output che corrispondono alle tue convenzioni al primo tentativo."

Se lavori con altri strumenti di codice IA accanto a Cursor, i concetti si trasferiscono direttamente. Claude Code usa CLAUDE.md, GitHub Copilot ha file di istruzioni e Windsurf ha il suo formato — ma il principio sottostante è identico.

Come funziona la precedenza delle regole

Quando più regole si applicano allo stesso file, Cursor segue una gerarchia chiara:

Le Team Rules sono disponibili nei piani Team ed Enterprise. Vengono impostate nel dashboard di Cursor dagli amministratori e applicate in tutta l'organizzazione — i singoli sviluppatori non possono disattivarle.

All'interno delle regole di progetto, se due regole si applicano allo stesso file e sono in conflitto, il comportamento non è strettamente definito. In pratica, le regole caricate più tardi tendono ad avere la precedenza. Numerare i file (001-base.mdc, 002-components.mdc) dà un ordine prevedibile.

Errori comuni e come correggerli

Dopo aver letto decine di thread della community e testato regole su vari progetti, questi sono gli errori che fanno inciampare di più:

Scrivere regole troppo vaghe. "Scrivi codice pulito" non dice nulla all'IA. "Usa export nominati, non export predefiniti. Struttura i componenti come: import, tipi, funzione, sotto-componenti" le dà qualcosa di praticabile.

Mettere tutto in always-apply. Il primo istinto è impostare alwaysApply: true su ogni regola. Resisti. Fai un audit delle regole ogni trimestre — se hai più di 2-3 regole sempre attive, probabilmente stai sprecando token.

Dimenticare di testare le regole. Dopo aver scritto una regola, apri un file pertinente e chiedi a Cursor di generare qualcosa che dovrebbe seguire la regola. Se non lo fa, il tuo pattern glob potrebbe essere sbagliato, o l'istruzione non è abbastanza chiara.

Non documentare gli anti-pattern. Dire all'IA cosa fare è metà del lavoro. Dirle cosa non fare è l'altra metà. Includi in ogni regola una sezione "NON fare mai questi" con esempi espliciti dell'approccio sbagliato.

Ignorare il salvataggio delle regole nell'UI. Un bug noto causa la scomparsa delle modifiche alle regole. Se le modifiche scompaiono, chiudi completamente Cursor, seleziona "Override" nel popup delle modifiche non salvate e riaprilo.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor non è l'unico strumento che usa file di istruzioni. Ecco come si confrontano i formati per chiunque lavori con più assistenti IA per la programmazione:

Il vantaggio di Cursor è la granularità. CLAUDE.md e AGENTS.md sono più semplici — caricano tutto sempre. Cursor ti permette di caricare le regole giuste al momento giusto, cosa che conta una volta che il tuo set di istruzioni supera qualche centinaio di righe.

Per un'analisi più approfondita di come il contesto modella l'output IA in questi strumenti, la nostra guida al context engineering illustra i principi che si applicano indipendentemente dall'editor che usi.

Se le funzionalità AI sono nella tua roadmap, è la nostra specialità: il team di integrazione AI di Techsy porta i sistemi LLM dal prototipo alla produzione. Vuoi una seconda opinione sul tuo stack? Richiedi una consulenza gratuita.

Domande frequenti

.cursorrules è deprecato?

Sì. Il singolo file .cursorrules nella directory radice del tuo progetto funziona ancora, ma Cursor raccomanda di migrare a file .cursor/rules/*.mdc. Il nuovo formato supporta pattern glob, caricamento condizionale e una migliore organizzazione. Esegui la migrazione dividendo il file monolitico in regole mirate.

Quale estensione di file devo usare — .mdc o .md?

Usa .mdc per i file che includono frontmatter YAML (description, globs, alwaysApply). I file .md semplici funzionano anche nella directory delle regole, ma non supportano i metadati frontmatter che abilitano il caricamento condizionale.

Quante regole dovrebbe avere un progetto?

Da cinque a otto è il punto ottimale per la maggior parte dei progetti. Una regola base sempre attiva, da tre a quattro regole allegate automaticamente per tipo di file e una o due regole manuali per compiti speciali. Più di 10 regole di solito significa che alcune possono essere consolidate o rimosse.

Le Cursor Rules influenzano il completamento automatico e il completamento con Tab?

Le regole si applicano alle interazioni di chat e agente. Le User Rules non si applicano alle modifiche inline (Cmd/Ctrl+K), e le regole generalmente non influenzano i suggerimenti di completamento automatico di Cursor Tab. Sono più efficaci nelle sessioni di chat e Composer.

Posso condividere regole tra più progetti?

Sì, tramite la funzionalità Remote Rules di Cursor. Vai a Cursor Settings > Rules, Commands, seleziona "Remote Rule (GitHub)" e incolla un URL di repository. Le regole si sincronizzano automaticamente quando il repository sorgente si aggiorna. In alternativa, mantieni un repository di regole condiviso e crea link simbolici in ogni progetto.

Qual è la lunghezza massima raccomandata per una regola?

La documentazione di Cursor suggerisce di mantenere le singole regole sotto le 500 righe. In pratica, punta a meno di 100 righe per regola. Le regole più brevi sono più facili da mantenere e costano meno token. Se una regola supera le 150 righe, dividila in due regole mirate.

Le regole funzionano con tutti i modelli IA in Cursor?

Le regole funzionano con ogni modello supportato da Cursor — Claude, GPT-4o, Gemini e altri. Le regole vengono iniettate come contesto a livello di sistema indipendentemente dal modello selezionato. Il comportamento del modello può variare, ma le regole stesse sono agnostiche rispetto al modello.

Come faccio il debug di una regola che non funziona?

Prima, verifica che il pattern glob corrisponda al tuo file — apri il file e controlla se la regola appare nel pannello di contesto. Poi, testa con una domanda diretta che dovrebbe attivare la regola. Prova poi a impostare temporaneamente alwaysApply: true per confermare che il contenuto della regola stesso funzioni. Se sì, il problema è nel tuo pattern glob.

Dovrei committare .cursor/rules in git?

Assolutamente. L'intero scopo delle regole di progetto è la coerenza a livello di team. Committa tutto in .cursor/rules/ tranne i file di preferenze personali. Aggiungi personal.mdc a .gitignore per le impostazioni individuali che non dovrebbero applicarsi a tutti.

Posso usare Cursor Rules insieme ai server MCP?

Sì, e si complementano molto bene. Le regole definiscono come l'IA dovrebbe scrivere il codice, mentre i server MCP danno all'IA accesso a strumenti e dati esterni. Una regola potrebbe dire "usa sempre il nostro client API interno", mentre un server MCP permette all'IA di interrogare effettivamente quell'API durante lo sviluppo.

Fonti

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub