Come scrivere una buona segnalazione di bug (per un'IA o uno sviluppatore)

Una buona segnalazione di bug permette a qualcun altro, uno sviluppatore o un'IA, di vedere lo stesso problema che hai visto tu, senza doverti fare domande. Servono un titolo specifico, i passaggi esatti per riprodurlo, cosa ti aspettavi, cosa è successo davvero, ogni messaggio di errore copiato parola per parola, e dove è successo: quale pagina, browser, dispositivo e utente. Un bug per segnalazione, con uno screenshot se utile.

La maggior parte dei bug richiede più tempo per essere capita che per essere corretta. Una segnalazione chiara elimina la parte di comprensione. Questo conta ancora di più con gli strumenti di IA: un'IA non può fare una domanda di approfondimento su cosa intendi con "il checkout è strano", quindi indovina, e un'ipotesi sbagliata può rompere qualcos'altro.

Il modello

Copialo e compilalo:

Titolo: [Cosa non va, dove]: es. "Il modulo di prenotazione rifiuta gli orari dopo le 18"

Passaggi per riprodurre:
1. ...
2. ...
3. ...

Atteso: [cosa dovrebbe succedere]
Effettivo: [cosa è successo invece]

Messaggio di errore: [testo esatto, se presente]
Dove: [pagina/URL, browser, dispositivo, connesso come quale utente]
Frequenza: [ogni volta / a volte / una volta]
Screenshot o registrazione: [allegato]

Il resto di questa guida spiega ogni parte.

Passo 1: riproducilo per primo

Prima di scrivere, prova a far accadere di nuovo il bug. Capirai quali passaggi contano e se succede ogni volta.

• Parti da uno stato pulito: ricarica, oppure esci e rientra.
• Annota ogni clic e ogni testo digitato.
• Prova a trovare il percorso più breve che lo fa scattare.
• Prova un secondo browser o un altro account. Se succede solo per un utente, è un indizio importante.

Per approfondire, vedi come fare debug di un'app creata con l'IA.

Passo 2: scrivi un titolo specifico

Il titolo deve dire cosa non va e dove, così chi scorre una lista capisce di quale bug si tratta.

Passo 3: elenca i passaggi esatti

Numerali. Sii letterale: quale pagina, quale pulsante, cosa hai digitato.

1. Accedi come cliente (account di prova: customer@example.com).
2. Aggiungi il "Starter kit" al carrello.
3. Inserisci il codice sconto WELCOME10 e clicca Applica.
4. Clicca Checkout.

"Prova a fare il checkout con un codice" tralascia i dettagli che spesso contano: quale utente, quale prodotto, quale codice, se è stato applicato prima.

Passo 4: atteso vs effettivo

Questa è la parte centrale della segnalazione. Scrivili entrambi, perché la differenza è il bug.

• Atteso: la pagina di checkout si apre con lo sconto del 10% mostrato nel totale.
• Effettivo: il pulsante mostra una rotellina per un secondo, poi non succede nulla. Senza codice sconto il checkout funziona.

Senza "atteso", chi legge potrebbe non sapere che il comportamento è sbagliato. Senza "effettivo", non sa cosa cercare.

Passo 5: copia gli errori esattamente

I messaggi di errore sono la strada più rapida verso la causa. Copiali come testo, parola per parola, senza parafrasarli.

Dove trovarli:

• Sullo schermo: qualsiasi messaggio mostrato dall'app.
• Console del browser: apri gli strumenti per sviluppatori (F12, oppure clic destro → Ispeziona) e guarda la scheda Console per le righe in rosso.
• Scheda Rete: negli strumenti per sviluppatori, trova la richiesta fallita e annota il suo URL e il codice di stato (per esempio POST /api/checkout → 500).
• Log del server, se vi hai accesso.

Una riga come TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 spesso indica direttamente il problema.

Passo 6: aggiungi contesto

• Dove: l'URL della pagina, l'ambiente (anteprima, staging o produzione).
• Chi: quale utente o ruolo: amministratore, membro, non connesso.
• Dispositivo e browser: "Safari su iPhone" e "Chrome su Windows" possono fare differenza.
• Dati: qualsiasi cosa insolita nel record: testi molto lunghi, caratteri speciali, un grande numero di elementi.
• Quando è iniziato: "dopo la modifica di ieri ai codici sconto" è oro.
• Frequenza: ogni volta, oppure una volta su dieci tentativi.

Passo 7: mostralo

Uno screenshot con il problema cerchiato, o una breve registrazione dello schermo, elimina ogni ambiguità, soprattutto per i bug di layout. Se il tuo strumento di IA accetta immagini, allegane una. Ritaglia qualsiasi cosa privata, comprese chiavi e dati di altre persone.

Scrivere segnalazioni per un builder con IA

La stessa struttura funziona come prompt. Due aggiunte aiutano:

• Di' cosa non deve cambiare, così la correzione non causa un nuovo problema.
• Chiedi di verificare la correzione, non solo di scriverla.

Connesso come cliente, con il "Starter kit" nel carrello e il codice WELCOME10 applicato, cliccando Checkout non succede nulla. Atteso: la pagina di checkout si apre con il 10% di sconto sul totale. Effettivo: una breve rotellina, poi niente. La scheda Rete mostra che POST /api/checkout ha restituito 500. Il checkout senza codice funziona. Trova la causa e correggila senza cambiare come vengono calcolati i prezzi per gli ordini senza codice. Poi verifica il checkout con un codice percentuale, un codice a importo fisso e nessun codice.

Se non sei sicuro della causa, chiedi prima una diagnosi:

Non cambiare ancora il codice. Sulla base di questa segnalazione, quali sono le cause probabili e cosa confermerebbe ciascuna?

Errori comuni

• "È rotto." Nessun passaggio, nessun risultato atteso, nulla su cui agire.
• Più bug in un'unica segnalazione. Alcuni vengono corretti, altri si perdono.
• Errori parafrasati. "Una cosa undefined" nasconde la parte utile.
• Dimenticare l'utente o il ruolo. Molti bug riguardano solo gli amministratori o solo i nuovi utenti.
• Descrivere solo la correzione che vuoi ("aggiungi un controllo null") invece del problema.
• Condividere segreti in screenshot o log incollati.

Checklist

• Ho riprodotto il bug e trovato i passaggi più brevi.
• Il titolo dice cosa non va e dove.
• I passaggi sono numerati e letterali.
• Sono indicati sia il risultato atteso sia quello effettivo.
• I messaggi di errore sono copiati esattamente, con la richiesta fallita e il codice di stato.
• Pagina, ambiente, utente, dispositivo e browser sono inclusi.
• Ho indicato con che frequenza succede e quando è iniziato.
• Uno screenshot o una registrazione è allegato, con i dati privati rimossi.
• Un bug per segnalazione.

Segnalare bug all'agente di Mythex

In un progetto Mythex, la segnalazione è il prompt. Alcune funzioni aiutano:

• Allega uno screenshot dell'anteprima o della schermata di errore, fino a 5 file per messaggio.
• /fix concentra l'agente sulla correzione di un bug; la modalità Piano gli permette di indagare prima di modificare.
• /test fa riprodurre i flussi all'agente direttamente nell'anteprima e gli fa riportare cosa vede.
• Ripristina a questo punto annulla una correzione che ha peggiorato le cose.

La pagina della documentazione debug con i prompt usa la stessa struttura passaggi / atteso / effettivo. Per il ciclo di correzione e verifica che la circonda, vedi come iterare su un'app creata con l'IA.

Domande