Cos'è la Debug Mode di Cursor? Come usarla, con prompt di esempio

Che cos’è realmente la Debug Mode

Nel dicembre 2025, Cursor ha annunciato una nuova modalità agente chiamata “Debug Mode”. Laddove la normale modalità Agent legge il codice e passa direttamente a una proposta di correzione, la Debug Mode adotta un approccio più simile a quello di un detective: raccoglie prima le informazioni di runtime e poi individua la causa.

In concreto, funziona così:

1. Descrivi il bug: fornisci i sintomi e i passaggi per la riproduzione nel modo più specifico possibile
2. Formula ipotesi: l’agente analizza la codebase e genera diverse ipotesi sulla causa
3. Aggiunge la strumentazione di log: inserisce temporaneamente del codice di log nei punti sospetti per testare ogni ipotesi
4. Riproduce il bug: usi effettivamente l’app per attivare il bug e l’agente raccoglie i log di runtime
5. Individua e corregge la causa: in base a ciò che ha raccolto (stato delle variabili, percorso di esecuzione, tempistiche e così via), propone una correzione precisa
6. Verifica la correzione: riproduci il bug un’altra volta: se è scomparso, l’agente rimuove automaticamente tutta la strumentazione di log aggiunta; in caso contrario, aggiunge altri log e continua a restringere il campo

Grazie a questo ciclo “ipotizza → strumenta → riproduci → verifica”, si dice che invece di riscrivere ciecamente centinaia di righe, di solito si ottiene una correzione precisa nell’ordine delle 2-3 righe.

Come attivarla

Premi Shift + Tab per scorrere le modalità e seleziona “Debug”. Puoi anche semplicemente cliccare sulla modalità e cambiarla direttamente.

Quando è lo strumento giusto

La documentazione ufficiale indica che la Debug Mode è particolarmente adatta per:

• Bug che riesci a riprodurre ma di cui non riesci a trovare la causa principale
• Problemi di prestazioni e perdite di memoria (memory leak)
• Problemi in cui la sola lettura del codice non rivela la causa

D’altra parte, un errore semplice con un tracciato dello stack (stack trace) evidente è solitamente più veloce da risolvere nella normale modalità Agent. Una regola pratica realistica: prova prima il tuo solito approccio di correzione e passa alla Debug Mode se questo non ti porta da nessuna parte.

Quanto è utile nella pratica?

Gli sviluppatori che usano regolarmente la Debug Mode sottolineano alcuni aspetti degni di nota:

• Funziona tramite log di testo basati su HTTP anziché dipendere da specifiche funzionalità dell’IDE (come l’LSP), quindi funziona con più o meno qualsiasi linguaggio di programmazione o runtime (ambienti locali, ovviamente, ma anche tramite Remote SSH)
• Puoi strumentare sia il frontend che il backend contemporaneamente per rintracciare i bug che si estendono a entrambi
• Alcuni sviluppatori affermano che collegare strumenti di osservabilità esterni come Datadog o Sentry tramite MCP affina ulteriormente i risultati

Uno sviluppatore si è imbattuto in un bug in cui la paginazione su un’integrazione API esterna restituiva sempre la prima pagina, indipendentemente da tutto. La Debug Mode ha formulato tre ipotesi (un nome di campo JSON errato, un parametro di query mancante, un token non passato correttamente) e ha aggiunto la strumentazione di log per testarle. Dopo alcuni cicli di riproduzione e raccolta dei log, si è scoperto che l’API utilizzava effettivamente uno schema di paginazione diverso per gli endpoint di aggregazione rispetto alle query normali, e gli endpoint di aggregazione richiedevano che il token fosse passato in un modo completamente diverso. Portare alla luce questo tipo di disallineamento nascosto delle specifiche basato su dati reali (il genere di cose facili da perdere semplicemente leggendo il codice) è ciò in cui eccelle davvero.

Prompt di esempio per scenario

