Anatomia di un prompt utile: ruolo, contesto, obiettivo, vincoli, formato, verifiche

Un prompt non è una frase: è un documento operativo a struttura. Sei sezioni minime — ruolo, contesto, obiettivo, vincoli, formato, verifiche — coprono l’85% delle ambiguità che fanno fallire le richieste. Il prompt elegante non basta: serve completo.

Perché questa lezione conta

I prompt brevi (“scrivi un’app per X”) ottengono output generici. I prompt che improvvisano in 200 righe disordinate confondono il modello tanto quanto te. La struttura a sei sezioni è un compromesso pragmatico: copre ciò che serve, niente di superfluo, e produce output prevedibili. Modulare: la stessa struttura si adatta a feature, bugfix, refactor, review.

Obiettivo operativo

Alla fine devi saper:

1. nominare le sei sezioni e cosa contiene ciascuna;
2. comporre prompt completi per task diversi (creazione, modifica, analisi, review);
3. riconoscere quale sezione manca quando un output va male.

Nucleo della lezione

1. Le sei sezioni

Ruolo: lente operativa del modello, non costume. Indica quali competenze e priorità deve attivare.

❌ “Sei un guru senior 10x developer ninja” ✅ “Stai lavorando come sviluppatore esperto in TypeScript e accessibilità web. Priorità: codice leggibile, accessibile WCAG AA, niente dipendenze non necessarie.”

Il ruolo funziona quando elenca competenze e priorità concrete, non aggettivi.

Contesto: cosa esiste già, dove ti trovi nel progetto, cosa il modello deve sapere per non inventare.

• stack: linguaggi, framework, versioni;
• file rilevanti (citati per nome, eventualmente incollati);
• convenzioni del progetto (naming, struttura cartelle, stile);
• stato attuale: cosa è già fatto, cosa è in corso.

Il contesto è dove un modello con accesso al filesystem (IDE AI, agente CLI) può cercare in autonomia. In chat, lo passi tu.

Obiettivo: cosa deve produrre questo specifico prompt. Una cosa, non cinque. Verbo-oggetto-criterio.

❌ “Aiutami a sistemare l’autenticazione” ✅ “Aggiungi al modulo src/auth.ts una funzione verifyEmail(token: string): Promise<User | null> che valida un token magic-link, verifica scadenza, restituisce l’utente o null.”

Vincoli: cosa NON deve fare e cosa deve rispettare.

• file ammessi/vietati;
• librerie permesse o no;
• pattern da mantenere (es. “usare Result<T,E> come in altri moduli”);
• divieti espliciti (no nuove dipendenze, no refactor laterale, no console.log, no commit automatici);
• vincoli non funzionali (sicurezza, performance, accessibilità).

Formato: come deve presentare la risposta. Riduce ambiguità a costo zero.

• struttura sezioni (piano, codice, test, rischi);
• linguaggio (italiano? inglese? neutro?);
• limite lunghezza (“piano max 5 punti”);
• presenza di blocchi codice vs prosa;
• richiesta esplicita di “diff” o “file completo”.

Verifiche: come si valuta l’output. Criteri di accettazione + comandi di test.

• “Test: npm test src/auth.test.ts deve passare”;
• “Manuale: invio token scaduto → ricevo null”;
• “Lint: nessun warning aggiunto”;
• “Diff: meno di 100 righe modificate, solo file src/auth.ts e src/auth.test.ts”.

2. Tre tipi di prompt

La struttura a sei sezioni si adatta a tre situazioni principali:

Esplorativo: vuoi opzioni, alternative, idee. Obiettivo: ricevere 3 approcci con trade-off, non codice. Formato: lista ordinata. Verifiche: criteri per scegliere fra alternative.

Implementativo: vuoi codice. Obiettivo: feature/fix specifico. Formato: piano + codice + test. Verifiche: comando di test, criteri funzionali.

Di revisione: vuoi feedback su codice esistente. Ruolo: revisore con priorità chiare. Obiettivo: critica strutturata. Formato: lista con severità (blocking / consigliato / nit). Verifiche: criteri di accettazione del PR.

Stesso schema, sezioni piene di contenuto diverso.

3. Errori che rivelano una sezione mancante

Sintomi → diagnosi:

• Modello sceglie librerie sbagliate → contesto debole (versioni, stack non specificati).
• Output troppo lungo o fuori tema → obiettivo vago.
• Refactor laterale non richiesto → vincoli mancanti (“non rifattorizzare X”).
• Soluzione plausibile ma non testata → verifiche assenti.
• Tono fuori contesto (formale dove serve diretto) → formato non specificato.
• Risposta troppo generica/standard → ruolo assente o troppo astratto.

Quando un output va male, prima di cambiare modello: identifica quale sezione del prompt era debole.

Procedura pratica

Workflow per scrivere un prompt completo:

1. Tipo: esplorativo, implementativo, di revisione?
2. Riempi le sei sezioni: una alla volta, breve. Se sei sezioni superano 1 pagina, sei già lungo.
3. Verifica completezza: ogni sezione ha contenuto reale? Niente “TODO” o vuoto.
4. Verifica coerenza: ruolo + obiettivo + formato + verifiche dicono la stessa cosa?
5. Invia, leggi output, segna quale sezione era debole se l’output non torna.

Tempo medio: 5-10 minuti. Salva ore di iterazione.

Laboratorio guidato

Stesso obiettivo (“aggiungere validazione email a un form esistente”), tre prompt diversi:

