«Stava nel prompt» non è una risposta a «perché ha fatto così?»
La conversazione si ripete in tutte le aziende che portano un agente in produzione. L'agente fa qualcosa di strano — promette una consegna che non esiste, risponde a una cosa che non gli spettava, si inventa una procedura — e qualcuno chiede cos'è successo. La risposta è sempre la stessa: «stava nel prompt». E allora arrivano le tre domande scomode. In quale versione del prompt? Chi ha scritto quella riga? Qualcuno ha provato cosa succede a toglierla?
Quasi mai c'è una risposta, e non è trascuratezza: è che la parola prompt spinge a trattare il testo come un messaggio. Un messaggio si scrive una volta, si manda e si dimentica. Ma quello che governa un agente in produzione non è un messaggio: è il documento che definisce cosa fa, cosa non tocca e chi chiama quando si blocca. In qualsiasi organizzazione questo ha un altro nome: una descrizione di ruolo. E le descrizioni di ruolo hanno un proprietario, una versione e una data di revisione.
Non è una metafora comoda. La documentazione di Anthropic consiglia di pensare al modello come a «un dipendente brillante ma nuovo, che non conosce le tue regole né i tuoi flussi di lavoro», e propone una regola d'oro che funziona altrettanto bene con le persone: mostra le tue istruzioni a un collega con poco contesto e chiedigli di seguirle; se si confonde lui, si confonde anche il modello. Fonte: Prompting best practices, Claude Platform Docs, consultato l'11 settembre 2026.
Questa guida parla di scrivere quel documento. Non è un corso di prompting né un modello magico da copiare: è la struttura minima che regge in produzione, il punto in cui quasi tutti sbagliano e l'abitudine che separa iterare dal pregare.
Le sei cose che devono essere scritte
Piattaforma, modello e caso d'uso non cambiano niente. Se manca uno di questi sei blocchi, l'agente lo riempie da solo, e quello che ci mette non l'hai deciso tu. Nell'architettura descritta da OpenAI un agente è fatto di tre pezzi — modello, strumenti e istruzioni — e le istruzioni sono le «linee guida e i guardrail espliciti che definiscono il suo comportamento». Espliciti è la parola. Fonte: A practical guide to building agents, OpenAI, consultato l'11 settembre 2026.
| Blocco | A cosa risponde | Cosa succede se manca |
|---|---|---|
| Identità e canale | Chi è, con chi parla e da dove | Tono e registro cambiano di giorno in giorno |
| Perimetro | Di cosa si occupa e di cosa no | Risponde a tutto, anche a quello che non sa |
| Cosa può decidere | Dove finisce proporre e comincia eseguire | Esegue cose che nessuno ha autorizzato |
| Formato di uscita | Con che forma consegna il risultato | Il sistema di destinazione lo rifiuta in silenzio |
| Cosa fa quando non sa | L'uscita onesta di default | Riempie il buco con qualcosa di verosimile |
| Quando scala | La soglia esatta che chiama una persona | Nessuno lo scopre fino al reclamo |
Guarda la colonna di destra: nessuno di questi guasti si manifesta come un errore. Tutti si manifestano come comportamento, che è molto più caro da individuare. Un agente che va giù te lo dice; un agente a cui manca il blocco del perimetro lavora tranquillo per settimane rispondendo a cose che non erano affar suo.
L'errore delle regole al negativo (e cosa metterci al posto)
Ecco la correzione più utile di tutta la guida, e va contro quello che fanno quasi tutti. Quando un agente si comporta male, il riflesso è aggiungere un divieto: «non promettere mai tempi di consegna», «niente emoji», «non dare mai prezzi». La lista dei no cresce settimana dopo settimana fino a diventare un regolamento, e il comportamento continua a comparire.
La documentazione di Anthropic è esplicita su questo: di' al modello cosa deve fare, invece di cosa non deve fare. Il loro esempio per controllare il formato è proprio questo: invece di «non usare markdown nella risposta», scrivi «la tua risposta deve essere composta da paragrafi di prosa scorrevole». E quando il divieto è inevitabile, la stessa guida consiglia di accompagnarlo con il motivo: «non usare MAI i puntini di sospensione» rende meno di «la tua risposta sarà letta ad alta voce da un motore di sintesi vocale, quindi non usare mai i puntini, perché non saprà pronunciarli». Il modello generalizza a partire dalla spiegazione; dal divieto secco, no. Fonte: Prompting best practices, Claude Platform Docs, consultato l'11 settembre 2026.
La traduzione operativa è semplice e costa lavoro: ogni volta che stai per scrivere un «non», fermati e rispondi a due domande. Cosa voglio che faccia al suo posto? e perché? Quello che esce da lì è la regola da scrivere.
| Quello che si scrive | Quello che funziona |
|---|---|
| «Non promettere mai tempi di consegna» | «Quando ti chiedono una data, dai quella che restituisce il sistema ordini. Se non ne restituisce nessuna, di' che la confermerai e apri una richiesta, perché una data sbagliata diventa un reclamo.» |
| «Non inventare informazioni» | «Rispondi solo con quello che trovi nella documentazione. Se non c'è, dillo con queste parole e proponi di passare la domanda a una persona.» |
| «Non dare sconti» | «Gli sconti li approva il responsabile commerciale. Se un cliente ne chiede uno, registra la richiesta con l'importo e avvisa il commerciale; non confermare niente tu.» |
C'è un'eccezione da conoscere: i vincoli di sicurezza duri — quello che non deve mai succedere, in nessuna circostanza — si scrivono sì al negativo e in modo netto, e conviene ripeterli all'inizio e alla fine del documento. Ma sono due o tre righe, non quaranta. Il resto del tuo regolamento di no è, quasi sempre, una specifica positiva che nessuno si è fermato a scrivere.
Cosa decide, cosa propone e cosa non tocca
Il blocco che fa risparmiare di più è il più corto. Prendi ogni azione che l'agente può eseguire e mettila in tre colonne: la esegue da solo, la lascia proposta perché qualcuno confermi, oppure non la tocca. E scrivilo con soglie numeriche, non con aggettivi: «importi alti» non è una soglia, «sopra i 300 euro» sì.
Per decidere in che colonna va ogni azione, la guida di OpenAI propone di dare un punteggio di rischio a ogni strumento — basso, medio o alto — su quattro fattori: sola lettura o scrittura, reversibilità, permessi richiesti e impatto economico. È quel punteggio a far scattare la pausa o l'escalation, ed è un criterio molto più difendibile dell'intuizione della riunione di martedì. Fonte: A practical guide to building agents, OpenAI, consultato l'11 settembre 2026.
Questo blocco delle istruzioni e i permessi tecnici dell'agente sono due cose diverse che devono dire la stessa cosa. Le istruzioni dicono cosa deve fare; i permessi determinano cosa può fare. Se il documento dice che non emette rimborsi ma la credenziale ha l'ambito per emetterli, l'unica cosa che separa la tua azienda da un rimborso indebito è la buona condotta del modello, che non è un controllo. Come si chiude questa tenaglia sta in quali permessi dare a un agente di IA, e la mappa di quanta autonomia concedere e in che ordine, in livelli di autonomia di un agente.
Cosa fa quando non sa, e quando chiama una persona
Senza un'istruzione esplicita, il comportamento di default davanti a un vuoto è riempirlo con qualcosa di plausibile. Non perché il modello menta, ma perché nessuno gli ha dato un'uscita migliore. L'uscita migliore si scrive in una riga e cambia la giornata: «se la risposta non è nella documentazione, dillo con queste parole, non dedurla, e proponi di passare la domanda a una persona».
L'escalation è l'altra metà. OpenAI la tratta come un meccanismo di sicurezza di prima classe e descrive due inneschi da copiare così come sono: superare una soglia di fallimenti — se l'agente non ha capito l'intento dopo N tentativi, trasferisce — e le azioni ad alto rischio, cioè quelle sensibili, irreversibili o di forte impatto; gli esempi che porta sono annullare ordini, autorizzare rimborsi importanti ed effettuare pagamenti. Fonte: A practical guide to building agents, OpenAI, consultato l'11 settembre 2026.
Scrivi quei due inneschi con numeri e con destinatario. Non «scala quando serve», ma «dopo due tentativi senza identificare l'ordine, passa la conversazione al servizio clienti con il riassunto e lo storico». La differenza tra le due formulazioni è la differenza tra un'escalation che avviene e una che non avviene.
Una cosa per volta: l'abitudine che separa iterare dal pregare
Quasi tutti regolano le istruzioni allo stesso modo: notano un comportamento strano, riscrivono quattro paragrafi, provano due casi a occhio e pubblicano. Se migliora, non sanno quale dei quattro cambiamenti l'ha risolto. Se peggiora, non sanno nemmeno quale l'ha rotto. Questo non è iterare, è pregare con passaggi intermedi.
L'abitudine che lo trasforma in ingegneria sta in tre regole. Una. Cambia una cosa per volta e lasciala scritta: cosa hai cambiato, perché e cosa ti aspettavi. Due. Conserva il prima e il dopo degli stessi casi — i dieci o quindici che rappresentano la tua operatività reale, compresi quelli strani — perché senza il prima non hai con cosa confrontare. Tre. Lascia la versione precedente dove puoi recuperarla in un minuto, perché il cambiamento che rompe qualcosa quasi mai la rompe nella prova: la rompe il martedì dopo.
Queste tre regole sono manuali e funzionano in un foglio di calcolo, che è dove devono cominciare. Quando l'agente smette di essere uno e diventa una flotta, il registro a mano non regge più e questo diventa una funzione operativa con fonte unica di verità, batteria di test prima del rilascio e ritorno indietro in un minuto: è testare e versionare i prompt di IA, ed è un servizio, non un consiglio. A decidere il salto non è la dimensione del team, è il numero di persone che possono toccare il documento.
E un avvertimento che fa risparmiare settimane: se l'agente fallisce perché non trova l'informazione, il problema non è nelle istruzioni e riscriverle non lo risolverà. È in quello che può consultare — come si monta e si valuta sta in addestrare un agente di IA — oppure in quello che dovrebbe ricordare tra una conversazione e l'altra, che è la memoria di un agente di IA. I tre si risolvono in modi diversi, e confonderli è il modo più comune di perdere un mese.
La scheda di una pagina: chi la firma e quando è stata rivista
Chiudi il documento con un'intestazione di cinque campi. Non è burocrazia: è quello che trasforma un testo sciolto in un artefatto che qualcuno mantiene.
- Proprietario. Una persona con nome e cognome, non un reparto. Chi risponde quando l'agente fa qualcosa di strano.
- Versione e data. Un numero che sale e il giorno in cui è salito. Senza questo non puoi dire cosa girava la settimana scorsa.
- Cosa è cambiato e perché. Due righe per versione. È il registro che ti evita di ripetere un esperimento fallito fra sei mesi.
- Casi di prova. Dove vivono i dieci o quindici casi con cui si verifica ogni cambiamento, e chi li tiene aggiornati.
- Prossima revisione. Una data. Le istruzioni scadono quando cambiano la policy, il catalogo o il sistema di destinazione, e nessuno avvisa.
Se il tuo agente è già in produzione e questo documento non esiste, l'ordine è questo: scrivi prima il blocco di cosa può decidere e quello di quando scala, i due che hanno soldi davanti. Il resto può aspettare una settimana. E il giorno in cui qualcuno tornerà a chiedere «perché ha fatto così?», potrai aprire un file, guardare una versione e rispondere.
Noi scriviamo quel documento con il cliente davanti e lo lasciamo firmato, versionato e con i suoi casi di prova: fa parte del montare dipendenti IA che lavorano davvero, dentro la logica generale di creare un agente di IA che regga la produzione. Non vendiamo il prompt. Ci facciamo pagare perché chiunque nel tuo team possa leggere cosa fa il tuo agente e perché, senza chiedere a nessuno.