Il ciclo: idea, specifica, prompt, codice, diff, verifica

Il vibe coding non è “scrivi prompt, ricevi codice”. È un ciclo a sei fasi, ognuna con un input e un output osservabile. Saltare una fase non rende il lavoro più veloce: rende il lavoro più rischioso, e prima o poi devi tornare indietro.

Perché questa lezione conta

Senza un ciclo esplicito, le sessioni con AI seguono un pattern tipico: idea → prompt → codice → “non funziona” → fix → “ancora non funziona” → frustrazione. Il problema non è il modello, è la struttura del lavoro. Il ciclo a sei fasi rende espliciti i punti di controllo e ti permette di interrompere quando una fase non è pronta, invece di trascinare ambiguità in avanti.

Obiettivo operativo

Alla fine devi saper:

1. nominare le sei fasi e cosa entra/esce da ciascuna;
2. riconoscere quale fase stai saltando quando un task va male;
3. usare il ciclo come template ripetibile su task piccoli e grandi.

Nucleo della lezione

1. Sei fasi, sei output osservabili

Idea: intuizione iniziale, una frase. Output: un’espressione del bisogno in linguaggio naturale. Es: “vorrei una feature per esportare ordini in CSV”.

Specifica: l’idea raffinata in qualcosa di verificabile. Output: cosa fa la feature, per chi, con quali input, con quale output, in quali casi. Es: “endpoint GET /orders/export?from=...&to=... restituisce CSV con colonne id, data, totale, stato; protetto da ruolo admin; max 10.000 righe.”

Prompt: la specifica trasformata in istruzione operativa per il modello. Output: testo strutturato con ruolo, contesto, obiettivo, vincoli, formato.

Codice: il diff prodotto dal modello. Output: modifiche concrete al filesystem, leggibili in git diff.

Diff: la lettura attiva del codice generato. Output: una decisione (accetta / modifica / rifiuta) motivata su file modificati, dipendenze aggiunte, edge case coperti.

Verifica: l’esecuzione che dimostra il comportamento. Output: log, screenshot, test passati, comando eseguito che produce il risultato atteso.

Saltare una fase = non avere il suo output. Senza specifica non sai cosa verificare. Senza diff non sai cosa hai accettato. Senza verifica hai una promessa, non un fatto.

2. Il diff come unità minima di fiducia

Un punto chiave: la fiducia non si dà alla risposta del modello, si dà al diff. Risposta vs diff sono cose diverse:

• Risposta: testo che il modello scrive in chat. Dichiarativo, può contenere “ho aggiornato X” anche quando non l’ha fatto, o l’ha fatto male.
• Diff: modifica concreta sul filesystem, visibile via git diff. Fattuale, non interpretabile.

Leggere la risposta è leggere il marketing. Leggere il diff è leggere il prodotto. Quando una sessione va bene, i due coincidono. Quando va male, divergono — e tu te ne accorgi solo se guardi il diff.

Pratica: prima di accettare un agente che modifica più file, sempre git diff (o equivalente nell’IDE) prima del commit. Se il diff è troppo grande per leggerlo, il task era troppo grande per generare.

3. Verifica continua

La verifica non è “alla fine controllo”. È distribuita: piccola verifica dopo ogni fase.

• Dopo idea: ho davvero un problema, o solo un’intuizione?
• Dopo specifica: la specifica copre il caso normale e almeno un caso difficile?
• Dopo prompt: il modello ha capito (chiedi parafrasi prima del codice)?
• Dopo codice: il diff è leggibile, contenuto, focalizzato?
• Dopo diff: i criteri di accettazione sono visibili nel codice?
• Dopo esecuzione: il comportamento osservato corrisponde alla specifica?

Verifica continua = costi di correzione bassi. Verifica solo finale = costi alti, perché un errore alla fase 1 si è propagato fino alla 6.

Procedura pratica

Sequenza completa per un task di un’ora:

