Debug guidato dall’AI: descrivere il sintomo, non la causa

Errore tipico in debug con AI: descrivere la diagnosi che credi sia corretta, invece dei sintomi reali. “Probabilmente c’è un problema di stato” → l’AI lavora sull’ipotesi tua, non sui dati. Se la tua ipotesi è sbagliata, accumuli fix che non risolvono. Descrivere sintomi (non cause) lascia all’AI lo spazio per diagnosticare bene.

Perché questa lezione conta

Bug medi-difficili spesso hanno cause non ovvie. La prima ipotesi è frequentemente sbagliata. Se in chat AI presenti la tua ipotesi come dato, l’AI ci costruisce sopra fix sempre più articolati. Risultato: loop, tempo perso, debito tecnico introdotto. Sapere come scrivere un bug report (anche per uso AI) è skill fondamentale, non opzionale.

Obiettivo operativo

Alla fine devi saper:

1. distinguere sintomo da diagnosi e raccontare solo sintomi;
2. costruire bug report riproducibile in 6 sezioni;
3. forzare l’AI a fare ipotesi multiple prima di proporre fix.

Nucleo della lezione

1. Sintomo vs diagnosi

Sintomo: cosa vedi/osservi. “Cliccando submit, la pagina mostra spinner per 30 secondi e poi messaggio ‘Errore generico’.”

Diagnosi: ipotesi su cosa causa il sintomo. “Il backend non risponde”, “il timeout è troppo basso”, “manca una validazione”.

Errore: passare diagnosi come sintomo. “Il backend non risponde” è una conclusione che potrebbe essere sbagliata. Magari il backend risponde ma il client non gestisce la response. Magari la response è 500 con dettagli ignorati.

Pratica: nel report, descrivi solo cose osservabili (visivamente, in console, nei log). Le ipotesi metti in sezione separata, dichiarate come “ipotesi”, non come fatti.

2. Bug report in 6 sezioni

Struttura standard, applicabile a qualunque bug:

1. Comportamento atteso: cosa dovrebbe succedere. “Cliccando submit, dopo max 5 secondi vedo conferma o messaggio errore specifico.”

2. Comportamento osservato: cosa succede realmente. “Spinner per 30s, poi ‘Errore generico’.” Verbatim.

3. Passaggi per riprodurre: sequenza esatta. “1. Apri /contact. 2. Compila tutti i campi. 3. Clicca submit. 4. Aspetta 30s.”

4. Log/errori (verbatim): stack trace, console errors, network log. Copia, non parafrasi.

5. Ambiente: browser+versione, OS, dimensione viewport, lingua, eventuali estensioni rilevanti.

6. Ultimo cambiamento prima del bug: cosa è cambiato nel codice/config recentemente. Spesso indica la causa.

Non aggiungere “secondo me è…”. Quello sta in sezione separata.

3. Strategia di isolamento prima del fix

Forza l’AI a diagnosticare prima di proporre fix:

• “Dammi 3 ipotesi di causa, ordinate per probabilità. Per ognuna, un controllo specifico per discriminarla.”
• “NON proporre fix in questa risposta.”
• “Aspetta che ti riporti i risultati dei controlli.”

Il modello, costretto a diagnosticare, spesso identifica la causa vera. Se vai diretto al fix, l’AI patcha il sintomo (es. aumenta timeout) senza risolvere la causa (es. query DB non indicizzata).

Sequenza:

1. Bug report a 6 sezioni.
2. Richiesta ipotesi multiple, no fix.
3. Eseguo controlli, riporto dati.
4. Itera diagnosi se necessario.
5. Solo dopo causa chiara, fix mirato.

Caso guidato

Richiesta cattiva:

Il problema è sicuramente lo stato React. Sistemalo.

Hai già dato una diagnosi, forse sbagliata. Il modello tenderà a cercare conferme nella direzione che gli hai imposto.

Richiesta buona:

Sintomo: quando salvo un task, la UI mostra il task due volte.
Atteso: dopo submit compare una sola riga.
Osservato: compaiono due righe identiche, ma dopo refresh torna una sola.
Passi:
1. apro /tasks
2. inserisco titolo "Pagare bolletta"
3. clicco Salva una volta
4. vedo due righe
Console: nessun errore.
Network: una sola POST /api/tasks 201.
Ultimo cambio: aggiunto optimistic update.

Prima di proporre patch, elenca 3 ipotesi e come verificarle.

Ora le ipotesi diventano verificabili:

• optimistic update aggiunge item e poi anche response server;
• chiave React duplicata causa rendering anomalo;
• stato locale e cache remota non vengono riconciliati.

La differenza è enorme: nel secondo caso l’AI può ragionare sul sintomo. Nel primo caso obbedisce alla tua diagnosi prematura. Nel debug, il tuo compito non è sembrare sicuro; è fornire osservazioni pulite.

Procedura pratica

Quando incontri un bug:

1. Non scrivere subito al modello. Pensa 2 minuti.
2. Riproduci: assicurati di poter rigenerare il bug. Se non riesci, non puoi risolverlo.
3. Scrivi bug report nelle 6 sezioni. Niente diagnosi.
4. Manda al modello con richiesta di ipotesi, no fix.
5. Esegui controlli suggeriti.
6. Riporta dati osservati, non interpretazioni.
7. Quando causa è chiara, chiedi fix mirato.
8. Verifica fix: bug riprodotto NON appare più; nessuna regressione su flussi vicini.

