Chiedere prima un piano, poi il codice

Il piano è il punto di controllo a costo zero. Correggere un piano richiede 2 minuti; correggere codice già generato in 5 file ne richiede 30. La regola è semplice: prima il piano, mai il codice senza piano. La regola è ignorata in pratica perché chiedere un piano “rallenta”. È un’illusione: rallenta i 5 minuti iniziali, accelera l’ora successiva.

Perché questa lezione conta

Senza piano esplicito, il modello sceglie autonomamente architettura, file da creare, dipendenze, pattern. Spesso male per il tuo contesto. Quando il codice è già scritto, le scelte sbagliate sono incorporate: rifiutare significa rigenerare tutto, accettare significa correggere file per file. Con piano esplicito, le scelte sono visibili prima del codice e correggibili in pochi messaggi.

Obiettivo operativo

Alla fine devi saper:

1. distinguere “piano utile” da “piano di facciata”;
2. forzare il modello a produrre piano prima del codice e a non saltare la fase;
3. valutare un piano con criteri oggettivi (passi, file, alternative, rischi).

Nucleo della lezione

1. Cosa rivela un piano

Un piano ben fatto rende visibili cinque cose:

• Assunzioni: cosa il modello sta dando per scontato (versione libreria, struttura DB, stack, convenzioni). Le più sbagliate emergono qui.
• Scelte architetturali: dove vivono dati, logica, UI. Quale pattern (es. “validazione sul client + server o solo server”).
• File coinvolti: lista esplicita di cosa verrà creato/modificato. Ti dice subito se lo scope è giusto.
• Alternative: il modello dovrebbe nominare almeno 2 vie possibili e perché ne preferisce una. Senza alternative, decisione opaca.
• Rischi/punti incerti: cosa il modello non sa, dove serve verifica esterna, quali edge case andranno gestiti.

Se il piano non rivela queste cose, è di facciata. Lo rifiuti, chiedi rispiegazione.

2. Cosa contiene un piano utile

Struttura minima:

1. Riassunto del task in 2 righe (parafrasi: il modello dimostra di aver capito).
2. Assunzioni elencate. Almeno 3.
3. Approccio scelto in 1 paragrafo, con motivazione.
4. Alternative considerate e perché scartate (almeno 1 alternativa).
5. Passi numerati dell’implementazione. Ognuno: cosa fa, file toccati, verifica.
6. Rischi e punti incerti.
7. Stima dimensione: righe di codice, file, dipendenze nuove.

Lunghezza: mezza pagina, non 5 pagine. Piano lungo è spesso piano vago travestito.

3. Quando accettare, modificare, rifiutare

Tre esiti possibili:

• Accetta: piano coerente, scope giusto, assunzioni corrette, rischi noti. Procedi al primo passo.
• Modifica: 1-3 cose da aggiustare (assunzione sbagliata, scope troppo largo, alternativa preferibile). Chiedi piano riveduto, non codice.
• Rifiuta: piano basato su un presupposto sbagliato (problema mal capito, vincoli ignorati). Torna indietro al brief, riformula, riavvia.

Errori frequenti:

• accettare un piano “perché sembra ragionevole” senza leggerlo davvero;
• modificare 8 cose contemporaneamente — meglio rifiutare e ripartire;
• saltare la fase di accettazione esplicita: il modello passa al codice da solo, e tu hai perso il controllo.

Comando esplicito da usare nel prompt: “non procedere al codice senza mia autorizzazione esplicita ‘OK procedi’”.

Caso guidato

Richiesta impulsiva:

Fammi una dashboard per gestire task con filtri, stati e salvataggio.

Se chiedi subito codice, il modello deve decidere troppe cose: struttura dati, stato, persistenza, UI, librerie, test, naming. Potrebbe produrre una dashboard appariscente ma fragile. Il modo corretto è costringerlo prima a esporre il piano.

Prompt di planning:

Voglio una dashboard task minima.
Vincoli: niente backend, salvataggio localStorage, niente librerie UI, mobile leggibile.
Prima del codice dammi:
1. modello dati;
2. componenti principali;
3. flusso creazione/modifica/filtro;
4. rischi e casi limite;
5. primo passo implementabile in massimo 2 file.
Non scrivere codice.

Piano accettabile:

• modello Task: id, title, status, createdAt;
• componenti: TaskForm, TaskList, TaskFilters;
• localStorage isolato in task-storage.ts;
• primo passo: solo modello + storage + test semplice.

Piano da respingere:

• introduce Supabase senza richiesta;
• aggiunge drag and drop nel primo step;
• crea 12 componenti;
• non nomina test né casi limite;
• mescola UI e persistenza nello stesso file.