1. Idea (5 min): scrivi una frase. “Cosa voglio costruire?”
2. Specifica (15 min): trasforma in 5 righe verificabili. Cosa, input, output, vincoli, criteri di “fatto”.
3. Prompt (5 min): usa template (vedi prompt di lavoro qui sotto). Includi specifica testuale.
4. Piano dal modello (10 min): prima del codice chiedi piano + assunzioni. Correggi.
5. Codice (10 min): autorizza un solo passo. Stop.
6. Diff (5 min): leggi diff prima del commit.
7. Verifica (10 min): esegui, testa caso normale e un edge case.

Se sfori un’ora: il task era troppo grande, dividi.

Laboratorio guidato

Mini feature: aggiungi a una piccola app un contatore di click salvato in localStorage che persiste fra refresh.

Esegui le sei fasi separatamente, fermandoti ad ogni fase per scrivere l’output:

• Idea: una frase.
• Specifica: 5 righe (input, output, persistenza, edge case di storage pieno o disabilitato, criteri).
• Prompt: testo completo che invieresti.
• Codice: diff ricevuto.
• Diff: tre osservazioni (file modificati, scelte tecniche, rischi).
• Verifica: cosa hai testato, cosa hai osservato, cosa è rimasto incerto.

Tempo target: 30 minuti totali.

Output atteso

Un template riusabile a sei sezioni, ciascuna con: obiettivo della fase, output atteso, domanda di controllo per passare alla successiva. Esempio domanda di controllo dopo specifica: “potrei dare questa specifica a un’altra persona e ricevere lo stesso risultato che voglio io?”. Se no, raffina prima di passare al prompt.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: imparare il ciclo operativo che tiene insieme creatività e controllo tecnico durante una sessione di vibe coding. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Idea come punto di partenza grezzo, specifica come contratto, prompt come istruzione operativa.
• Il diff come unità minima di fiducia: non si valuta il fascino della risposta, si valuta la modifica concreta.
• Verifica continua: esecuzione, test, lettura e confronto con i criteri di successo.

3. Applicazione: svolgi il laboratorio: simulare una sessione completa su una mini feature, interrompendosi dopo ogni fase per scrivere cosa è cambiato. L’output da ottenere è: un template riutilizzabile di ciclo di lavoro con sezioni per specifica, prompt, diff, test e revisione.

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 nominare le sei fasi senza guardare;
• ho un esempio personale di task in cui ho saltato una fase e ho pagato il costo;
• distinguo “risposta del modello” da “diff sul filesystem”;
• ho una procedura per fermare il ciclo a metà se una fase non è pronta.

Errori comuni

Saltare la specifica. Idea → prompt direttamente è la causa più frequente di output errati. Senza specifica, il prompt è vago e il modello inventa.

Confondere “il modello ha detto di averlo fatto” con “è stato fatto”. Sempre verificare diff e comportamento.

Verificare solo a fine ciclo. Un errore di fase 2 trovato a fase 6 costa 6 volte tanto un errore di fase 2 trovato a fase 3.

Trattare il ciclo come lineare e mai iterativo. A volte un errore in fase 5 ti rimanda a fase 2. È normale. Il ciclo è una guida, non un binario.

Prompt di lavoro

Sto applicando il ciclo idea→specifica→prompt→codice→diff→verifica.

Specifica:
[5 righe: cosa, input, output, vincoli, criteri di "fatto"]

Sono in fase "prompt → piano". Prima di generare codice:

1. Parafrasa la specifica con parole tue.
2. Lista assunzioni che stai facendo.
3. Proponi piano in 3-5 passi, ognuno con criterio di verifica.
4. Indica quale passo dovrei autorizzare per primo, e perché.

Non scrivere codice. Aspetto autorizzazione esplicita.

Esercizio finale

Riprendi un task fallito o difficile della tua esperienza recente. Ricostruiscilo a posteriori sulle sei fasi. In quale fase è andato storto? Quasi sempre la specifica era debole o saltata. Riscrivi quella fase ora, con la chiarezza del senno di poi: è la lezione più utile per il prossimo task.