Codex come revisore, non come autore automatico

Questa lezione appartiene al Modulo 20 — Strumenti e automazione.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. Questa lezione insegna a usare gli strumenti AI come revisori del codice — non come generatori automatici di cui copiare l’output.

Obiettivo della lezione

Imparare a formulare prompt di revisione utili per Copilot, Claude o Codex, a leggere criticamente le risposte e a decidere cosa accettare, cosa modificare e cosa rifiutare.

Alla fine devi avere: un esempio di sessione di revisione documentata, con il prompt usato, la risposta ricevuta e la decisione presa.

La distinzione fondamentale

Ci sono due modi di usare uno strumento AI nel codice:

• Autore automatico: scrivi un commento o un prompt, l’AI genera il codice, tu lo incolli. Non hai capito cosa fa.
• Revisore: porti il tuo codice già scritto, chiedi all’AI di trovare problemi, ricevi suggerimenti e li valuti criticamente.

Il primo modo è rischioso: il codice generato potrebbe non rispettare l’architettura del Registro, introdurre dipendenze sbagliate o risolvere il problema nel livello sbagliato. Il secondo modo è utile: un revisore esterno (umano o AI) vede cose che l’autore non vede più perché è troppo abituato al codice.

Come formulare un prompt di revisione

Un prompt di revisione efficace deve essere specifico. Deve indicare:

• quale file o funzione stai mostrando
• quale aspetto vuoi che venga revisionato
• quale vincolo architetturale deve essere rispettato

Un prompt vago produce una risposta vaga. Un prompt specifico produce una risposta utile.

Procedura guidata

1. Scegli una funzione del Registro che vuoi far revisionare (es. un caso d’uso, un adapter, un gestore di eventi).
2. Scrivi il prompt di revisione seguendo il formato della sezione successiva.
3. Invia il prompt all’AI e leggi la risposta.
4. Per ogni suggerimento, decidi: accetto, modifico, rifiuto — e perché.
5. Documenta la sessione nella scheda.

Attività in classe

Compila questa scheda dopo la sessione di revisione:

## Sessione di revisione AI

File revisionato:
Prompt usato:
Risposta ricevuta (riassunto):
Suggerimento 1: accettato / modificato / rifiutato — motivo:
Suggerimento 2: accettato / modificato / rifiutato — motivo:
Cosa avrei perso se avessi incollato la risposta senza leggerla:

Spiegazione guidata per studiare

Un revisore AI fa quello che gli chiedi. Se gli chiedi “scrivi il codice per aprire un prestito”, ti dà del codice — ma probabilmente non rispetta la struttura del Registro, usa fetch invece di localStorage, mette la logica nel posto sbagliato. Se gli chiedi “rivedi questa funzione e dimmi se rispetta il principio che i casi d’uso non devono importare localStorage direttamente”, ti dà un’analisi molto più utile.

La differenza non è nello strumento — è nel modo in cui lo usi. Usarlo come revisore richiede che tu abbia già scritto il codice e che tu sappia cosa stai cercando.

Passo per passo nel progetto

1. Scegli una funzione da revisionare. Esempio: apriPrestito in application/.
2. Formula un prompt di revisione specifico. Ecco tre template:

Template 1 — revisione architetturale:

Questo è il caso d'uso apriPrestito del mio progetto Registro del laboratorio scolastico.
Il progetto ha 4 livelli: domain, application, infrastructure, presentation.
Il livello application non deve importare localStorage, fetch o DOM.
Rivedi questa funzione e dimmi se viola questo principio:

[incolla il codice della funzione]

Cerca solo violazioni architetturali, non miglioramenti di stile.

Template 2 — revisione della gestione degli errori:

Questo è il gestore del click sul pulsante "Presta" nel mio Registro.
Voglio verificare che:
1. l'input venga validato prima di chiamare il caso d'uso
2. ogni errore abbia un messaggio in italiano per l'utente
3. non vengano esposti dettagli tecnici nella UI

Rivedi questo codice e dimmi cosa manca:

[incolla il codice del gestore]

Template 3 — revisione della testabilità:

Questo è il caso d'uso cercastrumenti del mio Registro.
Voglio sapere se posso testarlo senza browser e senza localStorage.
Rivedi la funzione e dimmi se dipende da qualcosa che non posso controllare in un test:

