Iterare sul prompt: cosa cambiare quando l’output non torna

L’output non torna. Quattro reazioni possibili: rimandare lo stesso prompt sperando in fortuna; aggiungere “per favore fai meglio”; rifare tutto da zero in panico; oppure diagnosticare la causa e modificarla. Solo l’ultima funziona davvero. Le prime tre sono il modo in cui le sessioni AI scappano di mano.

Perché questa lezione conta

Iterare male è la causa principale di sessioni che bruciano ore senza arrivare al risultato. Senza diagnosi, si tira a indovinare: cambia parola qui, aggiungi vincolo lì, rilancia. Cinque iterazioni, peggiora ogni volta. Con diagnosi, una iterazione mirata risolve quasi sempre.

Obiettivo operativo

Alla fine devi saper:

1. classificare l’errore in 5 tipi e diagnosticare la causa;
2. scegliere la leva di correzione giusta in base al tipo di errore;
3. riconoscere quando smettere di iterare e fermarsi.

Nucleo della lezione

1. Cinque tipi di errore tipici

Errore di formato: output non rispetta struttura richiesta. Prosa invece di lista, codice invece di piano, lingua sbagliata.

Causa: sezione “formato” del prompt assente o debole. Soluzione: rendi formato esplicito con esempio o struttura forzata.

Errore di completezza: output corretto ma manca qualcosa. Cinque criteri richiesti, ne soddisfa tre.

Causa: criteri assenti o lunghi (modello dimentica). Soluzione: lista numerata di “deve includere”, richiesta di self-check.

Errore di scelta tecnica: stack/libreria/pattern sbagliati per il tuo contesto.

Causa: contesto debole. Modello sceglie default popolare. Soluzione: aggiungi contesto specifico (versioni, vincoli, file di regole).

Errore di esecuzione: codice non gira. Sintassi rotta, import inesistenti, API obsolete.

Causa: modello allucina o usa training stale. Soluzione: passa documentazione ufficiale, riduci a un solo problema, verifica versione, considera modello migliore o chat con web search.

Errore di scope: modello fa più o meno di richiesto. Refactor non chiesto, file non citati toccati, scope espanso.

Causa: vincoli mancanti. Soluzione: vincoli espliciti (file ammessi, divieti), istruzione “fermati dopo X passo”.

Diagnosi prima di rilanciare. Cambiare la leva sbagliata produce output peggiore, non migliore.

2. Leve di correzione

Per ogni leva, sai quando usarla:

• Aggiungere vincoli: errore di scope, scelte tecniche errate. Specifico cosa NON fare.
• Ridurre scope: errore di completezza in task troppo grande. Un passo per volta.
• Fornire esempi: errore di formato, stile. Few-shot.
• Chiedere spiegazione: incertezza sul perché del modello. Diagnosi prima del codice.
• Cambiare ordine: a volte modificare ordine sezioni del prompt produce output diversi (modelli sono più sensibili a ciò che viene dopo).
• Aumentare contesto: errore di scelta tecnica perché manca info. Aggiungi file rilevanti.
• Ridurre contesto: errore di attenzione perché contesto troppo lungo. Taglia rumore.
• Cambiare modello: errore di esecuzione persistente, ragionamento debole. Passa a frontier o a modello specializzato.
• Cambiare strumento: chat → IDE AI → agente CLI quando serve filesystem reale.

3. Quando smettere

Non sempre si itera. Smettere ha senso quando:

• 3+ iterazioni senza progresso: stesso errore ricorre. Fermati, rileggi specifica.
• Specifica vaga: il problema non è nel prompt, è prima. Torna al brief.
• Il task è troppo grande: nessuna iterazione lo salva. Decomponi.
• Il dominio è fuori portata del modello: dettaglio tecnico non noto. Cerca documentazione, scrivi a mano, chiedi a esperto umano.
• Stai contraddicendo te stesso: chiedi cose incompatibili tra loro. Risolvi conflitto prima di iterare.

Smettere non è fallimento. Iterare ciecamente sì.

Procedura pratica

Quando un output non torna:

1. Pausa, niente reset istintivo. Non rilanciare lo stesso prompt.
2. Classifica errore: formato, completezza, tecnica, esecuzione, scope.
3. Diagnosi sezione del prompt corrispondente.
4. Scegli UNA leva di correzione, non tre.
5. Modifica prompt in modo mirato. Annota la modifica.
6. Rilancia, osserva.
7. Se ancora non torna dopo 3 iterazioni: fermati, controlla se è il momento di smettere.

