Direttive scritte: trattare i prompt come codice di produzione

C'è una differenza enorme fra "parlare con un modello" e "lavorare con un modello". La prima cosa la sa fare chiunque. La seconda richiede una piccola disciplina che cambia completamente l'esito del lavoro: scrivere direttive prima di iniziare, e versionarle come codice.

In questo articolo raccontiamo come lo facciamo, perché ha senso e cosa cambia nel risultato concreto.

Una chat non è una direttiva

Aprire Claude o ChatGPT, scrivere "fammi una funzione che valida un IBAN", iterare a senso, copia-incollare il risultato in produzione: è il flusso che la maggior parte delle persone usa quando inizia. È anche il flusso che produce, in modo statisticamente prevedibile, codice che funziona sul caso che hai mostrato e si rompe sui casi che non hai mostrato.

Una direttiva, al contrario, è un documento breve ma strutturato che descrive:

• Obiettivo: cosa deve fare il sistema, in una frase.
• Input attesi: forma, tipo, vincoli, edge case noti.
• Output atteso: forma, tipo, schema validabile.
• Vincoli non negoziabili: cose che non devono mai accadere (eccezioni leak, side effect, side channel, ecc.).
• Criteri di accettazione: come si decide se l'output è buono o no.

È un piccolo investimento di tempo (10-15 minuti per un task non banale) che ti restituisce ore di iterazione persa.

Il template che usiamo

Lo abbiamo standardizzato. Ogni direttiva sta in un file .md nel repo, accanto al codice che la consuma.

# Direttiva · IBAN validator

## Obiettivo
Validare un IBAN italiano (IT) lato server prima di salvarlo in DB.

## Input
- string, anche con spazi e maiuscole/minuscole miste
- lunghezza grezza variabile

## Output atteso
{ valid: boolean, normalized: string | null, reason?: string }

## Vincoli
- nessuna chiamata di rete (la validazione è offline)
- nessuna eccezione propagata: tutto in `valid: false`
- normalized in maiuscolo, senza spazi

## Casi di accettazione
1. "IT60 X054 2811 1010 0000 0123 456" → valid: true
2. "it60x0542811101000000123456"      → valid: true (case-insensitive)
3. "IT60X054281110100000012345"        → valid: false (lunghezza)
4. "FR1420041010050500013M02606"       → valid: false (non IT)
5. ""                                  → valid: false (empty)
6. null                                → valid: false (no throw)

## Note
Algoritmo: ISO 13616 + check IT (CIN, ABI, CAB, conto).

Questo file viene committato insieme al codice che valida l'IBAN. Quando un anno dopo qualcuno chiede "perché qui non chiamiamo un servizio di verifica?", la risposta è scritta accanto.

Versionati, in PR, rivisti

Le direttive non vivono nel canale Slack di sprint o nel cervello di chi le ha scritte. Vivono nel repo. Conseguenze pratiche:

• Una modifica al prompt è un commit. Si vede nel diff, si discute in PR.
• Una regression si attribuisce a un commit specifico.
• Quando la direttiva cambia, l'eval set deve continuare a passare (vedi l'articolo sull'eval set).
• Quando si cambia modello, si tiene la stessa direttiva e si misura: il nuovo modello regge la baseline?

Il codice di un sistema AI non è solo il glue code, è anche il prompt. Trattarli in modo asimmetrico è un debito tecnico mascherato.

Stratificare la direttiva

Per task complessi, una singola direttiva non basta. Stratifichiamo:

• System prompt: identità del sistema, vincoli generali, formato output. Stabile, cambia raramente.
• Task prompt: istruzioni specifiche per il task corrente. Cambia con la feature.
• Few-shot examples: 2-5 esempi di input/output. Cambia con i casi reali raccolti.
• Runtime context: dati specifici della richiesta (utente, documento, query). Cambia per ogni chiamata.

Trattiamo i primi tre come sorgente. Il quarto è dato. Mescolarli è esattamente come mescolare codice e dati in produzione: si fa una volta, poi non si fa più.

Cosa NON facciamo

Per chiarezza, ecco le abitudini che evitiamo deliberatamente:

• "Generami un prompt" chiesto al modello stesso, senza review umana. Il modello produce prompt che spesso suonano bene ma sono troppo generici, troppo lunghi, o pieni di istruzioni contraddittorie.
• Prompt copia-incollati da Twitter senza adattamento al contesto reale. Quei prompt sono tarati su demo, non sul tuo task.
• Prompt-fiume da 4000 token scritti come se più parole significasse più qualità. Quasi sempre è il contrario: chiaro e corto batte lungo e ridondante.
• Modifiche al prompt senza eval. Non ha senso parlarne due volte: se non hai un eval set, ogni modifica è alla cieca.

La direttiva è una decisione architetturale

L'aspetto che spesso sfugge: una direttiva ben scritta è una decisione architetturale codificata. Quando scrivi "nessuna chiamata di rete" in un vincolo, stai dicendo qualcosa sul resto del sistema (deve funzionare offline, deve essere veloce, deve essere indipendente da servizi esterni). Quando definisci l'output con uno schema, stai dichiarando il contratto fra quel modulo e tutti gli altri.

Il prompt non è un dettaglio implementativo. È il punto in cui la specifica diventa eseguibile. Trattarlo come tale rende l'intero sistema più solido, e rende l'AI un componente predicibile invece di una sorgente di sorprese.