Il problema: l'agente parte prima di aver capito, e due agenti si pestano i piedi
Hai chiesto all'agente di aggiungere l'accesso con Google. Dopo venti minuti hai un codice che funziona, ma ha toccato un middleware che non doveva toccare e ha aggiunto una dipendenza che non volevi. Il difetto non è nel codice: l'agente ha cominciato a scrivere quando non aveva ancora capito che cosa chiedevi. E se provi a rimediare lanciando tre agenti insieme, ne nasce un secondo: se due di loro modificano lo stesso file nella stessa cartella, uno sovrascrive il lavoro dell'altro.
Questo articolo tratta i due rimedi che Cursor offre, e che si compongono. Plan Mode mette un piano da rivedere fra la tua richiesta e il primo file modificato. Il lavoro in parallelo, che nelle prime versioni si chiamava Background Agents, oggi si articola in tre strade diverse (worktree locali, agenti nel cloud e subagenti), e conviene saperle distinguere perché hanno costi e rischi molto diversi. Vengono dopo l'Agent Mode e le regole di progetto: li do per noti.
Una precisazione sul metodo, perché in questa serie conta. Cursor non era installato dove ho scritto: tutto ciò che riguarda i pulsanti, i menu e il comportamento dell'agente viene dalla documentazione ufficiale letta il 2026-11-13 ed è dichiarato «non provato qui». Ciò che si può eseguire senza l'editor, cioè git, i file di configurazione e uno script di controllo del piano, l'ho eseguito davvero e riporto le uscite vere.
Che cosa è cambiato rispetto alla versione precedente di questo articolo
Il testo che stava qui prima descriveva una funzione chiamata «Mission Control», un tetto di «otto agenti» in
parallelo, scorciatoie come Cmd+Shift+N e un'impostazione git.showCursorWorktrees. Nella
documentazione e nel changelog che ho aperto oggi non ho trovato nessuna di queste cose, e quindi sono uscite.
Sono cambiati anche i nomi: la pagina dei Cloud Agents riporta, nella sezione «Naming History», che erano «formerly
called Background Agents». E il quadro è più largo: la finestra degli agenti (Agents Window) è disponibile con
Cursor 3, rilasciato il 2 aprile 2026 secondo la documentazione. Se leggi in giro guide che citano i nomi vecchi,
verifica che descrivano ancora il prodotto.
Plan Mode: far scrivere un piano prima del codice
Si attiva con Shift+Tab dal campo di input della chat, che ruota fra le modalità; Cursor può anche suggerirlo da solo quando riconosce parole chiave di un compito complesso. La documentazione descrive il flusso in cinque passi, e qui l'ordine conta davvero: il piano arriva dopo le domande e la lettura del codice, e l'esecuzione solo dopo la tua revisione.
- L'agente ti fa domande per chiarire i requisiti.
- Esplora il codice per raccogliere il contesto pertinente.
- Produce un piano di implementazione dettagliato.
- Tu lo rivedi e lo modifichi, in chat o direttamente nei file Markdown.
- Quando sei pronto, avvii la costruzione del piano.
Il passo che fa la differenza è il quarto. Un piano è un testo che puoi correggere in trenta secondi, mentre un errore di impostazione scoperto dopo l'esecuzione costa un intervento su molti file. Per questo la documentazione dà un consiglio controintuitivo: se l'agente ha costruito qualcosa di diverso da ciò che volevi, non inseguirlo con prompt successivi. Annulla le modifiche, rendi il piano più preciso e rilancialo. Rifare dal piano è spesso più rapido che riparare un'esecuzione già deviata, e produce un risultato più pulito.
Dove finisce il piano, e perché conviene salvarlo nel repository
Per impostazione predefinita i piani si salvano nella cartella home dell'utente, quindi fuori dal progetto. Il pulsante «Save to workspace» li sposta nell'area di lavoro, e la documentazione ne indica tre motivi: riferimento futuro, condivisione con il team, documentazione. Il valore predefinito ha una conseguenza che nessuno ti segnala: un piano non salvato nel workspace non finisce nel commit, e il collega che deve rivedere la tua pull request non sa che cosa avevi concordato con l'agente. Se il piano è una decisione di progetto, salvalo e versionalo.
Come si presenta un piano, e che cosa controllare
La documentazione non fissa un formato per il piano: è Markdown libero, e la struttura dipende dal modello e dalla tua richiesta. Il blocco qui sotto è quindi un esempio costruito da me, non l'uscita di Cursor. Serve a mostrare dove un piano sbaglia più facilmente: cita file con il loro percorso, e quei percorsi possono essere inventati.
# Piano: OAuth2 con Google
## Analisi
- Il servizio è in `src/auth/auth.service.ts`, la guardia in `src/auth/auth.guard.ts`.
- Il JWT è gestito in `src/middleware/jwt.middleware.ts`.
## Step
1. Aggiungere la dipendenza in `package.json`.
2. Creare `src/auth/strategies/google.strategy.ts` (file nuovo, non esiste ancora).
In questo piano di prova il servizio e la guardia esistono, mentre il middleware JWT è un percorso che l'agente ha supposto, e l'ultimo file è dichiarato nuovo. Controllare a occhio una ventina di percorsi è noioso, e la noia è esattamente il momento in cui si approva senza leggere. Meglio delegare la parte meccanica a uno script.
"""Controlla che i percorsi citati in un piano esistano davvero nel repository."""
import re
import sys
from pathlib import Path
ESTENSIONI = r"(?:ts|tsx|js|json|md|mdc|py|java|html|css|sql|yml|yaml)"
# un percorso = almeno una barra e un'estensione nota, dentro apici inversi
MODELLO = re.compile(r"`([\w@./-]+/[\w@.-]+\." + ESTENSIONI + r")`")
def percorsi_citati(testo: str) -> list[str]:
visti: list[str] = []
for m in MODELLO.finditer(testo):
p = m.group(1)
if p not in visti:
visti.append(p)
return visti
def main(piano: Path, radice: Path) -> int:
mancanti = []
for p in percorsi_citati(piano.read_text(encoding="utf-8")):
esiste = (radice / p).exists()
print(("ok " if esiste else "MANCANTE ") + p)
if not esiste:
mancanti.append(p)
return 1 if mancanti else 0
if __name__ == "__main__":
sys.exit(main(Path(sys.argv[1]), Path(sys.argv[2])))
Lo script cerca, dentro apici inversi, ogni stringa che contiene una barra e termina con un'estensione nota, e
verifica che il file esista a partire dalla radice del repository. La lista delle estensioni è nella costante
ESTENSIONI: se il tuo progetto usa .vue o .go, aggiungili, perché i percorsi
con altre estensioni non vengono visti. Il codice di uscita vale 1 se manca almeno un file, quindi puoi metterlo in
uno script di controllo. L'ho eseguito su un repository di prova che contiene solo i tre file veri
(python3 -I controlla_piano.py piano.md repo, Python 3.14, due esecuzioni con uscita identica):
ok src/auth/auth.service.ts
ok src/auth/auth.guard.ts
MANCANTE src/middleware/jwt.middleware.ts
MANCANTE src/auth/strategies/google.strategy.ts
Il controllo segnala due percorsi mancanti, ma uno dei due è un falso allarme: il file
google.strategy.ts è dichiarato nuovo, e il piano lo dice. Il vero problema è il middleware JWT,
che l'agente ha citato senza che esista. Lo script non sa distinguere i due casi, e non deve: il suo compito è
portarti a leggere proprio quella riga. Non dimostra che il resto del piano sia giusto, perché un percorso
esistente può comunque essere il file sbagliato da modificare.
Quando Plan Mode non serve
La documentazione lo consiglia per quattro situazioni: funzionalità complesse con più approcci validi, compiti che toccano molti file o sistemi, requisiti poco chiari da esplorare, decisioni architetturali da rivedere prima. Per un cambio piccolo o per un compito che hai già fatto molte volte, andare dritti in modalità Agent va bene. Un criterio pratico che ne ricavo: se sai già dire in una frase quali file cambieranno, il piano non ti dà nulla; se non lo sai, il piano è il modo più economico di scoprirlo.
Tre modi di lavorare in parallelo, che non vanno confusi
La parola «agente in background» oggi copre cose diverse. Sono tre strade, e la prima domanda da farsi è dove gira il lavoro e dove finiscono i file.
- Worktree locale: l'agente lavora sul tuo computer, ma in una copia separata del repository con un proprio ramo.
- Cloud Agent: l'agente lavora su una macchina virtuale isolata nel cloud, clona il repository, lavora su un ramo e vi consegna le modifiche.
- Subagente: un assistente specializzato con una finestra di contesto propria, lanciato dall'agente principale, in primo piano o in background.
Il discrimine è l'isolamento, e ognuno ne offre uno diverso. Il worktree isola i file e usa le tue risorse e la tua rete. Il Cloud Agent isola anche la macchina, ma gli devi affidare repository e segreti. Il subagente isola solo il contesto, cioè la memoria della conversazione, e lavora sugli stessi file dell'agente che lo ha lanciato: non protegge dai conflitti. Chi lancia «tre agenti in parallelo» pensando che siano tutti la stessa cosa ottiene sorprese su uno di questi tre piani.
Worktree: la tecnologia è git, e si prova senza Cursor
Un git worktree è una seconda cartella di lavoro collegata allo stesso repository, con il proprio ramo
attivo. Non è un clone: è associata allo stesso repository, con metadati propri, e la documentazione di git
precisa che i riferimenti in refs/ sono condivisi mentre HEAD è propria di ciascun worktree. Cursor lo usa per dare a ogni agente una cartella sua. La documentazione precisa dove: l'interfaccia
dei worktree è disponibile nella Agents Window, mentre nell'editor si usano i comandi /worktree (per
far svolgere un'intera chat in un checkout separato) e /best-of-n, che lancia lo stesso compito su più
modelli, ciascuno nel suo worktree, senza riunire i risultati: scegli il vincitore e lo porti nel tuo
checkout con /apply-worktree.
Il punto delicato è che il parallelismo non elimina i conflitti: li sposta al momento dell'unione dei rami. Lo
script seguente lo mostra con git puro. Crea un repository temporaneo con due worktree, fa aggiungere a due
«agenti» una rotta nello stesso punto dello stesso file, e poi unisce i rami. Non apre porte e non scrive nel
tuo repository: lavora in una cartella creata con mktemp -d che cancella alla fine.
#!/usr/bin/env bash
set -euo pipefail
base=$(mktemp -d)
cd "$base"
git init -q -b main progetto && cd progetto
git config user.email prova@example.com && git config user.name Prova
mkdir src
printf 'export const rotte = [\n "home",\n];\n' > src/rotte.ts
printf 'export const titolo = "App";\n' > src/titolo.ts
git add . && git commit -q -m "base"
git worktree add -q ../agente-a -b feature/a
git worktree add -q ../agente-b -b feature/b
echo "== worktree attivi (hash tolto)"
git worktree list | awk '{print $1, $NF}' | sed "s#$base#<tmp>#"
# l'agente A aggiunge una rotta e tocca un file suo
( cd ../agente-a && sed -i 's/ "home",/ "home",\n "login",/' src/rotte.ts && git commit -qam "a: login" )
# l'agente B aggiunge un'altra rotta nello stesso punto
( cd ../agente-b && sed -i 's/ "home",/ "home",\n "profilo",/' src/rotte.ts && printf 'export const titolo = "App B";\n' > src/titolo.ts && git commit -qam "b: profilo" )
echo "== merge di A (pulito)"
git merge -q --no-edit feature/a && echo ok
echo "== merge di B (stesso file)"
git merge --no-edit feature/b 2>&1 | sed 's/^/ /' || true
echo "== file in conflitto"
git diff --name-only --diff-filter=U
echo "== il file src/rotte.ts"
cat src/rotte.ts
git merge --abort
cd / && rm -rf "$base"
L'ho eseguito con git 2.53.0 due volte, con uscita identica (i messaggi di git sono in italiano perché la macchina è localizzata; gli hash non compaiono perché li ho tolti dall'elenco):
== worktree attivi (hash tolto)
<tmp>/progetto [main]
<tmp>/agente-a [feature/a]
<tmp>/agente-b [feature/b]
== merge di A (pulito)
ok
== merge di B (stesso file)
Merge automatico di src/rotte.ts in corso
CONFLITTO (contenuto): conflitto di merge in src/rotte.ts
Merge automatico fallito; risolvi i conflitti ed esegui il commit
del risultato.
== file in conflitto
src/rotte.ts
== il file src/rotte.ts
export const rotte = [
"home",
<<<<<<< HEAD
"login",
=======
"profilo",
>>>>>>> feature/b
];
Leggi l'uscita nell'ordine. Il primo ramo si fonde senza problemi, il secondo fallisce perché entrambi hanno
modificato la stessa riga di src/rotte.ts. Git ha lasciato nel file i marcatori
<<<<<<< e >>>>>>> e la scelta fra le due versioni spetta a
te. Questo è il caso più comune, ed è il motivo per cui prima di lanciare agenti paralleli conviene guardare il
piano e chiedersi quali file toccheranno: un file «centrale», come un elenco di rotte o un indice, è il punto dove
i conflitti nascono. Lo script ha anche un limite: simula gli agenti con due comandi sed, e non
dice nulla su come si comporta un vero agente davanti a un conflitto.
Preparare il worktree: .cursor/worktrees.json
Un worktree nuovo ha solo i file tracciati da git: mancano node_modules e i file di ambiente. Cursor
legge un file .cursor/worktrees.json (prima nel percorso del worktree, poi nella radice del progetto)
con comandi da eseguire dopo la creazione. Le chiavi sono tre: setup-worktree-unix per macOS e Linux,
setup-worktree-windows, e setup-worktree come ripiego per tutti i sistemi. Ognuna accetta un
array di comandi shell, eseguiti in sequenza nel worktree, oppure il percorso di uno script relativo al file. Su
Unix la chiave specifica ha la precedenza sul ripiego.
{
"setup-worktree-unix": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env"
],
"setup-worktree": [
"npm ci"
]
}
Il file è JSON valido (l'ho caricato con Python), ma l'effetto dentro Cursor non è stato provato qui. La variabile
ROOT_WORKTREE_PATH compare negli esempi della documentazione come percorso del checkout principale,
da cui copiare il .env. Due cautele: la documentazione sconsiglia di collegare con un link simbolico le
dipendenze, perché può causare problemi nel worktree principale, e suggerisce un gestore di pacchetti veloce come
pnpm. E un cp del .env sposta i tuoi segreti in un'altra cartella: va bene sul tuo
computer, ma ricordalo se quella cartella viene poi copiata o sincronizzata altrove. Per capire perché un setup non
riesce, apri il pannello Output e scegli «Worktrees Setup».
La pulizia automatica dei worktree, e che cosa può cancellare
I worktree occupano disco, e Cursor ne tiene un numero massimo: la documentazione indica, a partire da Cursor 3.5,
due impostazioni a livello di macchina, cursor.worktreeMaxCount (tetto di 25 worktree per computer, sommati
su tutti i progetti) e cursor.worktreeCleanupIntervalHours (ogni quante ore controllare; l'esempio della
pagina usa 6). Quando si supera il tetto, i più vecchi vengono rimossi. Il dettaglio da non perdere è nella stessa
pagina: la pulizia riscopre tutti i worktree, anche quelli creati fuori dal gestore con git worktree add,
e li considera eliminabili. Se in un worktree hai lavoro non committato, non fidarti del fatto che «l'ho creato io
a mano»: committa o spostalo.
Cloud Agent: un'altra macchina, con altri rischi
Un Cloud Agent usa gli stessi principi dell'agente locale ma gira in una macchina virtuale isolata, con un ambiente di sviluppo completo: repository clonati, dipendenze, segreti, comandi di avvio e accesso alla rete. Può costruire e provare il software, e produrre artefatti (schermate, video, log) allegati alla pull request. Il vantaggio dichiarato è che non serve il tuo computer acceso e connesso, e che puoi avviarne quanti vuoi in parallelo. Il prezzo di questo vantaggio sta in tre punti, che la documentazione dichiara e che conviene mettere in fila prima di adottarlo.
- Serve un piano che li includa: Premium e superiori, Teams, Enterprise o un piano a pagamento precedente; Free e Plus no.
- Un amministratore dell'account deve collegare il provider del codice (GitHub, GitLab, Bitbucket Cloud o Azure DevOps), e tu devi avere permessi di lettura e scrittura sul repository.
- Il consumo si somma all'uso del piano, al prezzo del modello scelto, e al primo utilizzo ti viene chiesto un limite di spesa.
Non riporto cifre di prezzo: cambiano, e la pagina dei prezzi va letta il giorno in cui decidi. Il segnale che ne ricavo è un altro: il costo di un agente nel cloud è proporzionale al tempo e al modello, quindi il limite di spesa non è una formalità. Lancia il primo agente su un compito piccolo e guarda il consumo prima di lanciarne cinque.
L'ambiente conta più del prompt
La documentazione insiste su un punto che ribalta il modo di pensarci: un agente che scrive codice ma non può eseguire
i test né raggiungere i servizi non chiude il ciclo del suo lavoro. L'ambiente si configura con una procedura guidata
dall'agente, con uno snapshot salvato oppure con un Dockerfile indicato in .cursor/environment.json. Qui non ho
provato nessuna delle tre: ti rimando alla pagina di setup per i campi esatti. Un compito di prova ragionevole è
far girare i test esistenti, perché se l'agente non riesce a farlo, quasi certamente l'ambiente è incompleto.
Segreti, MCP e hook nel cloud: che cosa vede l'agente
Qui il rischio diventa concreto. I segreti si inseriscono nel pannello del dashboard e vengono iniettati all'avvio
dell'agente: un agente già in esecuzione non vede i segreti aggiunti dopo. Per i server MCP il trasporto cambia
ciò che l'agente può leggere. Con HTTP, raccomandato dalla documentazione, la configurazione non è mai presente nella
macchina virtuale e le chiamate passano dal backend di Cursor; con stdio il server gira dentro la macchina, quindi
l'agente può accedere alla sua configurazione e alle sue variabili d'ambiente. Se un server richiede una chiave
potente, usare stdio nel cloud significa consegnarla all'agente. SSE e mcp-remote, secondo la stessa
pagina, non sono supportati per i server personalizzati.
Gli hook, argomento dell'articolo successivo, funzionano
anche nel cloud: gli agenti eseguono gli hook basati su comando definiti in .cursor/hooks.json del
repository, mentre quelli del tuo ~/.cursor/hooks.json non sono disponibili, perché la macchina
virtuale non vede la tua cartella home. Un controllo che vive solo nella tua configurazione personale, dunque,
non protegge il lavoro che gira nel cloud: se è una regola di progetto, deve stare nel repository.
Dove si avviano
La documentazione elenca molti punti di ingresso: il selettore «Cloud» nell'app desktop, l'interfaccia web e
l'app per iPhone, il comando @cursor in Slack, in un commento di GitHub o Bitbucket e in Linear, più
l'API. Nella Agents Window esistono anche /in-cloud, per affidare un compito a un subagente cloud, e
/autopilot per una pull request. La comodità di scrivere @cursor in un commento rende facile lanciare lavoro senza che nessuno tenga d'occhio il costo.
Decidi chi può farlo.
I subagenti: contesto separato, non file separati
Un subagente ha una finestra di contesto propria, riceve dal principale un prompt con le informazioni necessarie
(non vede la conversazione precedente) e restituisce un messaggio finale. Può girare in primo piano, e allora
blocca il principale finché non ha finito, o in background, e allora ritorna subito e lavora per conto suo. Cursor ne
include due per impostazione predefinita, Explore (cerca e analizza il codice, con un modello più veloce) e
Browser (controlla il browser tramite MCP), pensati per le operazioni che producono molto output
intermedio e rischiano di riempire il contesto principale. Puoi definirne di tuoi come file Markdown con
intestazione YAML in .cursor/agents/ (per il progetto) o in ~/.cursor/agents/ (per te), e
la documentazione dice che a parità di nome vince la cartella .cursor/ su .claude/ e .codex/.
La regola d'oro è nella tabella di confronto della stessa pagina: un compito di una sola azione, come formattare o generare un changelog, è una skill, non un subagente. Il subagente serve quando il contesto è troppo grande o i filoni sono davvero indipendenti. E ricorda che condivide i file con il genitore: se due subagenti modificano lo stesso file, il conflitto è nella stessa cartella e non lo vedi come marcatore git ma come sovrascrittura.
Un metodo per decidere, su un esempio concreto
Immagina un'applicazione Angular di cui sei l'unico manutentore e tre compiti: correggere la validazione di un modulo, aggiungere un filtro a una tabella, aggiornare una libreria con modifiche incompatibili in tre moduli. È uno scenario costruito per questo articolo, senza dati reali. Il primo compito è piccolo e lo fai in modalità Agent. Il secondo tocca un solo componente: un worktree locale basta, e puoi continuare a lavorare nel tuo checkout. Il terzo è il caso in cui il piano rende: lo fai scrivere in Plan Mode, controlli con lo script che i file citati esistano, lo salvi nel workspace e poi decidi se affidare un modulo per agente. Se i tre moduli condividono un file di configurazione, quel file si modifica per primo e a mano, e solo dopo si parallelizza. La tua attenzione si sposta dal digitare al decidere in che ordine e con quale confine far lavorare gli agenti.
Che cosa sai fare adesso
Sai quando usare Plan Mode e quando saltarlo, sai che il piano va salvato nel repository se è una decisione e controllato sui percorsi prima di approvarlo, e sai distinguere tre forme di parallelismo che hanno isolamenti diversi. Hai visto con git, in modo riproducibile, perché due agenti sullo stesso file producono un conflitto, e sai che un Cloud Agent richiede un piano a pagamento, un ambiente configurato, un limite di spesa e una scelta consapevole su segreti e trasporto MCP. Quello che non hai ancora è il modo di fermare un'azione pericolosa prima che accada: è il tema degli hook, nell'articolo successivo.
Domande frequenti
Come si attiva Plan Mode in Cursor?
Premendo Shift+Tab dal campo di input della chat, che ruota fra le modalità, oppure dal selettore di modalità. Cursor può anche suggerirlo quando rileva parole chiave di un compito complesso. Dove si trovi il piano e come si salvi lo spiega la documentazione di Plan Mode.
I Background Agents esistono ancora?
Il nome è cambiato: la documentazione li chiama Cloud Agents e nella sezione «Naming History» dice che erano chiamati Background Agents. Girano in una macchina virtuale nel cloud, e servono un piano che li includa e un limite di spesa.
Due agenti in parallelo possono modificare lo stesso file?
Con due worktree separati sì, ma il conflitto si presenta quando unisci i rami, come mostra la prova con git di questo articolo. Con due subagenti nella stessa cartella no: condividono i file e uno può sovrascrivere l'altro. Per questo conviene verificare prima quali file toccheranno.
Gli hook del mio computer valgono anche per gli agenti nel cloud?
No: gli hook di ~/.cursor/hooks.json non sono disponibili nel cloud, perché la macchina virtuale non vede la tua cartella home. Valgono quelli di .cursor/hooks.json nel repository e, sui piani Enterprise, quelli di team e aziendali.
Nella stessa serie trovi anche Cursor IDE: Guida Completa per Developer.
Fonti
- Cursor, documentazione: Plan Mode - flusso in cinque passi, attivazione con Shift+Tab, salvataggio dei piani, ripartire dal piano, consultata il 2026-11-13
- Cursor, documentazione: Cloud Agents - macchine virtuali, requisiti di piano, punti di avvio, supporto di MCP e hook, nome precedente Background Agents, consultata il 2026-11-13
- Cursor, documentazione: Cloud Agent capabilities - trasporti MCP HTTP e stdio, segreti redatti, artefatti, consultata il 2026-11-13
- Cursor, documentazione: Worktrees -
.cursor/worktrees.json,/worktree,/best-of-n, pulizia automatica, consultata il 2026-11-13 - Cursor, documentazione: Agents Window - disponibilità con Cursor 3 del 2 aprile 2026,
/in-cloude/autopilot, consultata il 2026-11-13 - Cursor, documentazione: Subagents - contesto separato, modalità foreground e background, subagenti predefiniti, cartelle dei subagenti, consultata il 2026-11-13
- Git, documentazione: git-worktree - worktree principale e collegati, riferimenti condivisi e HEAD per worktree, consultata il 2026-11-13
Lo script wt.sh è stato eseguito con git 2.53.0 e controlla_piano.py con Python 3.14, ciascuno due volte con uscita identica, in cartelle temporanee fuori dal repository. Il file worktrees.json è stato caricato come JSON ma non provato in Cursor, che non era installato: come ogni passaggio dentro l'editor, è uno schema da adattare.

Commenti
Caricamento commenti...
Accedi per commentare