La lezione pratica è questa: il piano è economico da correggere. Il codice no. Se il piano è confuso, il codice sarà una confusione più lunga.

Procedura pratica

Sequenza per ogni task non banale:

1. Prompt richiesta piano: con sezioni esplicitate (vedi prompt sotto).
2. Lettura piano (5-10 min): cerca le 7 voci richieste.
3. Decisione: accetta / modifica / rifiuta.
4. Se modifica: feedback puntuale, attesa nuovo piano.
5. Se accetta: autorizza UN passo (non tutti). “OK procedi con passo 1, ferma dopo”.
6. Verifica passo 1, autorizza passo 2. Iteri.
7. Se in qualunque momento il codice generato diverge dal piano: stop, chiedi conto.

Laboratorio guidato

Task: “aggiungi paginazione alla lista articoli del blog”.

Round A: chiedi codice direttamente. Salva output. Conta: quanti file ha modificato? quante dipendenze aggiunte? hai notato scelte non condivise?

Round B: chiedi piano prima. Quando arriva:

• conta le 7 voci. Quante presenti?
• assunzioni: ne contesti almeno una (es. “stai usando offset-based, valuta cursor-based per performance”);
• chiedi piano rivisto.
• autorizza solo passo 1.

Confronta i due esiti. Round B impiega più tempo all’inizio ma quasi sempre produce risultato più piccolo, focalizzato, corretto al primo tentativo.

Output atteso

Un protocollo personale a 2 prompt: planning prompt (per ottenere piano) + implementation prompt (per ottenere codice di un singolo passo). Salvati come template, riusabili per ogni task.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: separare progettazione ed esecuzione per correggere l’AI prima che produca molti file difficili da valutare. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Perché il piano rivela assunzioni, scelte architetturali e rischio prima del codice.
• Come chiedere un piano utile: passaggi, file coinvolti, alternative, test, punti incerti.
• Quando accettare, modificare o respingere un piano prima dell’implementazione.

3. Applicazione: svolgi il laboratorio: chiedere un piano per una feature, criticarlo con una checklist e poi autorizzare solo il primo passo. L’output da ottenere è: un flusso operativo in due prompt: planning prompt e implementation prompt.

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

• ho chiesto un piano per ogni task non banale ultimo mese;
• so distinguere piano utile da piano di facciata;
• almeno una volta ho rifiutato un piano e ripartito dal brief;
• non lascio mai che un modello passi dal piano al codice senza autorizzazione esplicita.

Errori comuni

Saltare il piano sui task “piccoli”. “È solo un’aggiunta veloce” — finisce in 5 file modificati. Anche per task piccoli, piano in 3 righe basta.

Accettare piani senza alternative. Se il modello propone una sola via, chiedi alternative. Senza alternative, decisione non motivata.

Piano fatto, codice generato in autonomia. Il modello scrive 8 file di seguito. Dopo il piano, autorizza passo per passo, non blocco.

Piano lungo come saggio. Un piano di 5 pagine è il modello che riempie. Re-chiedi con limite “max mezza pagina, lista numerata”.

Non documentare il piano accettato. Una settimana dopo, dimentichi cosa avevi deciso e perché. Salva il piano accettato (commit message, decision log, commento in PR).

Prompt di lavoro

Planning prompt:

Task: [descrizione 3 righe]
Vincoli: [da AGENTS.md o ripetuti qui]

Voglio SOLO un piano. Non scrivere codice in questa risposta.

Struttura richiesta (max mezza pagina):

1. Riassunto del task in 2 righe (parafrasa per dimostrare comprensione).
2. Assunzioni (almeno 3 esplicite su stack/versioni/dati).
3. Approccio scelto (1 paragrafo + motivazione).
4. Almeno 1 alternativa considerata e perché scartata.
5. Passi numerati con: cosa fa, file toccati, verifica.
6. Rischi / punti incerti.
7. Stima: righe di codice, file, dipendenze nuove.

Dopo aver inviato il piano, FERMATI. Aspetta che io scriva 'OK procedi con passo N' prima di scrivere codice.

Implementation prompt (dopo accettazione):

Piano accettato. Procedi con passo [N].

Vincoli operativi del passo:
- file ammessi: [come da piano]
- niente modifiche fuori passo N
- al termine: mostra diff e comando di verifica

Ferma dopo passo [N]. Non procedere al successivo senza autorizzazione.

Esercizio finale

Per la prossima settimana di lavoro con AI, applica la regola “no piano = no codice” senza eccezioni. Annota: quanti task hai chiuso più velocemente del previsto? quanti rework hai evitato? quanti piani hai dovuto rifiutare? Il numero di rifiuti è il dato più interessante: misura quante volte il modello stava per andare in direzione sbagliata e tu non te ne saresti accorto fino al codice.