Scrivere prompt che funzionano ✍️

Il prompt per un agente di coding non è una formula magica da recitare. È il modo in cui strutturi una richiesta perché il modello abbia le informazioni necessarie senza doverle indovinare. La differenza tra un prompt mediocre e uno efficace non è la quantità di parole: è la quantità di informazioni utili per unità di parola.

Un buon prompt non chiede all’agente di essere intelligente: gli dà ciò che gli serve per non dover esserlo.

I quattro elementi 🧩

Un prompt ottimizzato per un task di implementazione definisce esplicitamente quattro elementi:

Il modello ha una sola domanda in testa quando legge il tuo prompt: “cosa mi sta chiedendo esattamente, e come farò a sapere che ho finito?”. I quattro elementi sono la risposta.

Buono e cattivo esempio ⚖️

Il modo più rapido per capire è vedere la differenza. Il prompt vago:

“Aggiungi la gestione della sessione utente al backend e assicurati che sia sicura.”

Il risultato sarà un codice plausibile, generico e quasi certamente non allineato con le tue convenzioni. Ecco la versione direttiva:

1
2
3
4
5
6

OBIETTIVO: Implementare la gestione delle sessioni utente in src/auth/session.ts.
VINCOLI: JWT firmati con chiavi asimmetriche RS256. NON modificare l'interfaccia
UserStore esistente in src/types/user.ts.
FILE TARGET: Creare src/auth/session.ts e aggiornare src/auth/index.ts.
CRITERI: Generare test unitari in tests/auth/session.test.ts per i token scaduti.
Verificare che pnpm test restituisca esito positivo.

Non è più lungo, è più denso. Ogni riga elimina una decisione che altrimenti l’agente avrebbe preso da solo — e presa male.

Il pattern 3S 📌

Una scorciatoia mnemonica per non dimenticare pezzi:

• Situazione — il contesto minimo indispensabile: progetto, stack, vincolo di business.
• Specifica — cosa deve fare esattamente il codice, incluse le condizioni di errore e gli edge case.
• Standard — stile, pattern architetturali, convenzioni di test. Idealmente questi stanno già nelle istruzioni del repository e non vanno ripetuti a ogni richiesta.

Il bello delle 3S è che costringe a distinguere ciò che è specifico del task (va nel prompt) da ciò che è costante del progetto (va nel repository). Ripetere nel prompt quello che è già in AGENTS.md non aiuta: consuma token e confonde le priorità.

Scomporre i task 🔪

Un compito grande non va affidato a un prompt grande. Si scompone in una sequenza di richieste piccole, ognuna con il proprio ciclo di validazione:

1. prima la struttura (“proponi la struttura dei moduli e le interfacce”);
2. poi l’implementazione modulo per modulo;
3. poi i test;
4. infine la verifica completa.

Chiedere tutto in un colpo solo (“implementa il modulo di pagamento completo”) produce codice lungo, non verificabile e costoso da correggere. Chiederlo a passi produce un risultato che puoi controllare a ogni incrocio.

Controllare il volume dell’output 🎛️

L’output costa più dell’input: ogni parola inutile è spreco. Per i task di sola scrittura, il prompt può chiudere con “solo codice, senza spiegazioni”. Per le domande, “rispondi in elenco puntato”. Per i task esplorativi, “cita i file con percorso e riga per ogni affermazione”.

Questi piccoli vincoli non sono capricci stilistici: riducono il volume di output, accorciano le sessioni e costringono l’agente a essere preciso invece che eloquente.

Iterare invece di riscrivere 🔁

Il primo output raramente è quello giusto, e va benissimo. L’errore è ripartire da zero con un prompt nuovo ogni volta. La tecnica corretta è l’iterazione con scope narrowing:

• se una parte del risultato è sbagliata, circoscrivi la correzione a quella parte (“il caso di errore in session.ts non gestisce il token scaduto; correggi solo quello”);
• se il risultato è sulla strada giusta ma con la stile sbagliato, indica lo standard e ripeti l’operazione;
• se il secondo tentativo fallisce ancora sullo stesso punto, integra l’esito negativo come vincolo esplicito (“il tentativo precedente è fallito perché X; evita X”).

Iterare sull’errore è più rapido e più economico che ricominciare, e produce prompt progressivamente più precisi.

Prompt riutilizzabili e libreria di squadra 🗃️

Per i compiti ricorrenti — generazione di test, code review con checklist, scaffolding di un modulo — il prompt va standardizzato e versionato, non riscritto a mano ogni volta:

• salva i prompt in .prompt.md (o nella convenzione del tuo strumento, come le cartelle per i comandi slash);
• richiamali con un nome, non con un copia-incolla;
• la libreria cresce di valore: ogni revisione in PR è un prompt migliore per tutti;
• prima di reinventare, controlla la community: adattare un prompt esistente è quasi sempre più rapido che partire da zero.

Una libreria di prompt condivisa ha lo stesso effetto di un AGENTS.md curato: il team lavora con le stesse regole anche quando non le ha in testa.

Quando NON usare questa ricetta ⛔

• Il contesto conta più del prompt: un prompt perfetto con un contesto vuoto produce codice generico. Prima la qualità del contesto, poi la formulazione.
• Non è una formula infallibile: se l’agente continua a sbagliare su una parte della codebase, il problema potrebbe essere la leggibilità del codice, non il prompt.
• Non sostituire la validazione: il prompt definisce i criteri, non li verifica. La prova resta build, test e lint.

Checklist finale ✅

• Ho definito obiettivo, vincoli, file target e criteri di accettazione?
• Ho incluso solo il contesto rilevante, senza incollare file interi?
• Lo standard (stack, stile) sta nel repository e non nel prompt?
• Ho scomposto il task grande in passi con validazione intermedia?
• Ho controllato il volume dell’output (“solo codice”)?
• Se qualcosa è andato storto, ho iterato con scope narrowing invece di riscrivere?
• Il prompt che ha funzionato è salvato nella libreria di squadra?

Approfondimenti 📚

• Il ciclo di lavoro: pianifica, esegui, valida — dove finiscono i prompt ben scritti.
• Prompt engineering — il punto di vista complementare: il prompting per LLM generici.
• Blog: Communicate with AI.