Versione A — esplorativa:

• Ruolo: revisore esperto in form UX e accessibilità.
• Contesto: form React con react-hook-form, target WCAG AA, utenti italiani.
• Obiettivo: proporre 3 approcci di validazione email (client, server, ibrido) con trade-off.
• Vincoli: niente librerie esterne nuove se non strettamente necessarie.
• Formato: lista ordinata, ogni approccio con: descrizione, pro, contro, casi limite.
• Verifiche: criteri per scegliere = sicurezza, UX, performance, manutenibilità.

Versione B — implementativa:

• Ruolo: sviluppatore TypeScript, focus su accessibilità.
• Contesto: file src/components/ContactForm.tsx, react-hook-form, no zod ancora installato.
• Obiettivo: aggiungere validazione email che mostri errore inline, accessibile.
• Vincoli: solo ContactForm.tsx, niente nuove dipendenze, mantenere pattern esistenti.
• Formato: piano in 3 passi + diff finale + test.
• Verifiche: npm test ContactForm passa, manuale: campo email vuoto/invalido/valido, screen reader annuncia errore.

Versione C — di revisione:

• Ruolo: code reviewer pignolo su accessibilità e sicurezza.
• Contesto: PR diff allegato, validazione email aggiunta.
• Obiettivo: revisione in 4 categorie (correttezza, sicurezza, accessibilità, leggibilità).
• Vincoli: solo segnalazioni, no riscritture proposte.
• Formato: lista per categoria, severità blocking/suggerito/nit.
• Verifiche: ogni segnalazione ha riferimento file:riga.

Manda i tre prompt a un modello, confronta output. Stesso obiettivo iniziale, output drasticamente diversi e ognuno utile in fase diversa.

Output atteso

Un template prompt modulare, riusabile come scheletro. Sei sezioni con segnaposto compilabili. Salvalo come file (templates/prompt.md o snippet IDE) e parti da lì ogni volta.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: costruire prompt che riducono ambiguità e costringono l’AI a produrre output verificabili. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Il ruolo come lente operativa, non come travestimento: cosa deve privilegiare il modello.
• Contesto e obiettivo: cosa esiste già, cosa deve cambiare, cosa non deve essere toccato.
• Formato e verifiche: come deve presentare piano, codice, test, rischi e passaggi successivi.

3. Applicazione: svolgi il laboratorio: riscrivere un prompt generico in tre versioni: esplorativa, implementativa e di revisione. L’output da ottenere è: un template prompt modulare da adattare a feature, bugfix, refactor e review.

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 sezioni senza guardare;
• ho un template salvato e accessibile rapidamente;
• almeno una volta ho identificato a posteriori quale sezione mancava in un prompt fallito;
• distinguo prompt esplorativi/implementativi/di revisione e adatto le sezioni di conseguenza.

Errori comuni

Niente ruolo o ruolo cosmetico. “Sei il miglior dev del mondo” è inutile. Senza ruolo concreto il modello attiva default generici.

Contesto troppo o troppo poco. Troppo: incollare repo intera. Troppo poco: il modello inventa stack. Calibrare: il minimo per non inventare.

Più obiettivi. “Aggiungi feature X, fixami il bug Y, rifattorizza Z”. Tre prompt, non uno.

Niente vincoli. Il modello fa tutto ciò che gli pare ragionevole. Spesso più di quanto vuoi.

Formato non specificato. Output formato sbagliato (prosa invece di codice, codice senza piano) non è colpa del modello: è prompt incompleto.

Verifiche assenti. Senza criteri non sai quando accettare. Risultato: dipende dall’umore.

Prompt di lavoro

[RUOLO]
[Competenze attivate, priorità: 2-3 frasi concrete, no aggettivi]

[CONTESTO]
- Stack: [linguaggio + framework + versioni]
- File rilevanti: [lista]
- Convenzioni: [link a AGENTS.md o riassunto]
- Stato attuale: [cosa è fatto, cosa stiamo facendo]

[OBIETTIVO]
[Una sola cosa. Verbo + oggetto + criterio osservabile.]

[VINCOLI]
- File ammessi: [...]
- File vietati: [...]
- Librerie/dipendenze: [permesse / vietate / da approvare]
- Pattern da mantenere: [...]
- Divieti espliciti: [no refactor laterale / no nuove API endpoint / no console.log]
- Non funzionali: [sicurezza, performance, accessibilità minimi]

[FORMATO]
- Lingua: [italiano / inglese]
- Struttura: [piano + codice + test / lista alternative / diff con commenti]
- Lunghezza: [piano max N punti, codice mirato, no spiegazioni lunghe]

[VERIFICHE]
- Test: [comando]
- Manuale: [scenario]
- Lint/type: [nessun nuovo warning]
- Criteri di accettazione: [funzionali + non funzionali]

Procedura richiesta:
1. Conferma di aver capito (parafrasa obiettivo + vincoli).
2. Lista assunzioni.
3. Piano in N punti.
4. Aspetta autorizzazione prima di scrivere codice.

Esercizio finale

Riscrivi tre dei tuoi prompt più recenti seguendo lo schema. Confronta con gli originali: quante sezioni avevi davvero compilato? In quale sezione tendi a saltare? Quasi sempre verifiche o vincoli — le sezioni che richiedono più disciplina e meno fantasia. Quella consapevolezza è il punto: le sezioni “noiose” sono quelle che salvano il task.