Prompt per refactor: prima il piano, poi il diff

Un refactor cambia struttura senza voler cambiare comportamento. Proprio per questo è pericoloso affidarlo a un prompt generico. Prima serve un piano: cosa cambiare, cosa non cambiare, quali test proteggono il comportamento e quale passo è abbastanza piccolo da essere revisionato.

Perché questa lezione conta

Gli LLM tendono a “migliorare” più di quanto richiesto. In un refactor questo può significare rinominare troppe cose, spostare responsabilità, cambiare API, introdurre pattern non necessari o rompere casi limite. Separare piano e diff riduce il rischio.

Fase 1: analisi e piano

La prima richiesta non deve modificare codice.

Analizza questo modulo per un refactor.
Non scrivere patch.

Restituisci:
1. responsabilità attuali;
2. problemi concreti;
3. rischio di regressione;
4. piano in passi piccoli;
5. test da eseguire prima e dopo.

Questa fase serve a leggere il pensiero del modello prima che tocchi file.

Fase 2: patch minima

Solo dopo aver scelto un passo:

Applica solo il passo 1 del piano approvato.
Vincoli:
- non cambiare comportamento pubblico;
- non rinominare export;
- non modificare file fuori elenco;
- mantieni test esistenti verdi.

Chiudi con diff sintetico e verifiche.

Il refactor diventa una serie di diff piccoli, non una riscrittura.

Criteri per un buon piano

Un piano di refactor è buono se:

• ha passi ordinati;
• ogni passo è reversibile;
• distingue problemi reali e preferenze;
• indica file coinvolti;
• collega ogni passo a una verifica;
• non introduce architettura “per bellezza”.

Laboratorio guidato

Scegli una funzione lunga, un componente con troppe responsabilità o un modulo con duplicazione.

1. Chiedi al modello un refactor diretto e conserva il diff.
2. Ripeti chiedendo prima piano senza patch.
3. Scegli solo il primo passo.
4. Applica il passo.
5. Confronta i due diff.

Valuta:

Criterio	Refactor diretto	Piano + passo
File toccati
Comportamento cambiato
Diff leggibile
Test chiari
Rischio rollback

Output atteso

Una procedura “analizza poi modifica” formalizzata in due prompt.

Template:

Prompt A - Piano:
Analizza, non modificare. Trova passi piccoli, rischi, test.

Prompt B - Diff:
Applica solo il passo approvato. Mantieni comportamento. Chiudi con verifica.

Checklist di verifica

• il piano precede il diff;
• ogni passo ha un criterio di verifica;
• il diff è piccolo e revisionabile;
• non sono cambiate API pubbliche senza richiesta;
• esiste un modo semplice per tornare indietro.

Errori comuni

Chiedere “rifattorizza tutto”. È un invito a una patch enorme.

Confondere refactor e redesign. Se cambia il comportamento o l’architettura pubblica, non è solo refactor.

Non avere test prima. Senza test o scenario manuale, non sai se il comportamento è rimasto uguale.

Collegamenti

• Modulo: Prompt per il ciclo di codice — lezione 17 del corso.
• Lezione precedente: Prompt per generare funzioni e componenti.
• Prossima lezione: Prompt per code review: severità e categorie.