Come fare refactoring con Claude Code senza cambiare il comportamento

Chiedi a Claude Code di “ripulire questo modulo” e puoi ricevere un diff elegante che rinomina simboli, sposta funzioni, aggiorna dipendenze e corregge anche un paio di comportamenti ritenuti strani. Il problema è che non sai più quale cambiamento appartenga al refactoring e quale abbia modificato il prodotto.

Per un refactoring controllato, definisci prima che cosa deve restare uguale. Poi fai osservare il comportamento esistente, colma solo i vuoti di prova necessari e procedi per tranche piccole. Ogni passaggio deve avere un delta leggibile, un controllo pertinente e un punto di ripristino.

La guida ai workflow di Claude Code consiglia incrementi piccoli e verificabili, attenzione alla compatibilità ed esecuzione dei test dopo il refactoring. Queste indicazioni diventano operative quando le leghi a invarianti espliciti.

Refactoring e nuova funzione sono due incarichi diversi

In questo workflow chiamiamo refactoring un cambiamento della struttura interna che deve conservare il comportamento concordato. Se vuoi anche cambiare una risposta API, aggiungere un caso d'uso o correggere una regola, apri un incarico separato.

La separazione protegge la revisione. Se un test cambia insieme al codice perché “il nuovo comportamento è migliore”, non puoi più capire se la struttura è stata trasformata senza regressioni. Prima chiudi il refactoring; poi discuti il cambiamento funzionale con i suoi criteri.

Scrivi lo scope in una frase:

Riduci la duplicazione tra i due parser senza cambiare input accettati,
output, messaggi d'errore o chiamate esterne. Non aggiornare dipendenze.

La frase non basta come prova, ma rende visibili le deviazioni.

Scrivi il contratto degli invarianti

Gli invarianti sono comportamenti che il delta non deve spostare. Elencali prima che Claude proponga la nuova struttura.

Non trasformare la tabella in un catalogo teorico. Inserisci solo ciò che è osservabile e pertinente. Se non conosci un contratto, marca il campo come scoperto e decidi se il refactoring può partire.

Un invariante importante senza prova è un rischio, non una casella verde.

Osserva il comportamento prima della struttura

Prima del delta esegui i controlli esistenti e conserva risultati, versione e comando. Poi chiedi a Claude di localizzare dove ogni invariante viene già verificato.

La risposta può produrre tre stati:

• verde: esiste una prova specifica e passa;

• giallo: esiste un controllo indiretto o troppo ampio;

• rosso: nessuna prova osserva l'invariante.

Questo semaforo non misura la qualità generale della suite. Dice soltanto quanto è visibile il comportamento che vuoi preservare. Un progetto con migliaia di test può lasciare scoperto proprio il confine toccato dal refactoring.

Crea test di caratterizzazione dove serve

Un test di caratterizzazione fotografa il comportamento corrente necessario al contratto. Non dichiara che quel comportamento sia ideale; impedisce che cambi senza una decisione.

Chiedi a Claude di seguire i pattern già usati nel repository e di proporre casi limite legati all'invariante. La documentazione Anthropic osserva che Claude Code può esaminare i test esistenti per adattarsi a framework, stile e asserzioni, ma devi specificare quale comportamento vuoi controllare.

Evita di creare test che ripetano l'implementazione riga per riga. Preferisci input e output pubblici, effetti osservabili o contratti del modulo. Se il test passa anche dopo aver introdotto deliberatamente la regressione temuta, non sta proteggendo il refactoring.

Taglia il lavoro in tranche verificabili

Una tranche deve poter essere compresa e annullata senza dipendere dal resto. Può estrarre una funzione, spostare un tipo o sostituire una duplicazione, ma non tutte e tre le cose insieme se ciascuna ha un rischio diverso.

Prepara una matrice prima di procedere:

Fai completare, leggere e verificare una riga prima di aprire la successiva. Se la prima tranche rivela che i due parser non hanno lo stesso comportamento, la decisione può diventare “non consolidare”. È un esito utile.

Questa struttura applica la procedura di controllo delle modifiche: baseline, delta, prova e ripristino restano associati.

Chiedi a Claude di spiegare il vantaggio del delta

Ogni spostamento deve avere un motivo che sopravvive alla preferenza stilistica. Chiedi quale duplicazione elimina, quale dipendenza rende esplicita o quale confine chiarisce.

Poi chiedi la controparte: che cosa diventa più difficile? Un'astrazione condivisa può ridurre righe duplicate e aumentare l'accoppiamento. Una nuova classe può chiarire responsabilità e rendere più lungo un flusso semplice.

Se il vantaggio non si può collegare al problema iniziale, elimina la tranche. Il refactoring non deve dimostrare quante parti del codice Claude sappia trasformare.

Controlla compatibilità e superfici laterali

Non fermarti ai test del modulo. Cerca chiamanti, configurazioni, serializzazioni, esempi di documentazione e script che usano l'interfaccia. Un simbolo interno può essere richiamato da un tool o da un test di integrazione fuori dalla cartella osservata.

Chiedi a Claude di produrre una lista chiusa delle superfici cercate e dei metodi usati: ricerca dei riferimenti, test, build, controllo dei tipi. La lista consente a un revisore di vedere anche ciò che non è stato controllato.

Per output destinati alle persone, applica una checklist di verifica degli output AI. Il compilatore non intercetta un messaggio diventato meno chiaro o un ordine diverso che rompe un processo manuale.

Ferma la tranche quando la prova perde significato

Interrompi il refactoring se per far passare i test devi cambiare gli invarianti, se il diff si allarga a dipendenze non previste oppure se emerge un bug che richiede una decisione funzionale.

Non chiedere a Claude di “sistemare anche quello” dentro la stessa sessione di lavoro. Registra la scoperta, torna a uno stato coerente e apri un nuovo incarico. Questa disciplina mantiene leggibile il motivo di ogni modifica.

Le best practice di Claude Code danno priorità a verifiche che il modello possa eseguire e leggere. Se la prova non distingue più il prima dal dopo, aggiungere altre modifiche non la rende più informativa.

Consegna il refactoring come serie di decisioni

La consegna finale non è “codice più pulito”. Deve includere:

• obiettivo strutturale e fuori scope;

• invarianti preservati;

• tranche completate;

• file cambiati per ciascuna;

• test eseguiti e risultati;

• compatibilità controllata;

• rischi non coperti;

• modalità di ripristino.

Rivedi il diff una tranche alla volta e poi nel suo insieme. Due passaggi corretti possono interagire in un modo che i test isolati non osservano; per questo serve anche una prova finale sul percorso completo interessato.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi prendere un refactoring circoscritto, trasformarlo in un contratto degli invarianti e lavorarlo per tranche fino a una consegna leggibile e reversibile.