Regressioni di prompt: versionare e confrontare

Un prompt può regredire come una funzione. Cambi una frase per migliorare un caso, ma ne rompi tre che funzionavano. Aggiungi un esempio, ma il modello diventa troppo letterale. Sposti un vincolo, ma l’output perde formato. Se non versioni e non confronti, te ne accorgi quando qualcuno usa il prompt in un contesto reale.

Questa lezione porta le abitudini del software engineering dentro il lavoro sui prompt: file, diff, changelog, test, review e rollback.

Perché questa lezione conta

Nel lavoro individuale puoi tollerare un prompt “vivo” in una chat. In un team non basta. Se un prompt decide come classificare ticket, generare test, fare review o chiamare tool, ogni modifica produce comportamento. Quel comportamento va tracciato.

La regressione più pericolosa non è l’errore evidente. È il miglioramento apparente: l’output su un esempio diventa più elegante, ma il prompt perde robustezza sui casi limite.

Obiettivo operativo

Alla fine della lezione devi saper trattare un prompt come un artefatto versionato: capire cosa è cambiato, perché è cambiato, quali casi sono migliorati, quali sono peggiorati e come tornare indietro.

Struttura minima di una directory prompt

Una struttura semplice basta:

prompts/
  code-review/
    prompt.md
    README.md
    eval-cases.jsonl
    changelog.md
    runs/
      2026-05-31-v1.2.md

prompt.md contiene il prompt effettivo, non appunti sparsi. README.md spiega scopo, proprietario, modello consigliato, parametri e limiti noti. eval-cases.jsonl conserva i casi di valutazione. changelog.md registra le decisioni. runs/ contiene i risultati più importanti, soprattutto quando una modifica è controversa.

La parte più importante è il diff. Un prompt in un documento condiviso può cambiare senza storia. Un prompt in Git racconta cosa è successo.

Versionare cosa, esattamente

Versiona almeno:

1. testo del prompt;
2. versione del modello o classe di modello usata;
3. parametri rilevanti: temperatura, max output, top-p se usato;
4. formato di input;
5. formato di output;
6. dataset di eval;
7. criteri di accettazione.

Se cambi il prompt ma anche il dataset, il confronto è meno leggibile. A volte è necessario, ma va dichiarato. La disciplina utile è: una modifica di comportamento per volta.

Confronto A/B

Un confronto A/B tra prompt non è una gara estetica. È una tabella:

caso        v1.1   v1.2   nota
review-001  pass   pass   output piu conciso
review-007  fail   pass   ora rileva race condition
review-012  pass   fail   regressione: segnala falso positivo P1
review-019  pass   pass   costo +18%

La decisione non è sempre “vince chi ha più pass”. Un fallimento su un caso critico può bloccare una versione anche se la media migliora. Un aumento di costo può essere accettabile per un flusso manuale e inaccettabile per un’automazione ad alto volume.

Changelog decisionale

Un changelog utile non dice solo “migliorato prompt”. Dice:

## v1.2

Motivo:
- ridurre falsi positivi nelle review frontend.

Cambiamento:
- aggiunto vincolo: non proporre refactor se il diff non modifica l'area coinvolta.
- aggiunto esempio negativo su naming non critico.

Risultato eval:
- 18/20 pass, prima 17/20.
- migliorati review-006 e review-007.
- regressione su review-012: falso positivo ancora presente ma severita scesa da P1 a P2.

Decisione:
- adottare in beta per una settimana.

Questa forma permette a un collega di capire la scelta senza rileggere tutta la chat.

Quando accettare una regressione

Non tutte le regressioni bloccano. Devi distinguere:

Regressione bloccante. Rompe casi di sicurezza, produce output non parsabile, aumenta falsi negativi su bug critici, viola policy sui dati.

Regressione tollerabile. Peggiora stile, aumenta verbosità controllata, fallisce un caso raro a basso impatto ma migliora casi frequenti.

Regressione da monitorare. Non blocca il rilascio, ma richiede un controllo dopo uso reale.

Questa classificazione va scritta prima del confronto, non dopo, altrimenti rischi di razionalizzare il risultato che preferisci.

Laboratorio guidato

Prendi un prompt esistente e portalo in una directory versionata. Crea due versioni:

1. v1: prompt attuale;
2. v2: modifica mirata a un problema concreto.

Esegui entrambe sullo stesso dataset minimo. Produci un report con tre sezioni: miglioramenti, regressioni, decisione. Non limitarti al conteggio pass/fail: aggiungi note qualitative sui casi ad alto impatto.

Output atteso

Alla fine devi avere:

1. una directory prompts/ ordinata;
2. un prompt versionato;
3. un dataset stabile;
4. un report di confronto;
5. una decisione esplicita di adozione, rollback o ulteriore iterazione.

Errori comuni

Tenere la versione solo nel nome file. prompt_finale_v3_buono.md non è versionamento. Serve storia, diff e motivo.

Accettare modifiche senza eval. È come fare merge senza test su una funzione usata in produzione.

Cambiare il dataset per far vincere la nuova versione. Il dataset può evolvere, ma non deve diventare uno strumento per giustificare una scelta già presa.

Ignorare costo e latenza. Una regressione operativa può essere più grave di una piccola regressione qualitativa.

Checklist di verifica

• il prompt vive in un file versionato;
• ogni modifica importante ha un motivo scritto;
• confronto due versioni sullo stesso dataset;
• distinguo regressioni bloccanti, tollerabili e da monitorare;
• posso fare rollback senza ricostruire il prompt da una chat.

Collegamenti

• Modulo: Affidabilità: valutazione, sicurezza, costi — questa lezione è la numero 27 del corso.
• Dipende dal dataset minimo costruito nella lezione 26.