Versionare i prompt come si versiona il codice: workflow per team AI

Il bug che nessuno aveva scritto

Una scena comune nei team che hanno messo un'AI in produzione da qualche mese: il chatbot inizia a comportarsi in modo strano su una categoria di query. Il team indaga. Scopre che un mese prima qualcuno ha modificato una parola nel prompt di sistema ("cortese" invece di "empatico") per un test su un caso specifico, poi ha fatto merge senza rollback.

Nessuno ricorda quel cambio. Non c'è un diff leggibile, perché il prompt era una stringa di 3000 caratteri in mezzo al codice. Non c'è un test che mostri cosa è peggiorato.

Il bug non era tecnico. Era organizzativo. I prompt erano trattati come stringhe, non come codice.

I prompt sono logica di business, non stringhe

In un sistema AI maturo, il prompt di sistema è una delle componenti più sensibili del prodotto. Contiene:

• La personalità dell'assistant
• Le regole di cosa può e non può fare
• Le policy aziendali codificate in linguaggio naturale
• Le istruzioni per gestire edge case specifici
• Il formato atteso dell'output

Se una di queste cose va storto in produzione, l'impatto può essere grave — risposte imbarazzanti, rischi legali, perdita di clienti. Eppure molti team trattano i prompt con meno rigore di quanto trattino una configurazione di environment.

La prima mossa strategica è semplice: i prompt vivono in un repository, sotto controllo versione, con review obbligatoria. Non sono stringhe hard-coded da modificare in fretta.

Struttura a file invece che a stringa

Un pattern che si ripaga subito: invece di avere il prompt come una stringa Python multi-riga nel codice, separarlo in file dedicati.

/prompts
  /customer_support
    system.v12.md
    guardrails.v4.md
    examples.v8.yaml
  /lead_qualifier
    system.v7.md
    scoring_rules.v3.md

Con questa struttura ottieni automaticamente:

• Diff leggibili quando qualcuno cambia qualcosa
• Possibilità di usare il linter markdown per catturare errori di formattazione
• Separazione chiara tra la logica del sistema e i dati di supporto (examples, rules)
• Capacità di caricare versioni diverse per ambienti diversi (dev, staging, prod)

Il caricamento nel codice diventa un import pulito:

from prompt_loader import load_prompt

prompt = load_prompt(
    role="customer_support",
    component="system",
    version="v12"
)

Il vantaggio concreto arriva al primo incident: invece di scorrere commit history cercando "chi ha toccato quella stringa", apri la cartella, vedi tutti i cambiamenti, capisci l'evoluzione.

Il versioning semantico dei prompt

Non tutti i cambiamenti a un prompt sono uguali. Un pattern utile è distinguere tre tipi di modifiche con una numerazione semantica:

Patch (v12.0 → v12.1): correzioni di typo, piccole riformulazioni che non cambiano il comportamento atteso. Non richiedono test estesi.

Minor (v12 → v13): aggiunte di capacità o istruzioni. Cambiano il comportamento in casi nuovi senza rompere quello esistente. Richiedono test su regression set.

Major (v13 → v20): cambi strutturali o di tono. Possono cambiare il comportamento anche su casi che prima funzionavano. Richiedono A/B test prima del rollout completo.

Questa disciplina fa due cose. La prima è obbligare a pensare all'impatto prima di fare il cambio. La seconda è dare al team di QA un segnale chiaro su quanto test serve.

Il regression set obbligatorio

Ogni prompt in produzione dovrebbe avere un regression set associato — un file di test con query di input e risultati attesi (o proprietà verificabili). Prima di mergeare qualunque modifica, il regression set deve passare.

# prompts/customer_support/regression.v12.yaml
tests:
  - id: refund_policy_edge_case
    input: "Voglio essere rimborsato per un ordine di 3 mesi fa"
    expected_properties:
      - mentions_30_day_policy: true
      - suggests_escalation: true
      - tone: "empathetic"
  
  - id: off_topic_coding_question
    input: "Come si scrive una funzione Python per ordinare una lista?"
    expected_properties:
      - refuses_politely: true
      - redirects_to_support_topic: true
      - no_code_output: true

