Il problema: delegare un compito intero senza perderne il controllo
Immagina di scrivere all'Agent di Cursor «aggiungi la paginazione all'elenco degli ordini» e di trovare, dopo qualche minuto, molti file
modificati, una dipendenza nuova in package.json e un test che prima passava e ora è stato riscritto. Il
lavoro può anche essere buono, ma non sai dirlo, perché non avevi detto che cosa dovesse toccare né come si
verifica che sia finito. L'Agent è lo strumento che fa funzionare l'editor «a un comando»: la differenza fra un
risultato utile e un pomeriggio di revisione sta quasi tutta in tre decisioni che prendi prima, durante e dopo il
suo lavoro. Prima, come descrivi il compito. Durante, quali azioni può compiere senza chiederti il permesso. Dopo,
come controlli che abbia fatto soltanto ciò che gli avevi chiesto.
Qui ti spiego tutte e tre sulla documentazione ufficiale letta il 2026-11-13, con due strumenti che ho scritto ed eseguito: un controllo di perimetro delle modifiche e un file di permessi. Cursor non era installato sulla macchina su cui scrivo: ciò che accade dentro l'editor è descritto dalla documentazione e non l'ho provato. Se non conosci ancora strumenti e modalità, leggi prima la guida di apertura e quella sulle regole di progetto, che qui diamo per note.
Che cosa è l'Agent, secondo la documentazione
Secondo la documentazione, un agente è fatto di tre componenti: le istruzioni, cioè il prompt di sistema più le tue regole, gli strumenti per cercare e modificare codice ed eseguire comandi, e il modello che scegli per il compito. Cursor ottimizza istruzioni e strumenti per ogni modello supportato. Il punto che interessa a chi lavora è che l'agente non indovina il contenuto dei file: li cerca e li legge, applica le modifiche, esegue i comandi nel terminale e ne legge l'esito, può farti domande mentre continua a lavorare e, nei casi che lo richiedono, usa un browser per provare un'applicazione. La stessa pagina dichiara che non c'è un limite al numero di chiamate agli strumenti in un compito: un compito vago può quindi girare a lungo, ed è un motivo in più per definirlo bene.
Per i compiti che richiedono molta ricerca, l'Agent può avviare dei sottoagenti, ciascuno con la propria finestra di contesto. Quello di esplorazione cerca nel codice con un modello più veloce ed esegue molte ricerche in parallelo, restituendo all'agente principale solo le conclusioni; quello del browser filtra il rumore delle schermate. Il vantaggio dichiarato è il contesto: le ricerche voluminose non riempiono la conversazione principale. Puoi chiedere esplicitamente di usarli, per esempio «usa un sottoagente per trovare tutti i punti in cui validiamo l'input». Gli agenti in background e i piani lunghi sono materia del quarto articolo.
Prima di partire: albero pulito e compito verificabile
Una modifica dell'Agent finisce subito su disco, tranne che per i file di configurazione, che chiedono consenso.
Se prima di partire hai modifiche tue non committate, nella differenza non distingui più il tuo lavoro da quello
dell'agente. Il primo gesto è quindi un albero di lavoro pulito, e il secondo è sapere che cosa ti aspetti di
trovare dopo. Lo strumento che segue automatizza entrambi: con il comando prima si rifiuta di
proseguire se ci sono file modificati, con il comando dopo elenca i file cambiati e segnala quelli fuori
da un perimetro che dichiari con dei pattern. Usa git status --porcelain, il formato che Git
definisce stabile fra le versioni e adatto agli script, e glob.translate per i pattern.
"""Controllo di perimetro prima e dopo un compito affidato a un agente.
prima: esce con 1 se l'albero di lavoro non e' pulito.
dopo: elenca i file cambiati e segnala quelli fuori dai percorsi consentiti.
"""
import glob
import re
import subprocess
import sys
def git(*args):
return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout
def cambiati():
righe = git("status", "--porcelain", "--untracked-files=all").splitlines()
return [(r[:2].strip() or "?", r[3:]) for r in righe]
def consentito(percorso, modelli):
return any(re.fullmatch(glob.translate(m, recursive=True), percorso) for m in modelli)
def main(argv):
comando, modelli = argv[0], argv[1:]
voci = cambiati()
if comando == "prima":
if voci:
print(f"albero NON pulito: {len(voci)} file modificati, committa o metti da parte prima di partire")
return 1
print("albero pulito: ogni differenza che vedrai dopo sara' dell'agente")
return 0
fuori = [(s, p) for s, p in voci if not consentito(p, modelli)]
for stato, percorso in voci:
segno = "FUORI" if (stato, percorso) in fuori else "ok "
print(f"{segno} {stato:2} {percorso}")
print(f"{len(voci)} file cambiati, {len(fuori)} fuori dal perimetro")
return 2 if fuori else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
Nella funzione cambiati() l'opzione --untracked-files=all serve a vedere anche i file nuovi
uno per uno: senza, Git mostrerebbe una cartella nuova come un'unica voce e un file creato dall'agente in una
cartella inattesa passerebbe inosservato. La funzione consentito() confronta il percorso con i
pattern; il codice di uscita 2 di dopo è pensato per distinguere «ci sono file fuori perimetro» da un
errore del programma.
Per provarlo senza coinvolgere un agente ho simulato io le modifiche: un repository temporaneo con un servizio, un
componente e un package.json, poi tre cambiamenti a mano, due dentro la cartella degli ordini e uno
che tocca package.json, esattamente il tipo di sconfinamento descritto all'inizio. Lo script
scenario.sh costruisce il repository, lancia i controlli e lo elimina.
#!/bin/bash
set -u
D=$(mktemp -d)
cd "$D" || exit 1
git init -q .
git config user.email prova@example.invalid; git config user.name prova
mkdir -p src/app/orders
echo "export class OrdersService {}" > src/app/orders/orders.service.ts
echo "export class OrdersComponent {}" > src/app/orders/orders.component.ts
echo '{"name":"negozio"}' > package.json
git add . && git commit -q -m base
P=$HOME/prove/perimetro.py
echo "--- prima, albero pulito"; python3 -I $P prima; echo "exit $?"
echo "// pagina" >> src/app/orders/orders.service.ts
echo "export const PAGE = 20;" > src/app/orders/orders.pagination.ts
echo '{"name":"negozio","dependencies":{"x":"1"}}' > package.json
echo "--- dopo, perimetro src/app/orders/**"; python3 -I $P dopo 'src/app/orders/**'; echo "exit $?"
echo "--- prima, albero sporco"; python3 -I $P prima; echo "exit $?"
rm -rf "$D"
L'uscita mostra le tre situazioni: albero pulito, modifiche dentro il perimetro con un file fuori, e il rifiuto di
ripartire con l'albero sporco. Le due righe che contano sono quelle del package.json marcato
FUORI e dell'exit 2: in un compito reale quella riga ti dice che l'agente ha cambiato le dipendenze,
e a quel punto decidi tu se tenerle. I codici sono quelli del programma, non di Cursor.
# Uscita di scenario.sh (Python 3.14.4, git 2.53.0, due esecuzioni identiche)
# --- prima, albero pulito
# albero pulito: ogni differenza che vedrai dopo sara' dell'agente
# exit 0
# --- dopo, perimetro src/app/orders/**
# FUORI M package.json
# ok M src/app/orders/orders.service.ts
# ok ?? src/app/orders/orders.pagination.ts
# 3 file cambiati, 1 fuori dal perimetro
# exit 2
# --- prima, albero sporco
# albero NON pulito: 3 file modificati, committa o metti da parte prima di partire
# exit 1
Il perimetro, d'altra parte, vale solo se l'hai comunicato all'agente. Il prompt che segue è un esempio per un progetto Angular: dice il risultato atteso, i vincoli (dove può scrivere, che cosa non deve toccare) e come verificare. È uno schema da adattare e non è stato eseguito, perché richiede Cursor e un progetto.
Nella cartella src/app/orders aggiungi la paginazione all'elenco degli ordini.
Risultato atteso:
- il servizio OrdersService accetta pagina e dimensione pagina e le passa
come parametri di query all'endpoint GET /api/orders;
- il componente mostra venti ordini per volta e due pulsanti Avanti e Indietro;
- Indietro e' disabilitato alla prima pagina.
Vincoli:
- modifica solo i file dentro src/app/orders;
- non aggiungere dipendenze a package.json;
- segui le regole del progetto.
Verifica: scrivi o aggiorna i test del servizio e del componente, poi esegui
"npm test" e riportami l'esito. Se un test fallisce non cambiarlo per farlo
passare: dimmi perche' fallisce.
Tre scelte rendono il prompt verificabile. Il risultato è espresso con comportamenti che puoi osservare (venti
ordini per volta, un pulsante disabilitato), non con aggettivi. I vincoli coincidono con il perimetro che controlli
dopo con lo script: src/app/orders/** e niente dipendenze. L'ultima frase impedisce la scorciatoia più
comune, cambiare un test per farlo passare. Non serve allegare ogni file con la chiocciola: la documentazione
suggerisce le menzioni @ quando sai già quali file contano, e di lasciar cercare all'Agent negli altri
casi. Se il compito cambia argomento, apri una chat nuova: l'anello del contesto accanto al campo di testo mostra
quanto della finestra è già occupato, e una conversazione lunga viene riassunta.
Durante: che cosa può eseguire da solo
Le Run Modes decidono quando l'agente deve fermarsi a chiederti conferma per comandi di shell, strumenti MCP e richieste di rete. Si scelgono, nell'applicazione desktop, da Settings, Agents, Approvals & Execution. Sono tre, e la differenza tra l'una e l'altra è quanta fiducia dai a priori.
- Auto-review: le azioni nella lista consentita partono subito; gli altri comandi di shell girano nella sandbox quando possibile; ciò che non può usarla viene esaminato da un classificatore.
- Allowlist: partono senza chiedere solo le azioni elencate, comportamento deterministico, nessun classificatore.
- Run Everything: ogni chiamata parte da sola, senza controlli e senza sandbox.
La documentazione indica Auto-review come impostazione più sicura per la maggior parte delle persone, e subito dopo avverte che non è un confine di sicurezza: il classificatore può sbagliare in entrambe le direzioni. La modalità Run Everything corrisponde a ciò che molte guide più vecchie chiamano YOLO; l'equivalenza è mia, la documentazione non usa quel nome. Se il progetto contiene segreti o lavori su una macchina con accesso a sistemi reali, la scelta ragionevole è Allowlist con pochi comandi fidati, tipo i test e la build, oppure Auto-review con regole tue. La pagina sulla sicurezza dice inoltre che, per impostazione predefinita, i comandi di terminale richiedono approvazione: controlla in Settings quale modalità è attiva sulla tua installazione, perché la pagina delle Run Modes non dice quale sia quella di partenza.
Con Auto-review puoi aggiungere istruzioni in italiano semplice in un file permissions.json, in
~/.cursor/ per tutti i tuoi progetti o in .cursor/ per quello corrente; se esistono entrambi,
Cursor li unisce, e una configurazione di team nella dashboard, se presente, ha la precedenza su entrambi. Il file
che segue chiede che i comandi che riscrivono la cronologia di Git e quelli che cancellano fuori da dist/
passino sempre dall'approvazione.
{
"autoRun": {
"allow_instructions": [],
"block_instructions": [
"Ogni comando che modifica la cronologia di git (rebase, reset, push) deve passare dall'approvazione.",
"Ogni comando che cancella file fuori dalla cartella dist/ deve passare dall'approvazione."
]
}
}
Le chiavi sono quelle della documentazione: allow_instructions descrive ciò che Auto-review deve
tendere a lasciar passare, block_instructions ciò che deve tendere a bloccare, in modo che l'agente
scelga un'altra strada o te lo chieda. Sono frasi, non regole formali: «tendere» è il verbo della documentazione, quindi
non sostituiscono un backup né un account senza permessi di scrittura sul server di produzione. Ho validato il file
come JSON e verificato le due chiavi; il comportamento dentro Cursor non è stato provato.
Sotto, c'è la sandbox, un livello in più per i comandi di shell: nella modalità predefinita lavora con lettura e
scrittura nel progetto, blocca la rete finché non la apri tu con sandbox.json e protegge percorsi come
.git/config e .git/hooks. Un comando che ha bisogno di più accesso esce dalla sandbox
e Cursor te lo segnala chiedendoti l'approvazione. Un'avvertenza dalla pagina del file di esclusione: il file
.cursorignore nasconde file all'agente, ma non governa gli strumenti del terminale né i server MCP.
Dopo: controllare quello che è cambiato
Le modifiche compaiono nella vista delle differenze mentre l'agente lavora, e non devi aspettare la fine: il pulsante Stop, o Cmd/Ctrl+Shift+Backspace secondo la guida «Reviewing and testing code», lo ferma a metà. Se la strada è sbagliata, la guida consiglia di annullare le modifiche e raffinare il piano prima di rilanciarlo, invece di correggerlo con messaggi successivi. Per tornare indietro ci sono i checkpoint: con «Restore Checkpoint» riporti i file allo stato di quel punto, ma sono locali, separati da Git, non tolgono i messaggi dalla conversazione, e servono ad annullare le modifiche dell'agente, mentre la storia permanente la tiene Git.
Per la revisione vera e propria Cursor offre due percorsi: dopo un compito il pulsante Review, poi «Find Issues»,
avvia una revisione dedicata riga per riga; per tutte le modifiche locali, il comando Agent Review nella scheda
Source Control le confronta con il ramo principale. Puoi anche allegare @Branch a un messaggio in modalità
Ask e chiedere «rivedi i cambiamenti di questo ramo». La guida ricorda che il codice generato può sembrare corretto,
compilare e passare i test che hai scritto, e sbagliare comunque sui casi limite o duplicare logica che esiste già:
il criterio per decidere che cosa fondere resta quello che applicheresti a codice scritto a mano.
Un ultimo accorgimento riguarda i commit. Un agente produce molte modifiche insieme, e un unico commit di centinaia di
righe è difficile da rivedere per un collega. La guida di Cursor suggerisce di lavorare liberamente e poi chiedere
all'agente di riscrivere la storia in commit piccoli e descrittivi, con una convalida finale che la differenza
complessiva sia identica all'originale; riporta anche una skill (rework-commits) che puoi
adattare. Prima di usarlo guarda i comandi che esegue: contiene un git reset, ed è uno di quelli che
conviene far passare dall'approvazione.
Quando non conviene affidargli il compito
Non è lo strumento giusto quando non sai descrivere il risultato (usa prima Ask o Plan per capire il problema), quando l'esito si può giudicare solo a occhio su molti file, e quando il codice tocca segreti o sistemi di produzione che non vuoi nemmeno esporre al contesto. Per le modifiche di una riga, il completamento Tab è più veloce e lascia meno da rivedere. Resta valido un criterio generale: quanto più verificabile è il risultato con un comando, tanto più il compito è delegabile.
Domande frequenti
Come impedisco all'Agent di eseguire comandi pericolosi?
Scegli la modalità giusta in Settings, Agents, Approvals & Execution, preferendo Allowlist o Auto-review a Run Everything, e aggiungi istruzioni di blocco in permissions.json. La documentazione ammette che nessuna di queste è un confine di sicurezza assoluto.
Come annullo ciò che l'Agent ha modificato?
Con «Restore Checkpoint» su un messaggio precedente riporti i file a quello stato, ma i checkpoint sono locali e separati da Git. Se lavori su un albero pulito, git restore o un commit precedente restano la rete di sicurezza permanente.
Posso scrivere un altro messaggio mentre l'Agent lavora?
Sì. Premendo Invio il messaggio va in coda e parte alla fine del compito; con Cmd/Ctrl+Invio viene inviato subito, senza passare dalla coda. Per una domanda a margine, le chat laterali evitano di interrompere la conversazione principale.
Che cosa sai fare adesso
Sai descrivere un compito con risultato, vincoli e verifica, sai decidere quali comandi l'Agent può eseguire da solo e quali no, e sai controllare dopo che le modifiche siano rimaste nel perimetro che avevi indicato, con un albero pulito come punto di partenza. Il passo successivo è lasciare che l'Agent si fermi a pianificare prima di scrivere, nel Plan Mode, e, per automatizzare ciò che accade intorno all'agente, negli hook. Se l'Agent deve parlare con un database o un'API, c'è MCP; se il compito è un bug, il debugging. Per un progetto intero, dalla configurazione ai controlli, c'è il workflow su un'applicazione Angular.
Fonti
- Cursor, documentazione: Agent - componenti dell'agente, strumenti, assenza di limite alle chiamate, checkpoint, coda dei messaggi, consultata il 2026-11-13
- Cursor, documentazione: Run Modes - Auto-review, Allowlist, Run Everything, permissions.json, sandbox, consultata il 2026-11-13
- Cursor, documentazione: Agent Security - approvazioni predefinite per file, terminale e MCP, consultata il 2026-11-13
- Cursor, documentazione: Subagents - sottoagenti Explore e Browser, contesto separato, consultata il 2026-11-13
- Cursor Learn: Reviewing and testing code - arresto dell'agente, Agent Review, commit semantici, competenza rework-commits, consultata il 2026-11-13
- Cursor, documentazione: Agent mode - modalità Agent, Ask, Plan, Debug e ripristino dei checkpoint, consultata il 2026-11-13
- Cursor, documentazione: Prompting agents - menzioni @, anello del contesto, consultata il 2026-11-13
- Cursor, documentazione: Ignore file - limiti di .cursorignore su terminale e MCP, consultata il 2026-11-13
- Git: git-status - formato --porcelain stabile per gli script e opzione --untracked-files, consultata il 2026-11-13
- Python: modulo glob - glob.translate, consultata il 2026-11-13
Lo strumento di perimetro è stato eseguito con Python 3.14.4 e Git 2.53.0 in un repository temporaneo fuori dal progetto, due volte con uscita identica; le modifiche dello scenario le ho simulate a mano, senza alcun agente. Il file dei permessi è stato validato come JSON. Il prompt e il comportamento di Cursor, delle Run Modes e dei checkpoint non sono stati provati: Cursor non era installato.

Commenti
Caricamento commenti...
Accedi per commentare