Leggere criticamente un report di Codex

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

Obiettivo della lezione

Saper leggere un report di revisione generato da uno strumento AI (GitHub Copilot, Claude, ChatGPT) sul codice del Registro e decidere in modo autonomo cosa applicare, cosa rifiutare e cosa approfondire prima di agire.

Alla fine non accetti i suggerimenti automaticamente — li verifichi sul tuo codice reale.

Perché serve nel percorso

Gli strumenti AI sono bravi a identificare pattern comuni, ma non conoscono il contesto specifico del tuo progetto. Un suggerimento corretto in generale può essere sbagliato per il Registro — o può suggerire un refactoring che rompe un confine che hai costruito con attenzione.

Nel Registro del laboratorio

Supponi di aver inviato questo file a un AI per la revisione:

// src/application/registraPrestito.js (versione fragile per l'esercizio)
export function registraPrestito(strumentoId, studenteId) {
  const strumenti = JSON.parse(localStorage.getItem("registro_strumenti") || "[]");
  const strumento = strumenti.find(s => s.id === strumentoId);
  if (!strumento) throw new Error("Strumento non trovato");
  if (strumento.stato !== "disponibile") throw new Error("Non disponibile");
  strumento.stato = "in_prestito";
  localStorage.setItem("registro_strumenti", JSON.stringify(strumenti));
}

L’AI potrebbe rispondere con un report come questo:

REPORT AI — revisione registraPrestito.js

1. [CRITICO] La funzione accede direttamente a localStorage.
   Suggerimento: iniettare l'archivio come dipendenza.

2. [MEDIO] Mancanza di gestione errori per JSON.parse.
   Suggerimento: aggiungere try/catch.

3. [BASSO] Il messaggio "Strumento non trovato" dovrebbe essere un codice come STRUMENTO_NON_TROVATO.
   Suggerimento: usare costanti per i codici errore.

4. [BASSO] Considera di aggiungere TypeScript per type safety.
   Suggerimento: convertire il progetto a TypeScript.

5. [MEDIO] La funzione modifica direttamente l'oggetto strumento (mutazione).
   Suggerimento: usare spread operator { ...strumento, stato: "in_prestito" }.

Procedura guidata

Per ogni punto del report, applica questo processo:

1. Leggi e capisce il problema descritto — non il suggerimento, il problema.
2. Verifica se il problema esiste nel tuo codice reale (apri il file, controlla).
3. Valuta l’impatto sul Registro specifico: questo problema causa bug visibili? Rende difficile cambiare qualcosa?
4. Decidi: applica, rimanda, rifiuta motivando.
5. Se applichi, fallo in un commit separato con un messaggio chiaro.

Attività in classe

Analizza il report dell’esempio e compila questa tabella:

## Valutazione report AI

| N. | Problema descritto | Esiste nel mio codice? | Applico? | Motivazione |
|----|-------------------|------------------------|----------|-------------|
| 1  | localStorage diretto | sì/no | sì/no/rimando | ... |
| 2  | try/catch mancante | sì/no | sì/no/rimando | ... |
| 3  | codici errore | sì/no | sì/no/rimando | ... |
| 4  | TypeScript | sì/no | sì/no/rimando | ... |
| 5  | mutazione oggetto | sì/no | sì/no/rimando | ... |

Poi identifica: quale suggerimento migliorava davvero il progetto? Quale era inapplicabile o fuori contesto?

Spiegazione guidata per studiare

Un report AI è un punto di partenza, non una lista di istruzioni da seguire. Gli strumenti AI hanno bias precisi:

Tendono a suggerire troppo. Un tool come Copilot o Claude preferisce segnalare più problemi che meno. Molti “problemi” sono questioni di stile o preferenze, non errori reali.

Non conoscono il tuo contesto. Il suggerimento numero 4 (aggiungere TypeScript) è tecnicamente corretto come best practice generale, ma è fuori scala per un progetto scolastico con 4 settimane di tempo. L’AI non sa che hai un vincolo.

Come valutare un suggerimento:

• Critico (accetta quasi sempre): dipendenze dirette, assenza di gestione errori, comportamenti non deterministici.
• Medio (valuta il costo): refactoring strutturali, cambio di convenzioni — applica solo se il costo è giustificato ora.
• Basso (rimanda o ignora): stile, TypeScript, pattern avanzati — decidi tu quando ha senso.

Il test del suggerimento: prima di applicarlo, chiediti: “se non applico questo, cosa si rompe?” Se la risposta è “niente di visibile”, puoi rimandare.

// Suggerimento 5 — mutazione oggetto
// Prima (mutazione):
strumento.stato = "in_prestito";

// Dopo (spread, suggerito dall'AI):
const strumentoAggiornato = { ...strumento, stato: "in_prestito" };
archivio.aggiorna(strumentoAggiornato);

Questo suggerimento è corretto e vale la pena applicarlo — la mutazione diretta dell’oggetto può causare bug sottili se l’oggetto viene riusato.

Passo per passo nel progetto

1. Copia uno dei tuoi file applicativi in un prompt AI e chiedi una revisione.
2. Ricevi il report e numeralo.
3. Per ogni punto: apri il file reale e verifica se il problema esiste davvero.
4. Assegna una priorità: applica ora / rimanda / rifiuta.
5. Per i punti che applichi: fai una modifica alla volta con un commit separato.
6. Dopo ogni modifica: esegui i test esistenti e verifica che il comportamento non sia cambiato.

Prova di comprensione

• Perché un report AI segnala 5 problemi ma solo 2 sono urgenti?
• Come si verifica se un suggerimento migliora davvero il progetto specifico?
• Qual è il rischio di applicare tutti i suggerimenti senza valutarli?
• Cosa dovresti documentare dopo aver letto un report AI?

Errori da evitare

• applicare tutti i suggerimenti in blocco senza capirli — rischi di rompere confini che hai costruito;
• rifiutare tutti i suggerimenti per principio — qualcuno è genuinamente utile;
• applicare suggerimenti di stile prima di risolvere problemi strutturali;
• non verificare sul codice reale se il problema segnalato esiste davvero.

Prodotto da consegnare

La tabella di valutazione del report compilata, con motivazioni per ogni decisione. Almeno un suggerimento applicato con commit separato e verifica che i test passino.

Checklist di chiusura

• ogni punto del report è stato verificato sul codice reale
• ogni decisione (applica/rimanda/rifiuta) ha una motivazione scritta
• i suggerimenti applicati sono stati fatti in commit separati
• i test passano dopo ogni modifica
• i suggerimenti fuori contesto sono stati rifiutati con motivazione

Risultato atteso

Ho letto il report AI su registraPrestito.js.
Ho applicato i punti 1 e 5 (dipendenza iniettata, no mutazione diretta).
Ho rimandato il punto 2 (try/catch) alla lezione sulla robustezza.
Ho rifiutato il punto 4 (TypeScript) — fuori scala per questo progetto.
I test passano dopo le modifiche. Ho documentato le decisioni nel README.