Laboratorio guidato

Bug ipotetico: “form di registrazione, dopo submit l’utente non viene loggato automaticamente”.

Approccio sbagliato (diagnosi imposta):

“C’è un bug nella sessione, l’utente non viene loggato dopo registrazione. Probabilmente il cookie non viene impostato. Puoi sistemarlo?”

L’AI fissa cookie. Bug rimane perché era altro.

Approccio corretto (sintomi):

Bug: dopo registrazione, utente non risulta loggato.

Comportamento atteso:
- POST /signup completato → utente vede dashboard /home con suo nome.

Comportamento osservato:
- POST /signup → 200 OK
- redirect a /home → mostra "Login richiesto"
- /home ricarica → ancora "Login richiesto"

Riproduzione:
1. Apri /signup
2. Compila email "test@test.it", password "test1234"
3. Submit
4. Osserva: redirect a /home con prompt login

Log:
- Network: POST /signup → 200, response: {ok: true, userId: "abc"}
- Network: GET /home → 302 redirect a /login
- Console: nessun errore
- Cookie tab: nessun cookie "session" presente

Ambiente:
- Chrome 120, macOS 15
- localhost:3000 (dev)

Ultimo cambiamento:
- ieri ho modificato endpoint /signup per inviare email di verifica via Resend.

NON proporre fix. Dammi 3 ipotesi di causa, ordinate per probabilità, con un controllo specifico per ognuna.

Risposta tipo:

1. Cookie non impostato dal server (alta): controllo: nei DevTools, response headers di POST /signup, c’è Set-Cookie: session=...?
2. Cookie impostato ma non in same-origin (media): controllo: domain del cookie matcha l’host?
3. Codice modificato ieri rompe set-cookie (media): controllo: confronta diff dell’endpoint /signup, vedi se c’è ancora chiamata a setSession() dopo creazione user.

Esegui controllo 1: Set-Cookie non c’è. Causa identificata: signup ora invia email ma non crea sessione (regressione introdotta ieri).

Fix mirato: aggiungere setSession(user.id) dopo creazione user, prima dell’invio email.

Senza l’approccio strutturato, avresti speso tempo su ipotesi sbagliate.

Output atteso

Un template “bug report” personale in 6 sezioni, salvato come snippet o template. Riusabile per ogni bug, anche prima di coinvolgere AI.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: fornire all’AI informazioni verificabili invece di imporre diagnosi premature. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Buon report di bug: comportamento atteso, comportamento osservato, passaggi per riprodurre, log, ambiente, ultimo cambiamento.
• Evitare supposizioni come ‘è un problema di stato’ se non è stato dimostrato.
• Chiedere una strategia di isolamento prima della patch: cosa controllare, in che ordine, con quali comandi.

3. Applicazione: svolgi il laboratorio: riscrivere tre richieste di debug da diagnosi vaga a report riproducibile. L’output da ottenere è: un template bug report pensato per lavorare con AI senza depistare l’analisi.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• distinguo sintomo da diagnosi quando descrivo bug;
• ho bug report a 6 sezioni come template;
• forzo AI a fare ipotesi multiple prima di fix;
• eseguo controlli suggeriti prima di applicare fix;
• almeno una volta ho evitato di patchare causa sbagliata grazie all’isolamento.

Errori comuni

“Probabilmente è X”. Diagnosi prematura, AI lavora su ipotesi tua. Limita opzioni vere.

Saltare riproduzione. “Succede a volte” → impossibile diagnosticare. Prima riproduci.

Log parafrasati. “Errore di connessione” non è il messaggio esatto. Verbatim.

Niente ambiente. “Non funziona”. Browser? OS? Versione? Tutti rilevanti.

Saltare “ultimo cambiamento”. Spesso il bug è introdotto da modifica recente. Quella sezione lo identifica.

Andare diretto al fix. AI patcha sintomo, causa rimane.

Non verificare fix. “L’AI ha proposto X, applico”. Senza riproduzione bug post-fix, non sai se hai risolto.

Prompt di lavoro

Devo diagnosticare un bug. NON proporre fix in questa risposta.

# Comportamento atteso
[cosa dovrebbe succedere]

# Comportamento osservato
[cosa succede, descrizione operativa, niente interpretazione]

# Riproduzione
1. [...]
2. [...]
3. [...]

# Log/errori (verbatim, niente parafrasi)
[INCOLLA ESATTO]

# Ambiente
- browser: [...] versione: [...]
- OS: [...]
- ambiente: [dev / staging / prod]

# Ultimo cambiamento
[modifiche al codice/config nelle ultime 24-48h]

# Mie ipotesi (per onestà, ma vorrei le tue indipendenti)
[opzionale: 1-2 ipotesi tue]

Voglio:
1. 3 ipotesi di causa, ordinate per probabilità.
2. Per ognuna, un controllo specifico per discriminarla (comando, log da guardare, valore da ispezionare).
3. NESSUN fix ora. Aspetto risultati dei controlli.

Se mancano info per fare ipotesi solide, chiedi cosa serve invece di indovinare.

Esercizio finale

Per il prossimo bug non banale del tuo progetto, applica il template. Misura: tempo a fix con questo metodo vs tempo che avresti speso con approccio “diretto”. Quasi sempre il metodo strutturato è più rapido per bug medio-difficili (anche se sembra più lento all’inizio). Per bug banali (typo, condizione invertita) il metodo è overhead. Sviluppi sensibilità per quale è quale.