Il prompt engineering è il lavoro di scrivere e riscrivere le istruzioni che dai a un modello di intelligenza artificiale finché il risultato è quello che ti serve, e finché resta quello anche alla decima esecuzione. La definizione sembra ovvia e non lo è, perché sposta il metro dal singolo risultato riuscito alla ripetibilità.
In italiano questo argomento viene quasi sempre raccontato come una collezione di frasi da incollare. Sono contenuti che invecchiano in un trimestre, perché la frase magica dipende dal modello di quel trimestre. Quello che non invecchia è il criterio con cui decidi cosa mettere dentro un'istruzione, e su quel criterio la documentazione di Anthropic è molto più precisa di qualsiasi lista di trucchi.
Il cambiamento serio degli ultimi due anni sta altrove. Il prompt ha smesso di essere una cosa che digiti una volta dentro una chat ed è diventato un file che un agente rilegge ogni giorno, su richieste che tu non hai visto. Cambiano le regole del gioco, e quasi tutti i contenuti italiani sull'argomento stanno ancora rispondendo alla domanda di due anni fa.
Le tecniche che la documentazione di Anthropic mette per iscritto
La pagina ufficiale sulle buone pratiche di prompting pubblicata da Anthropic raccoglie sotto i principi generali le tecniche che valgono su tutti i modelli Claude attuali, e per ognuna dà un dettaglio operativo invece di un principio generico. Vale la pena leggerla nell'originale, ma questa è la sostanza.
| Tecnica | Il dettaglio esatto che dà Anthropic |
|---|---|
| Essere chiari e diretti | La regola d'oro: fai leggere il prompt a un collega che non conosce il compito. Se si confonde lui, si confonde anche il modello |
| Spiegare il perché dell'istruzione | "Non usare mai i puntini di sospensione" rende meno di "il testo verrà letto da un sintetizzatore vocale, che non sa come pronunciarli" |
| Usare esempi | Da tre a cinque, chiusi in tag <example>, rilevanti e diversi tra loro |
| Strutturare con tag XML | Nomi coerenti e descrittivi come <instructions>, <context>, <input>, annidati quando il contenuto ha una gerarchia |
| Assegnare un ruolo | Una sola frase nel system prompt cambia già il comportamento |
| Contesto lungo | Sopra i ventimila token, documenti in cima e domanda in fondo |
Gli esempi pesano più delle istruzioni, ma vanno da tre a cinque
Gli esempi sono il modo più affidabile per governare formato, tono e struttura di quello che esce, e la documentazione di Anthropic è netta sulla quantità: da tre a cinque per ottenere il risultato migliore. Sotto quella soglia il modello non ha abbastanza materiale per cogliere lo schema, sopra rischia di imitare un dettaglio accidentale che si ripete.
La parte che quasi nessuno applica riguarda la diversità. Anthropic chiede esempi rilevanti, cioè vicini al caso d'uso vero, e diversi tra loro, cioè che coprano i casi limite abbastanza da non far cogliere al modello un pattern che non volevi insegnargli. Cinque esempi identici nella forma sono peggio di due esempi ben scelti.
Gli esempi vanno chiusi dentro tag <example>, e il gruppo dentro <examples>, così il modello distingue cosa è materiale di riferimento e cosa è istruzione. È lo stesso motivo per cui conviene marcare con tag anche il resto del prompt.
Nei documenti lunghi la domanda va in fondo, non in cima
Quando il prompt supera i ventimila token, Anthropic raccomanda di mettere i documenti lunghi in alto, sopra la domanda, le istruzioni e gli esempi. Il numero che accompagna la raccomandazione è il motivo per cui vale la pena ricordarsela: mettere la domanda alla fine migliora la qualità della risposta fino al trenta per cento nei test, soprattutto quando i documenti in ingresso sono più di uno.
Sui documenti multipli la documentazione indica anche la forma: ogni documento dentro un tag <document>, con <source> per la provenienza e <document_content> per il contenuto. Serve a fare in modo che il modello sappia sempre da quale documento sta prendendo una frase.
Aggiungo una cosa che uso quando i documenti sono tanti, e che sta anch'essa nella pagina di Anthropic: chiedere al modello di estrarre prima le citazioni rilevanti e solo dopo di rispondere. Costa qualche token in più e riduce parecchio le risposte inventate, per lo stesso principio del RAG.
Perché il prompt engineering cambia quando a leggerlo è un agente AI
Un prompt che esegui tu in chat e un prompt che esegue un agente da solo hanno due problemi opposti. Nel primo caso il rischio è che il modello non capisca, e lo correggi al volo con un secondo messaggio. Nel secondo caso il modello capisce benissimo e fa troppo, e non c'è nessun secondo messaggio: quello che esce va in produzione.
La documentazione di Anthropic prende questo comportamento di petto e lo chiama con il suo nome, overeagerness. Segnala che Claude Opus 4.5 e Claude Opus 4.6 tendono a sovraingegnerizzare, creando file in più, astrazioni non richieste e flessibilità che nessuno ha chiesto, e propone un prompt di esempio che delimita quattro cose: portata dell'intervento, documentazione, codice difensivo e astrazioni.
Sulla stessa logica c'è il blocco contro le allucinazioni nel coding agentico, che si riassume in una frase da copiare così com'è: mai speculare su codice che non hai aperto. Chi fa girare Claude Code in automatico sa che è esattamente lì che si perde una giornata di lavoro.
L'errore che ho fatto sul prompt di questo blog
Il prompt della routine che pubblica gli articoli di questo sito sta in automazione-blog/cloud-agent/prompt-articolo-notizie.md ed è lungo 5.261 parole, mentre le regole di scrittura vere e proprie stanno in .claude/skills/articolo/ e sono altre 7.794 parole divise in cinque file. È un prompt che nessuno rilegge prima che l'articolo vada online, quindi ogni riga sbagliata lì dentro diventa un errore pubblicato.
L'errore più istruttivo è stato scrivere un numero. Il prompt diceva di eseguire sette controlli finali, e intanto lo skill era arrivato a otto: il risultato è che l'ottavo controllo, che era proprio quello sulla keyword, non è mai stato eseguito per ventiquattro articoli. Il numero era giusto il giorno in cui l'ho scritto ed è diventato falso senza che nessuno lo toccasse.
L'altro errore l'ho trovato misurando. Nelle linee guida avevo vietato una lista di formule di apertura, e la misura riportata dentro .claude/skills/articolo/seo-geo.md dice che quelle formule comparivano una volta sola in tutto il campione, mentre un paragrafo su otto si apriva comunque male, per enumerazione. Il divieto scritto come lista di frasi non intercettava il problema vero, e per intercettarlo ho dovuto riscriverlo come criterio: nessun paragrafo comincia con un ordinale se il soggetto non è ripetuto per esteso.
Da dove partire se scrivi prompt che verranno riusati
La documentazione di Anthropic mette tre prerequisiti prima ancora di cominciare, e sono il punto di partenza migliore: un criterio di successo definito, un modo per verificarlo empiricamente e una prima bozza di prompt da migliorare. Senza il secondo dei tre stai solo giudicando a occhio.
In pratica, nell'ordine in cui conviene farle:
- Scrivi cosa deve succedere perché il risultato sia buono, in una riga misurabile. "Nessuna sezione supera le 220 parole" è un criterio, "l'articolo dev'essere scorrevole" non lo è.
- Sostituisci ogni numero copiato a mano con un rimando al posto dove quel numero vive davvero. È l'errore delle sette righe di prima, e si evita solo così.
- Aggiungi da tre a cinque esempi diversi tra loro, dentro i tag, prima di aggiungere altre istruzioni.
- Riscrivi ogni divieto come criterio applicabile. Un divieto elenca frasi, un criterio descrive la forma sbagliata e regge anche sulle frasi che non ti erano venute in mente.
- Quando il prompt cresce, spostane dei pezzi fuori: trasformare un documento in una skill costa meno contesto che tenere tutto dentro un unico file, e vale anche per ridurre i token di un agente di coding.
Quando riscrivere il prompt non è la risposta
Quando il prompt smette di essere un testo e diventa l'insieme delle cose che il modello ha davanti mentre lavora, il nome cambia e diventa context engineering, che è il mestiere di chi costruisce agenti veri. Il prompt engineering resta il primo pezzo, quello che decide se il resto ha senso.
Una cosa vale la pena dirla, ed è scritta nella pagina di Anthropic prima di ogni tecnica: non tutti i problemi si risolvono riscrivendo il prompt. Latenza e costo, per esempio, si sistemano più facilmente cambiando modello. Se in azienda il problema è che nessuno sa scrivere istruzioni riusabili, però, quella è formazione e si risolve con la formazione AI in azienda, non con l'ennesima lista di frasi da incollare.
Fonti primarie: la panoramica sul prompt engineering e la pagina sulle buone pratiche di prompting pubblicate da Anthropic.
Domande frequenti
Serve un corso per imparare il prompt engineering?
Un corso serve a saltare la fase in cui provi frasi a caso, non a imparare formule segrete. Anthropic pubblica gratuitamente un tutorial interattivo su GitHub e una versione più leggera come foglio di calcolo, ed è materiale sufficiente per arrivare a scrivere prompt decenti. Il salto vero arriva dopo, quando cominci a misurare i risultati invece di giudicarli a occhio.
Chi è il prompt engineer e conviene assumerne uno?
Il prompt engineer è la figura che scrive e mantiene le istruzioni con cui un'azienda fa lavorare i modelli di intelligenza artificiale. Come ruolo separato in una PMI ha poco senso, perché scrivere una buona istruzione richiede di conoscere il processo da automatizzare più che il modello. Conviene formare chi quel processo lo esegue già, invece di cercare una figura esterna che deve impararlo da zero.
Il prompt engineering funziona allo stesso modo su ChatGPT e su Claude?
I principi generali valgono ovunque: istruzioni esplicite, esempi, struttura chiara, formato di uscita dichiarato. I dettagli no. Anthropic pubblica pagine di indicazioni diverse per Claude Fable 5, Claude Sonnet 5, Claude Opus 5 e Claude Opus 4.8, e i tag XML sono una convenzione che Claude gestisce particolarmente bene. Un prompt portato da un modello all'altro va riprovato, non dato per buono.
Conviene farsi scrivere il prompt da un modello?
Per la prima bozza sì, ed è Anthropic stessa a suggerirlo: la pagina di panoramica rimanda a un notebook che genera un prompt di partenza con la ricetta del metaprompt del Claude Cookbook. Funziona bene anche chiedere al modello di valutare gli esempi che hai già scritto, per capire se sono abbastanza rilevanti e abbastanza diversi tra loro. La bozza generata resta però una bozza: i criteri di successo li devi mettere tu.
Un prompt che funziona oggi funzionerà anche con il prossimo modello?
Non è detto, ed è il motivo per cui la pagina sulle buone pratiche di Anthropic si chiude con una sezione dedicata alla migrazione dei prompt scritti per le generazioni precedenti. Un prompt tarato su un modello va riprovato quando cambi modello, con gli stessi criteri di verifica che avevi usato la prima volta. Chi usa l'AI in produzione questo passaggio se lo mette in calendario, non lo scopre dai risultati.