Versionare i prompt sembra un dettaglio da addetti ai lavori, finché un venerdì pomeriggio qualcuno aggiunge due righe alle istruzioni dell'agente che risponde ai clienti e il lunedì mattina le risposte hanno un tono diverso. Nessuno ricorda com'era il testo prima. Nessuno sa chi l'ha toccato, né perché. In quel momento si scopre una cosa scomoda: il testo che pilota l'automazione non stava in nessun posto davvero affidabile.
È un problema organizzativo prima che tecnico. Il prompt — le istruzioni in linguaggio naturale che definiscono il comportamento di un modello — è l'unico pezzo di un'automazione AI che tutti si sentono autorizzati a modificare, perché «è solo testo». Ed è proprio per questo che merita la stessa disciplina che si riserva al codice: una storia, un autore, un motivo e un modo per tornare indietro.
Perché versionare i prompt non è pignoleria
La prima ragione è misurabile. In un lavoro presentato a ICLR 2024, Melanie Sclar, Yejin Choi, Yulia Tsvetkov e Alane Suhr hanno quantificato quanto pesano le scelte di formattazione in un prompt: separatori, spaziature, maiuscole. Su LLaMA-2-13B hanno osservato differenze fino a 76 punti di accuratezza tra formati equivalenti dello stesso compito, cioè tra testi che un essere umano leggerebbe come identici. Il fenomeno non si risolve usando un modello più grande, aggiungendo esempi o passando a un modello istruito: la loro raccomandazione è riportare un intervallo di prestazioni su più formati plausibili invece di un singolo numero.
Se una virgola spostata può muovere il risultato, allora una modifica non tracciata è una variabile fuori controllo dentro un processo aziendale. Quando il mese dopo le pratiche evase male aumentano, senza la storia delle modifiche non si può nemmeno formulare l'ipotesi giusta: il modello è cambiato? i dati in ingresso? o quella riga aggiunta a fine settembre?
La seconda ragione è economica. In molte automazioni il prompt è la parte stabile che viene riutilizzata a ogni chiamata e quindi messa in cache: cambiarne una riga invalida il prefisso e riporta il costo di quelle richieste al valore pieno, come abbiamo visto parlando di prompt caching e costo di un'automazione. Una modifica innocua può alzare la bolletta senza che nessuno colleghi le due cose.
Il prompt è codice o è configurazione?
Vale la pena fermarsi su questa domanda, perché la risposta decide dove va il file. La metodologia Twelve-Factor App definisce la configurazione come «tutto ciò che è probabile vari tra un ambiente e l'altro» — credenziali, indirizzi di servizi, parametri di collegamento — e propone un test semplice: il codice dovrebbe poter diventare pubblico in qualsiasi momento senza esporre alcuna credenziale.
Un prompt non supera questo test al contrario: non varia tra collaudo e produzione, perché se variasse staremmo collaudando un'altra cosa. Varia quando cambia il comportamento del prodotto. Non è configurazione: è logica applicativa scritta in italiano. Le chiavi API restano fuori dal repository, con le scadenze e i referenti annotati nell'inventario delle dipendenze; le istruzioni del modello, invece, vanno dentro, accanto al codice che le usa.
Il registro delle modifiche vale più dello strumento che lo ospita: conta che ogni cambiamento abbia una data, un autore e un motivo.
Dove vive un prompt versionato: registro del fornitore o repository
Esistono due scuole, e nell'ultimo anno il mercato ha dato un'indicazione chiara. Da un lato i registri gestiti: su Vertex AI, Google permette di salvare un prompt come risorsa con versioni immutabili, elencarle e ripristinare una versione precedente; il ripristino, significativamente, genera una nuova versione invece di riscrivere la storia. È comodo per sperimentare e per far lavorare chi non apre un editor di codice.
Dall'altro lato c'è la strada del repository, e qui il segnale è forte. OpenAI aveva introdotto i «prompt riutilizzabili» lato piattaforma e ora li sta dismettendo: de-enfasi dal 3 giugno 2026 e spegnimento dell'endpoint v1/prompts previsto per il 30 novembre 2026. La guida di migrazione è esplicita: spostare il contenuto dentro il codice dell'applicazione, sostituire le variabili del prompt con argomenti di funzione tipizzati e portare il versionamento nel proprio repository, con commit, revisione e valutazioni eseguite nella pipeline di rilascio. Tradotto: le modifiche al prompt passano dallo stesso processo delle modifiche al prodotto.
Anche Anthropic va nella stessa direzione per gli agenti che operano su un progetto: le istruzioni persistenti stanno in un file CLAUDE.md che, come dice la documentazione di Claude Code, viene «condiviso con il team attraverso il controllo di versione», mentre le preferenze personali finiscono in un file locale escluso dal repository. La stessa pagina aggiunge un avvertimento che vale per qualsiasi fornitore: quelle istruzioni sono contesto, non configurazione imposta. Un prompt ben scritto orienta il comportamento, non lo vincola — per impedire un'azione servono i permessi, come nel pezzo su autonomia e permessi di un agente AI.
Per una PMI la sintesi è pratica: usa il registro del fornitore per provare, tieni la verità nel tuo repository. È l'unico posto che nessuno può dismettere con sei mesi di preavviso.
Versionare i prompt: cosa annotare a ogni modifica
Versionare i prompt non significa solo salvare file numerati. Significa che per ogni cambiamento resta scritto:
- Cosa è cambiato, nella forma del confronto riga per riga tra il testo precedente e quello nuovo.
- Chi l'ha modificato e quando, con data e ora.
- Perché: il caso reale che ha motivato la modifica — un reclamo, una risposta sbagliata, una richiesta del cliente. È il campo che si salta sempre e l'unico che sei mesi dopo serve davvero.
- Su quale modello è stato provato, con la versione esatta e non l'alias generico.
- L'esito sul set di prova: quanti casi passavano prima, quanti dopo.
- L'effetto su costo e tempi di risposta, almeno in forma di ordine di grandezza.
- Chi ha approvato e come si torna indietro.
Sette voci, nessuna delle quali richiede uno strumento particolare. Un repository Git le copre tutte con un messaggio di commit decente; un foglio condiviso le copre il 90%, che è infinitamente meglio di zero.
Come si prova un cambio di prompt prima dei clienti
Qui si ricompone il quadro con le altre pratiche. Serve un posto dove provare che non sia la produzione — lo stesso ragionamento dell'ambiente di staging per un sito aziendale, applicato a un'automazione: stessi strumenti, dati di prova anonimizzati, nessun cliente in mezzo. Serve un set di casi di prova, costruito a partire dagli errori già accaduti, da rieseguire a parità di modello prima e dopo la modifica. Serve un rilascio graduale, se l'automazione ha volumi: prima una quota di pratiche, poi tutte.
E serve un piano di rientro che non sia «riscriviamo a memoria com'era». Se il prompt è nel repository, tornare indietro è un'operazione di trenta secondi; se è in un campo di testo di una dashboard, è un esercizio di archeologia. Vale la pena aggiungere al set anche i tentativi di aggiramento raccolti durante il collaudo avversariale dell'automazione: una riga rimossa per fare spazio è il modo più comune di riaprire una falla che era già stata chiusa.
Da dove partire questa settimana
Tre passi, in ordine. Primo: trova tutti i prompt della tua azienda. Sono nei campi di testo delle dashboard, nelle note di chi ha configurato l'automazione, a volte in una chat. Secondo: mettili in file di testo, uno per agente o per flusso, in un repository con una revisione a due occhi per le modifiche. Terzo: scrivi venti casi di prova con il risultato atteso e rieseguili prima di ogni rilascio.
Chi arriva fino al terzo passo smette di avere automazioni che «a volte funzionavano meglio»: versionare i prompt è il lavoro d'ordine che rende ripetibile tutto il resto. Studiollice progetta agenti e automazioni su misura, e in ogni consegna il prompt è un file sotto controllo di versione con la sua storia: se ti serve una mano a mettere ordine nei tuoi, ne parliamo volentieri.