Prompt per proporre refactoring in passi piccoli

Questa lezione appartiene al Modulo 21 — Usare l’AI come revisore.

Obiettivo della lezione

Formulare prompt che producono un piano di refactoring in passi piccoli e verificabili — non una riscrittura completa, ma una sequenza di modifiche che mantengono il sistema funzionante ad ogni passo.

Alla fine hai un piano concreto con passi numerati che puoi eseguire uno alla volta.

Perché serve nel percorso

L’AI tende a proporre refactoring ambiziosi — “riscrivi tutto con questa struttura migliore”. Un piano del genere è difficile da eseguire senza rompere il progetto a metà. Il prompt giusto chiede esplicitamente passi piccoli con verifica intermedia.

Nel Registro del laboratorio

Scenario: registraPrestito.js è cresciuta e ora fa troppo — legge da localStorage, controlla le regole, genera l’ID, salva. Vuoi un piano per separarla in parti più piccole.

Prompt mal formulato:

Refactora registraPrestito.js per renderla migliore.

L’AI propone una riscrittura completa con TypeScript, dependency injection container, pattern Repository — troppo per fare in una sessione senza rompere nulla.

Prompt ben formulato:

Questo è il file src/application/registraPrestito.js del mio progetto
"Registro del laboratorio scolastico".

Il progetto ha 4 livelli: domain, application, infrastructure, presentation.
È scritto in JavaScript modulare senza TypeScript e senza framework.

Il problema: la funzione fa troppo — legge da localStorage, controlla le regole,
genera l'ID del prestito e salva. Voglio separarla in responsabilità più piccole.

Proponi un piano di refactoring in passi piccoli. Per ogni passo indica:
1. Cosa cambia (quale codice viene spostato o estratto)
2. Cosa rimane invariato (quali test devono continuare a passare)
3. Come si verifica che il passo è andato bene
4. Stima del tempo necessario (5/10/20 minuti)

Vincoli importanti:
- ogni passo deve lasciare il sistema funzionante
- non aggiungere TypeScript
- non introdurre framework o librerie
- il codice deve rimanere leggibile per uno studente

[incolla il contenuto di registraPrestito.js]

Risposta attesa dall’AI (esempio):

Piano di refactoring per registraPrestito.js

Passo 1 (10 min): Estrai la verifica di stato dello strumento
- Cosa cambia: crea verificaPrestabilità(strumento) in src/domain/strumento.js
- Cosa rimane: la firma di registraPrestito non cambia
- Verifica: i test esistenti passano ancora
- Rischio: nessuno — solo spostamento di codice

Passo 2 (15 min): Inietta l'archivio come dipendenza invece di leggere localStorage direttamente
- Cosa cambia: aggiorna la firma a registraPrestito(dati, archivioStrumenti, archivioPrestiti)
- Cosa rimane: la logica interna
- Verifica: aggiorna tutti i punti che chiamano registraPrestito, esegui i test
- Rischio: devi aggiornare la UI che chiama registraPrestito

Passo 3 (10 min): Sposta la generazione dell'ID nel dominio
- ...

Procedura guidata

1. Scegli la funzione da refactorare e incolla il suo contenuto nel prompt.
2. Descrivi il problema specifico (troppo lunga, troppe responsabilità, dipendenza diretta).
3. Aggiungi i vincoli (no TypeScript, no framework, ogni passo deve lasciare il sistema funzionante).
4. Chiedi il formato: numero passo, cosa cambia, verifica, stima tempo.
5. Valuta il piano proposto: i passi sono abbastanza piccoli? Sono nell’ordine giusto?
6. Esegui un passo alla volta, con test dopo ogni passo.

Attività in classe

Prendi il piano proposto dall’AI e valutalo con questi criteri:

## Valutazione del piano di refactoring

Piano proposto: [numero di passi]

Passo più grande (in tempo stimato): __
È troppo grande per una sessione? sì/no

Ordine corretto? (i passi che rompono di più vengono dopo quelli sicuri?) sì/no

Verifiche specificate per ogni passo? sì/no

Vincoli rispettati (no TypeScript, no framework)? sì/no

Passo che eseguiresti prima: __
Motivo:

Spiegazione guidata per studiare

Un buon piano di refactoring ha queste caratteristiche:

Ogni passo è indipendente: puoi fermarti dopo qualsiasi passo e il sistema funziona. Non ci sono passi che “si completano al passo 5”.

I passi più rischiosi vengono dopo: prima estrai funzioni pure (zero rischio), poi sposta responsabilità (rischio medio), poi cambia interfacce pubbliche (rischio alto e richiede aggiornare i chiamanti).

Ogni passo ha una verifica: “esegui i test” è una verifica accettabile se i test coprono il comportamento modificato. “Controlla che funzioni” non è una verifica.

Esempio di ordine corretto:

Passo 1: estrai verificaPrestabilità come funzione pura nel dominio
  (zero rischio — non cambia nessuna interfaccia pubblica)

Passo 2: aggiorna registraPrestito per usare verificaPrestabilità
  (basso rischio — modifica interna, interfaccia pubblica invariata)

Passo 3: inietta archivioStrumenti e archivioPrestiti come dipendenze
  (rischio medio — cambia la firma, devi aggiornare i chiamanti)

Passo 4: aggiorna la UI e i test per usare la nuova firma
  (passo necessario dopo il 3)

Questo ordine garantisce che dopo ogni passo il sistema sia in uno stato coerente.

Passo per passo nel progetto

1. Scegli la funzione con più problemi nel Registro.
2. Scrivi il prompt con contesto, problema, vincoli e formato richiesto.
3. Ricevi il piano e valutalo con i criteri della scheda.
4. Se i passi sono troppo grandi, chiedi all’AI di spezzarli ulteriormente.
5. Esegui il primo passo e i test.
6. Documenta nel commit cosa hai fatto e che i test passano.

Prova di comprensione

• Perché chiedere “passi piccoli” invece di “refactoring completo”?
• Come si verifica che un passo di refactoring ha lasciato il sistema funzionante?
• Qual è il rischio di invertire l’ordine dei passi (iniziare da quello più rischioso)?
• Come decidi se un passo proposto dall’AI è “abbastanza piccolo”?

Errori da evitare

• eseguire tutti i passi del piano in un unico commit — perdi la tracciabilità;
• non verificare i test dopo ogni passo — non sai quando hai introdotto il problema;
• accettare un piano con passi da “1 ora” senza chiedere di spezzarli;
• ignorare i vincoli che hai specificato nel prompt (TypeScript, framework).

Prodotto da consegnare

Il prompt usato, il piano proposto dall’AI, la valutazione del piano e almeno il primo passo eseguito con commit separato e test passati.

Checklist di chiusura

• il prompt specifica il problema, i vincoli e il formato richiesto
• il piano ha passi di massimo 20 minuti ciascuno
• ogni passo ha una verifica specificata
• i passi più rischiosi vengono dopo quelli sicuri
• almeno un passo è stato eseguito con i test che passano

Risultato atteso

Ho formulato il prompt per refactorare registraPrestito.js.
L'AI ha proposto 4 passi da 5-15 minuti ciascuno.
Ho eseguito il passo 1 (estrai verificaPrestabilità nel dominio) — i test passano.
Ho eseguito il passo 2 (usa verificaPrestabilità in registraPrestito) — i test passano.
Il prossimo passo è iniettare le dipendenze.