La Debug Mode diventa più precisa quanto più descrivi in modo specifico la situazione. Basandosi sui modelli di utilizzo della documentazione ufficiale, ecco alcuni esempi di prompt suddivisi per scenario.

Indagare partendo da un messaggio di errore

I'm getting "Cannot read property id of undefined" on line 45
of UserService.getProfile. Find the root cause and fix it.

La riga in cui un tracciato dello stack mostra un errore e il punto in cui risiede la causa effettiva sono spesso diversi. La Debug Mode risale fino a “chiunque abbia chiamato quella funzione” per trovare la vera causa.

Ristringere il campo di una causa a partire dai log

Processing for order ID 12345 is failing. The logs show:
inventory check passed → payment auth started → error here.
Find out exactly where after payment auth this is failing.

Forniscile log con timestamp e la Debug Mode incrocerà l’ordine degli eventi durante le sue indagini.

Indagare a partire da un ticket di supporto

A customer reported that exporting their data produced an empty file.
Pro plan, account ID 12345. Check the export feature's code and
work out why the file might come out empty.

L‘“file vuoto” da solo copre molte cose: zero record, un timeout, un errore silenzioso, un download corrotto. La Debug Mode elenca queste possibilità e aiuta a capire cosa controllare per primo.

Indagare su un test intermittente (flaky test)

This test is flaky — sometimes it passes, sometimes it fails.
Run it 20 times, collect the failures, and find the pattern.

Eseguire un test a mano più e più volte è noioso, ma è proprio in questo tipo di lavoro ripetitivo che la Debug Mode si dimostra utile.

Indagare su un problema di frontend

In abbinamento agli strumenti per il browser di Cursor, può controllare la schermata effettivamente renderizzata, gli errori della console e persino le richieste di rete.

The "Place order" button on the checkout page doesn't respond when clicked.
Take a screenshot, check the console errors, and find the cause.

Suggerimenti per prevenire problemi ripetuti e costruire la conoscenza aziendale

Per evitare di ripetere le indagini sullo stesso tipo di problema, vale la pena mantenere un file di regole di debug sotto .cursor/rules/. Annota i modelli di bug comuni, le query interne che usi per le indagini, i test instabili noti e così via: la Debug Mode ne terrà conto nelle indagini future.

Una volta applicata una correzione, vale anche la pena chiedere alla modalità Ask di spiegare perché il bug si è verificato in primo luogo e se lo stesso schema potrebbe celarsi altrove. Questo è ciò che impedisce effettivamente le recidive.

Un’altra cosa (non una funzione specifica della Debug Mode, ma un consiglio comune per fare in modo che Cursor corregga bene i bug in generale): molte persone inviano un primo prompt che chiede solo una panoramica dell’approccio, senza fargli scrivere ancora alcun codice. Questo ti permette di cogliere un’eventuale incomprensione da parte dell’agente prima che venga scritto del codice, riducendo la necessità di rifare il lavoro.

Limitazioni note e cose da tenere d’occhio

Ci sono segnalazioni secondo cui molte di queste limitazioni possono essere aggirate, almeno in parte, scrivendo regole sotto .cursor/rules/*.mdc, come ad esempio: “usa questa specifica libreria” o “esegui il comando di lint specificato in modo pulito dopo qualsiasi modifica”. Per quanto riguarda il problema della CLI in cui l’input smette di essere registrato, premere Escape di solito sblocca la situazione, e pre-approvare i comandi fidati in una whitelist (o attivare l’approvazione automatica) rende più facile evitarlo del tutto.

In conclusione

La Debug Mode integra una solida disciplina di debug nell’agente: invece di “leggi il codice e indovina”, l’approccio è “trova la causa dai dati raccolti eseguendo effettivamente il programma”. È forte contro bug misteriosi, ostinati e problemi di prestazioni, sebbene per errori semplici la normale modalità Agent sia talvolta più veloce; quindi è importante sapere quando ricorrere all’una o all’altra.

Se non l’hai ancora provata, la prossima volta che ti immetti in un bug in cui la causa non è ovvia, prova la Debug Mode tramite Shift+Tab.