Come correggere un bug con Claude Code partendo da una riproduzione

“Il salvataggio ogni tanto non funziona” descrive un disagio, non ancora un bug affidabile da consegnare a Claude Code. Manca lo stato di partenza, non sappiamo quale azione fallisca e non esiste un segnale che distingua una correzione vera da un errore semplicemente nascosto.

Per correggere un bug con Claude Code, costruisci prima una riproduzione che fallisce nello stesso modo. Poi chiedi di spiegare la causa, confrontare alternative e applicare il cambiamento più piccolo. La chiusura richiede due prove: il caso originario ora passa e un comportamento vicino non è regredito.

La guida ai workflow di Claude Code invita a fornire il comando che riproduce l'errore, lo stack trace, i passaggi e l'informazione che distingue un difetto costante da uno intermittente. Sono gli ingredienti che trasformano una segnalazione in un esperimento.

Un messaggio d'errore non è ancora una riproduzione

Lo stesso messaggio può nascere da condizioni diverse. Un timeout può dipendere dalla rete, da un lock, da dati fuori formato oppure da un test che non prepara l'ambiente. Incollare solo l'ultima riga spinge la diagnosi verso la prima spiegazione compatibile.

Una riproduzione identifica almeno versione, input, sequenza, risultato atteso e risultato osservato. Deve anche dire quante volte fallisce. Se il difetto compare una volta su venti, non trattarlo come un fallimento deterministico.

Ripulisci i log prima di condividerli. Rimuovi token, email, percorsi personali e payload reali. Conserva però timestamp relativi, codici di stato e righe utili a ricostruire l'ordine degli eventi.

Compila la scheda del bug

Usa sei campi e chiedi a Claude di segnalarne i vuoti prima di proporre il fix.

Aggiungi il comando esatto che esegue la prova e il suo codice di uscita. “Esegui i test” lascia a Claude la scelta di una suite forse irrilevante; npm test -- profile-save identifica un punto di controllo, se quello è davvero il comando del progetto.

Collega la scheda a un registro degli incidenti AI quando il difetto ha già avuto conseguenze operative. Il registro conserva cronologia e impatto; la scheda qui serve a riprodurre il comportamento nel codice.

Fai fallire la prova prima di cambiare il codice

Chiedi a Claude di eseguire la riproduzione nello stato iniziale e salvare l'esito. Se la prova passa, fermati: o il bug non è presente nell'ambiente, o la riproduzione non lo osserva.

Una consegna utile è:

Esegui il comando di riproduzione senza modificare file.
Riporta codice di uscita, asserzione fallita e primi tre frame pertinenti.
Se non fallisce come descritto, non proporre una correzione: indica la differenza di ambiente.

Questo passaggio evita di cambiare codice sulla base di una storia non confermata. Fissa anche una ricevuta “prima” che potrai confrontare con il risultato finale.

Separa fatti e ipotesi

Durante la diagnosi fai mantenere due colonne. I fatti sono visibili nel codice, nel test o nel log. Le ipotesi spiegano quei fatti e devono avere una prova che potrebbe smentirle.

Non permettere che una nuova ipotesi cancelli la precedente dal racconto. Il registro rende visibile perché una strada è stata abbandonata e impedisce di ripeterla durante un retry.

Chiedi alternative prima del fix

Quando la causa è abbastanza circoscritta, chiedi due o tre soluzioni con conseguenze diverse. Una normalizzazione nella UI, nell'API o nel dominio può far passare lo stesso test, ma cambia il punto in cui il sistema garantisce la regola.

Per ogni alternativa chiedi:

• quale contratto modifica;

• quali chiamanti copre;

• quale comportamento lascia invariato;

• quale test la distingue dalle altre;

• come tornare indietro.

Non serve una gara tra proposte. Serve evitare che la prima patch plausibile diventi automaticamente la decisione.

Applica la modifica più piccola che spiega la causa

Il fix minimo non è quello con meno caratteri. È il delta più piccolo che corregge la causa nel livello giusto e che puoi verificare senza trascinare un refactoring non necessario.

Chiedi di elencare i file attesi prima della modifica. Se il diff tocca anche formattazione, dipendenze o API non coinvolte, separa quei cambiamenti. Un bug fix leggibile mette in relazione causa, riga cambiata e prova.

Le best practice di Claude Code raccomandano di dare al modello un segnale che possa eseguire e leggere: test, build, linter, script o confronto visuale. “Ho corretto il problema” non è quel segnale.

Usa la regola delle due prove

La prima prova è la riproduzione congelata: deve fallire prima e passare dopo. La seconda protegge un comportamento vicino che il fix potrebbe rompere.

Nel caso del nome con spazio finale:

1. il test del bug dimostra che " Ada " viene normalizzato come previsto;

2. il test di regressione dimostra che un nome già valido non viene alterato in modo inatteso.

La seconda prova non deve essere una suite enorme scelta per prudenza. Deve osservare il confine reale del cambiamento. Se il fix tocca una funzione condivisa, aggiungi i chiamanti più esposti; se modifica solo la presentazione, verifica anche l'interazione visibile.

Puoi costruire casi congelati con una guida al dataset di test per workflow AI: input, risultato atteso e criterio di confronto restano uguali tra prima e dopo.

Tratta a parte i bug intermittenti

Un difetto intermittente richiede una misura di frequenza e condizioni controllate. Non dichiararlo risolto perché non compare in un singolo tentativo.

Riduci le variabili: stesso commit, stesso seed, stessa concorrenza, stesso input. Esegui un numero dichiarato di ripetizioni e conserva quanti fallimenti osservi. Se il bug dipende dal tempo, usa clock controllabile; se dipende dall'ordine, registra gli eventi.

Il risultato può essere “causa non isolata”. È una consegna valida se include le ipotesi escluse, i campioni e il prossimo esperimento. Una patch senza segnale ripetibile non migliora la conoscenza del problema.

Consegna causa, delta e limite

La chiusura del lavoro deve rispondere a cinque domande:

• quale comportamento falliva;

• quale causa è sostenuta dalle prove;

• quali file sono cambiati e perché;

• quali due prove sono verdi;

• quale rischio o condizione non è stato coperto.

Chiedi anche il comando esatto e l'output essenziale, non un generico “tutti i test passano”. Se alcuni controlli non sono stati eseguiti, devono restare visibili.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi trasformare un bug del tuo lavoro in una scheda riproducibile, far separare ipotesi e fatti e arrivare a un fix con una prova che qualcun altro può rilanciare.