Tieni un mini-diario delle iterazioni: prompt iniziale → sintomo → modifica applicata → risultato. Diventa la tua libreria personale di pattern di errore.

Laboratorio guidato

Prendi un task non banale e attivamente sbaglialo per imparare a iterare.

Iter 0 (prompt volutamente debole): “fammi una funzione per validare email”.

Output probabile: regex semplificata, niente edge case, in JS, niente test.

Iter 1 — diagnosi: errore di scope (regex troppo permissiva), errore di formato (no test). Leva: aggiungi vincoli + criteri.

Prompt rivisto: “fammi una funzione validateEmail(email: string): {valid: boolean, error?: string} in TypeScript. Edge case: stringa vuota, no @, multipli @, dominio senza dot, IDN, lunghezza > 254 caratteri (RFC 5321). Includi 5 test con casi limite.”

Output probabile: migliore, ma forse lib esterna o regex iperingegnerizzata.

Iter 2 — diagnosi: scelta tecnica (lib esterna). Leva: vincolo “no dipendenze esterne”.

Prompt rivisto: aggiungi vincolo “no dipendenze esterne, regex semplice + check programmatici. Doppio @, dominio senza dot, lunghezza, sono check separati, non un mega-regex.”

Output probabile: ora dovrebbe essere ragionevole.

Annota le iterazioni, le diagnosi, le leve. Esercizio fa vedere come una sequenza ordinata di iterazioni mirate converge in 2-3 round, mentre iterazioni cieche divergerebbero.

Output atteso

Una tabella personale “errore tipico → leva di correzione” da consultare quando un output non torna. Riempila con casi reali del tuo lavoro, non solo teoria.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: diagnosticare se il problema è nel prompt, nel contesto, nel modello, nel task o nelle aspettative. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Tipi di errore: output fuori formato, soluzione incompleta, scelta tecnica sbagliata, codice non eseguibile, requisiti ignorati.
• Leve di correzione: aggiungere vincoli, ridurre scope, fornire esempi, chiedere spiegazione, cambiare ordine delle richieste.
• Quando non iterare ancora: fermarsi, rileggere la specifica, testare manualmente o scrivere a mano il pezzo critico.

3. Applicazione: svolgi il laboratorio: prendere un output mediocre e migliorarlo con massimo tre iterazioni documentate. L’output da ottenere è: un diario di iterazione con prompt iniziale, sintomi, modifica applicata e risultato osservato.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• so classificare un errore di output in uno dei 5 tipi;
• ho almeno 3 iterazioni recenti documentate (prompt, sintomo, modifica, esito);
• ho una soglia personale di “smettere”: 3 iter senza progresso, fermo;
• non rilancio mai due volte lo stesso prompt sperando in fortuna.

Errori comuni

Rilanciare uguale. Stesso prompt = stesso output ± rumore. Se non hai cambiato, non aspettarti diverso.

Cambiare 5 cose insieme. Non sai quale ha funzionato. Una variabile alla volta.

“Per favore fai meglio”. Non è una leva. Specifica cosa modificare.

Non documentare iterazioni. Domani rifai stessi errori. Diario di iterazione costa 1 minuto, salva ore.

Iterare quando il problema è specifica. Specifica vaga genera prompt vaghi. Torna al brief.

Cambiare modello come prima leva. Spesso il modello non è il problema, è il prompt. Modello cambiato dopo aver verificato che il prompt sia solido.

Prompt di lavoro

Sto iterando su un prompt che non sta producendo l'output che voglio.

Prompt iniziale:
[copia prompt]

Output ricevuto (sintomi):
[descrivi cosa è andato storto, sii specifico: format errato, manca X, stack sbagliato, scope troppo largo]

Aiutami a:
1. Classificare l'errore in uno di: formato / completezza / scelta tecnica / esecuzione / scope.
2. Identificare la sezione del prompt che è debole.
3. Suggerire UNA leva di correzione (aggiungere vincoli / ridurre scope / esempi / spiegazione / contesto).
4. Riscrivere il prompt con la modifica applicata. Cambia UNA cosa, non tre.

Non rispondere al prompt originale. Stiamo lavorando sul prompt, non sul task.

Esercizio finale

Per la prossima settimana, ogni iterazione AI documenta in 4 righe: prompt iniziale, sintomo, leva applicata, risultato. A fine settimana rileggi il diario. Quale tipo di errore ricorre più spesso? Quale leva è la più efficace per te? Quel pattern personale è la tua “guida di iterazione” tarata sul tuo modo di scrivere prompt — molto più utile di qualsiasi guida generica.