[incolla il codice]

1. Leggi la risposta dell’AI. Per ogni suggerimento, fai queste domande:

   • Ha capito il contesto del progetto?
   • Il suggerimento rispetta la struttura a 4 livelli?
   • Sta risolvendo il problema nel livello giusto?
   • Introduce una dipendenza che non voglio?

2. Esempio di risposta AI da valutare criticamente:

Risposta AI: "Potresti aggiungere un indice locale in memoria per velocizzare 
la ricerca per ID invece di usare Array.find ogni volta."

Come valutarla: è un’ottimizzazione prematura? Quanti strumenti ho nel Registro? 50? L’ottimizzazione è necessaria? Dove andrebbe la cache — nel caso d’uso o nell’adapter? Se va nell’adapter, cambia il contratto? La risposta potrebbe essere tecnicamente corretta ma sbagliata per il contesto.

1. Esempio di risposta utile da accettare:

Risposta AI: "La funzione apriPrestito chiama archivioStrumenti.caricaTutti() 
due volte: una per cercare lo strumento e una per salvare. Puoi usare l'array 
già caricato nella prima chiamata invece di ricaricarlo."

Questa è una osservazione concreta, verificabile, che non introduce dipendenze nuove. Si accetta e si corregge.

Esempio JS — come documentare la sessione

// PRIMA della revisione
export function apriPrestito({ strumentoId }, archivioStrumenti, archivioPrestiti) {
  const strumenti = archivioStrumenti.caricaTutti();
  const strumento = strumenti.find(s => s.id === strumentoId);
  if (!strumento) throw new Error("STRUMENTO_NON_TROVATO");

  // BUG trovato dalla revisione AI: secondo caricaTutti ridondante
  const tuttiGliStrumenti = archivioStrumenti.caricaTutti();
  tuttiGliStrumenti.find(s => s.id === strumentoId).stato = "in-prestito";
  archivioStrumenti.salva(tuttiGliStrumenti);
}

// DOPO la revisione
export function apriPrestito({ strumentoId }, archivioStrumenti, archivioPrestiti) {
  const strumenti = archivioStrumenti.caricaTutti(); // una sola lettura
  const strumento = strumenti.find(s => s.id === strumentoId);
  if (!strumento) throw new Error("STRUMENTO_NON_TROVATO");
  if (strumento.stato !== "disponibile") throw new Error("STRUMENTO_NON_DISPONIBILE");
  strumento.stato = "in-prestito";
  archivioStrumenti.salva(strumenti); // stessa array, non ricaricata
}

Prova di comprensione

Rispondi per iscritto:

• Qual è la differenza tra chiedere all’AI “scrivi questa funzione” e “rivedi questa funzione”?
• Come riconosci una risposta AI che non ha capito il contesto del tuo progetto?
• Quale tipo di suggerimento AI è più probabile che sia sbagliato per il Registro?
• Se l’AI suggerisce di usare un framework esterno per risolvere un problema semplice, come risponderesti?

Errori da evitare

• incollare il codice generato senza leggerlo e capirlo;
• accettare un suggerimento solo perché l’AI sembra sicura;
• formulare prompt vaghi come “migliora questo codice” senza specificare il criterio;
• usare l’AI per scrivere il codice che non capisci invece di chiedere spiegazioni;
• non documentare la sessione di revisione — il ragionamento è parte del lavoro.

Prodotto da consegnare

La scheda della sessione di revisione compilata: prompt usato, risposta ricevuta, decisioni motivate per ogni suggerimento. Come verifica: mostra al docente il prima/dopo del codice e spiega perché hai accettato o rifiutato i suggerimenti.

Checklist di chiusura

• il prompt di revisione era specifico e indicava il vincolo architetturale;
• ho valutato ogni suggerimento individualmente, non ho accettato tutto;
• ho documentato almeno un suggerimento rifiutato con motivazione;
• il codice finale è migliorato rispetto a prima della revisione;
• capisco ogni riga del codice risultante.

Risultato atteso

Ho usato un prompt di revisione specifico su apriPrestito.
L'AI ha trovato: [descrizione del problema reale].
Ho accettato: [suggerimento accettato].
Ho rifiutato: [suggerimento rifiutato] — perché: [motivazione].
Il codice dopo la revisione è migliorato in: [aspetto specifico].