Regole Cursor pronte per la produzione: Next.js, React TypeScript e FastAPI [Guida 2026]

Gli assistenti di programmazione basati su intelligenza artificiale tendono a riproporre convenzioni superate se non vengono opportunamente vincolati. Nei progetti moderni, Cursor suggerisce spesso API obsolete del vecchio Pages router di Next.js, inserisce tipi any nei componenti React o genera chiamate sincrone bloccanti all'interno di rotte asincrone Python FastAPI.

Le regole di Cursor aiutano a ridurre queste problematiche. Collocando file mirati nella cartella .cursor/rules/, fornite ai modelli linee guida architetturali nel contesto pertinente. Sono istruzioni, non vincoli eseguiti dal compilatore: non garantiscono l'assenza di bug o allucinazioni e richiedono test e revisione. Consultate la documentazione ufficiale sulle regole.

Modelli e accesso, aggiornamento del 22 ottobre 2026: Cursor elenca Opus 5.5, Sonnet 5.5, Gemini 4 Argon e GPT 5.6 Sol tra i modelli disponibili. L'accesso dipende dal piano e dalla configurazione: aggiungere una regola non sblocca un modello né ne aumenta le quote. Verificate la documentazione sui modelli e sui piani.

Di seguito troverete modelli di regole testati per Next.js, React TypeScript e FastAPI nel 2026, con una guida pratica per organizzare regole modulari ed efficaci.

File radice .cursorrules a confronto con regole modulari .cursor/rules/*.mdc

Risposta diretta: Le versioni moderne di Cursor supportano file modulari .cursor/rules/*.mdc; il file legacy .cursorrules resta supportato. Per una regola con alwaysApply: false e pattern glob, le istruzioni vengono aggiunte quando un file corrispondente entra nel contesto, non soltanto quando lo si modifica. Questo permette di limitare le istruzioni allo stack pertinente, senza garantire l'assenza di errori.

Inizialmente Cursor utilizzava un singolo file .cursorrules nella radice del progetto. Pur essendo rapida da configurare, questa modalità costringe ogni richiesta a includere istruzioni sull'intero stack tecnologico, sprecando token di contesto e creando direttive discordanti tra frontend e backend.

Le versioni attuali di Cursor supportano file modulari nel formato .cursor/rules/*.mdc. Ciascun file .mdc unisce un'intestazione YAML a indicazioni tecniche in formato Markdown:

---
description: Sintesi dell'ambito della regola
globs: pattern/file/destinatari/**
alwaysApply: false
---

# Le vostre linee guida tecniche qui

Parametri YAML fondamentali

• globs: un pattern di selezione file (come src/app/**/*.tsx o backend/**/*.py). Con alwaysApply: false, la regola viene aggiunta quando un file corrispondente è nel contesto.

• alwaysApply: impostare a true soltanto per convenzioni valide per tutto il repository (formato dei commit o licenze). Mantenere il valore a false per le regole specifiche dei singoli framework.

• description: illustra l'ambito della regola, aiutando Cursor a selezionarla automaticamente durante le ricerche con @ nella chat.

Se volete approfondire il confronto tra un editor evoluto come Cursor e un agente autonomo da riga di comando, consultate la nostra guida su Claude Code vs Cursor.

1. Migliori regole Cursor per Next.js (App Router)

Salvate questo file con il nome .cursor/rules/nextjs.mdc. Descrive convenzioni dell'App Router, separazione dei dati server/client e caricamento nei Server Components; verificatele rispetto alla versione di Next.js installata e ai controlli del progetto.

---
description: Standard per Next.js App Router e Server Components
globs: src/app/**/*.{ts,tsx},app/**/*.{ts,tsx}
alwaysApply: false
---

# Regole architetturali Next.js

## Separazione tra componenti server e client
- Adottare i React Server Components (RSC) come scelta di default. Aggiungere "use client" solo se il componente necessita di useState, useEffect, gestori eventi del browser o API window.
- Mantenere i componenti client alle estremità dell'albero di rendering. Passare i dati dai Server Components sotto forma di props serializzabili.
- Vietare categoricamente l'importazione di librerie riservate al server (client database, variabili d'ambiente protette) all'interno di componenti client.

## Recupero dati e mutazioni
- Recuperare i dati direttamente nei Server Components usando async/await. Evitare l'impiego di useEffect per le chiamate ai dati.
- Utilizzare le Server Actions di Next.js per l'invio di moduli e le modifiche di stato. Raggruppare le azioni nel componente o nel file `actions.ts` con la direttiva "use server" all'inizio del file.
- Validare tassativamente i dati in ingresso delle Server Actions tramite schemi Zod prima di interagire con il database.
- Invalidare e aggiornare le rotte in cache dopo una mutazione riuscita tramite `revalidatePath()` o `revalidateTag()`.

## Navigazione e gestione rotte
- Utilizzare `next/link` per i collegamenti interni; evitare tag `<a>` generici per i percorsi applicativi.
- Leggere i parametri di ricerca tramite props di pagina o `useSearchParams()`. Proteggere con blocchi Suspense i componenti che leggono i parametri di ricerca.

2. Migliori regole Cursor per React e TypeScript

Salvate questo file come .cursor/rules/react-typescript.mdc. Richiede tipi precisi, export con nome e uniformità nell'interfaccia; TypeScript, lint e revisione devono verificarne il rispetto.