I regression set non devono coprire tutto. Devono coprire i casi che in passato hanno fatto perdere tempo al team o causato incident. La regola utile: ogni volta che un problema arriva in produzione, il fix include un test nel regression set. Così lo stesso problema non può tornare silenziosamente.

La review dei prompt è review di codice

Un cambiamento a un prompt di produzione merita lo stesso tipo di review che meriterebbe un cambiamento a logica critica del sistema. Questo significa:

• Almeno un revisore diverso dall'autore
• Diff chiaro di cosa è stato modificato
• Spiegazione del perché il cambio è necessario
• Evidenza che i test di regression passano
• Indicazione dell'impatto atteso sul comportamento

Un pattern che aiuta: richiedere nella descrizione della PR una sezione "Atteso cambiamento di comportamento" che descrive a parole cosa il sistema dovrebbe iniziare a fare diversamente. Se l'autore non riesce ad articolarlo, probabilmente non ha testato abbastanza.

Il rollout progressivo

Per modifiche major, fare il deploy a tutti gli utenti contemporaneamente è un rischio non necessario. I pattern di rollout progressivo tradizionali funzionano anche per i prompt:

Canary deploy: la nuova versione va al 5% del traffico per 24h. Se le metriche di qualità sono stabili, si espande al 25%, poi al 100%.

Shadow deploy: la nuova versione gira in parallelo alla vecchia senza essere mostrata all'utente. Si confrontano le risposte a posteriori per capire differenze di comportamento.

Feature flag per segmento: la nuova versione va prima agli utenti interni, poi a utenti beta, poi a tutti.

Ogni deploy progressivo ti dà una finestra per accorgerti di un problema prima che diventi un incident diffuso. Senza deploy progressivo, ogni cambio di prompt è una scommessa sull'intero traffico.

Il prompt come asset condiviso

In team con più persone che lavorano sull'AI, i prompt rischiano di diventare silos. Ognuno ha "il suo" prompt, con le sue convenzioni, le sue abbreviazioni, le sue decisioni. Quando uno degli autori lascia il team, il sistema diventa un mistero.

Due pratiche riducono questo rischio:

Stile guide dei prompt. Un documento di team che definisce convenzioni: come si scrivono le istruzioni, come si strutturano le sezioni, quali parole chiave usare per i tool, come si formattano gli esempi. È noioso da scrivere e paga immensamente.

Pairing su modifiche significative. Le modifiche major ai prompt si fanno in due. Non per rallentare, ma per assicurarsi che almeno due persone capiscano il reasoning dietro ogni scelta.

La documentazione del perché, non del cosa

Un errore comune è documentare i prompt descrivendo cosa fanno. "Questo prompt classifica le email in cinque categorie". Utile, ma limitato.

La documentazione che paga davvero descrive perché il prompt è fatto così:

• Perché queste cinque categorie e non quattro o sei
• Perché l'esempio X è incluso (ha risolto un bug specifico)
• Perché l'istruzione "non menzionare mai prezzi" è al secondo paragrafo e non al primo
• Quali alternative sono state provate e scartate, con il motivo

Questa documentazione protegge il prompt dall'erosione. Senza di essa, un nuovo membro del team vedrà un'istruzione "strana" e proverà a rimuoverla, scoprendo solo in produzione che era lì per un motivo.

La migrazione graduale

Non serve rifare tutto in un giorno. Un team che vuole adottare queste pratiche può procedere per step:

1. Settimana 1-2: estrarre i prompt in file separati, sotto version control
2. Settimana 3-4: scrivere un regression set minimo per i casi più critici
3. Settimana 5-8: introdurre la review obbligatoria per modifiche ai prompt
4. Mese 3+: rollout progressivo per cambiamenti major

Dopo tre mesi, la differenza è misurabile: meno incident legati a modifiche di prompt, onboarding più veloce di nuovi membri, debugging di problemi storici drasticamente più rapido.

La disciplina invisibile

Versionare i prompt non è glamour. Non produce demo impressionanti. Non finisce nei blog post di annuncio.

Ma distingue un team che sta giocando con l'AI da un team che sta mettendo l'AI in produzione seriamente. Il momento in cui serve sapere "cosa ha scritto il nostro prompt 47 giorni fa quando quel cliente ha ricevuto quella risposta" è il momento in cui capisci se hai investito in questa disciplina o no. Dopo, è troppo tardi.