---
description: Standard per React e TypeScript
globs: **/*.{ts,tsx}
alwaysApply: false
---

# Linee guida per React e TypeScript

## Precisione dei tipi TypeScript
- Non utilizzare mai il tipo `any`. Usare `unknown` per input arbitrari e restringere con type guards.
- Preferire `interface` per descrivere oggetti e props di componenti. Impiegare `type` per unioni e mappature.
- Assegnare tipi di ritorno espliciti a tutte le firme di funzione esportate oltre il perimetro del modulo.
- Evitare asserzioni non-null (`!`). Gestire i casi nulli o indefiniti con l'operatore optional chaining (`?.`) o valori di fallback.

## Architettura dei componenti
- Impiegare esclusivamente export con nome: `export function UserProfile(...)`. Non usare `export default`.
- Definire l'interfaccia delle props appena sopra il componente adottando il modello `<NomeComponente>Props`.
- Destrutturare le props direttamente nella firma: `function Button({ variant = "primary", children }: ButtonProps)`.
- Estrarre la logica articolata in custom hook dedicati con prefisso `use`.

## Stili e accessibilità
- Utilizzare direttamente le classi di utilità Tailwind CSS. Evitare stili inline `style={{ ... }}`.
- Aggregare le classi condizionali mediante funzioni di supporto come `cn()` (clsx + tailwind-merge).
- Curare l'accessibilità degli elementi interattivi (`aria-label`, navigabilità da tastiera).

3. Migliori regole Cursor per Python e FastAPI

Salvate questo file con il nome .cursor/rules/fastapi.mdc. Richiede rotte asincrone non bloccanti, modelli Pydantic v2 precisi e dependency injection controllata; controllate il codice generato e coprite il comportamento con test.

---
description: Standard per Python FastAPI e Pydantic
globs: **/*.py,backend/**/*.py,api/**/*.py
alwaysApply: false
---

# Regole di programmazione FastAPI

## Gestori di rotta asincroni
- Definire qualsiasi endpoint che esegue operazioni di I/O con `async def`.
- Non eseguire chiamate sincrone bloccanti (come `requests.get()`, `time.sleep()` o driver database tradizionali) nelle rotte asincrone.
- Adottare `httpx.AsyncClient` per le chiamate HTTP e driver asincroni dedicati per il database.

## Modelli Pydantic v2
- Suddividere i payload in ingresso, le risposte e le rappresentazioni delle tabelle in modelli distinti.
- Assegnare nomi chiari e univoci: `UserCreateRequest`, `UserUpdatePayload`, `UserResponse`.
- Impostare sempre `from_attributes = True` all'interno di `model_config` quando si elaborano entità ORM.
- Usare `Field()` con vincoli espliciti (`min_length`, `gt`, `le`) e descrizioni con esempi.

## Dependency Injection e sicurezza
- Fornire le sessioni del database e i dati di sessione mediante il costrutto `Depends()` di FastAPI.
- Racchiudere le operazioni sul database in context manager asincroni per garantire la chiusura delle connessioni in caso di errore.
- Generare eccezioni con `HTTPException` e codici di stato espliciti, evitando dizionari di errore non strutturati.

Allineamento delle regole di Cursor con agenti da terminale

Se nel vostro team impiegate anche Claude Code per refactoring pesanti o cicli di test via shell, è consigliabile mantenere coordinate le direttive del repository. Mentre Cursor legge i file .cursor/rules/*.mdc, Claude Code si basa su CLAUDE.md e pacchetti di skill modulari.

Scoprite come organizzare routine di test e review automatiche nel nostro articolo sulle migliori skill Claude Code per sviluppatori, o consultate il catalogo completo di skill tecniche verificate.

Come testare e convalidare le regole di Cursor

Completata la configurazione in .cursor/rules/, verificate che il sistema le applichi correttamente:

1. Controllare la corrispondenza dei glob: aprite un file interessato (ad esempio src/app/page.tsx).

2. Aprire la chat di Cursor (Cmd+L): controllate il badge del contesto nella parte inferiore della finestra. nextjs.mdc dovrà figurare tra le regole attive del progetto.

3. Invocare una regola manualmente: digitate @ nella chat, selezionate Rules e scegliete il file desiderato.

4. Verificare con Composer (Cmd+I): chiedete a Cursor di generare un nuovo componente e controllate che il diff rispetti i criteri definiti (export con nome e tipizzazione rigorosa).

Errori da evitare nelle regole di Cursor

Per conservare rapidità ed efficacia nel supporto di Cursor, evitate questi quattro errori frequenti:

1. Documenti troppo estesi: non inserite l'intero regolamento aziendale in un singolo file. Mantenete ogni .mdc al di sotto delle 80 righe con indicazioni mirate.

2. Ambito non definito: senza globs non c'è associazione automatica per pattern di file; controllate il tipo di regola e alwaysApply per stabilire quando deve entrare nel contesto.

3. Indicazioni contrastanti: eliminate qualsiasi incongruenza tra il file .cursorrules principale e le regole per modulo.

4. Principi indefiniti: rimpiazzate espressioni generiche come "scrivi codice ordinato" con vincoli verificabili come "limitare le funzioni a 40 righe di codice".

Tabella di sintesi

Impostando file modulari .cursor/rules/*.mdc, fornite all'agente di Cursor il contesto della vostra architettura di sviluppo. Verificate che le regole siano attive e che il codice generato le rispetti tramite test e revisione.