Capstone: progettare, valutare e versionare un prompt reale

Il capstone chiude il corso trasformando tutte le tecniche in un artefatto unico: non un prompt bello da leggere, ma un piccolo sistema di prompt pronto per un team.

Deve contenere obiettivo, template, variabili, schema, eval, versioni, sicurezza, budget, rollout e ownership. Se manca una di queste parti, il progetto può funzionare in demo ma non è ancora maturo.

Perché questa lezione conta

Il prompt engineering professionale non si misura dalla frase più brillante. Si misura dalla capacità di produrre comportamento ripetibile, verificabile e mantenibile. Il capstone serve a dimostrare proprio questo.

Alla fine non devi presentare “la risposta migliore ottenuta”. Devi presentare un sistema che spiega come hai scelto, cosa hai misurato, quali limiti hai trovato e come il team può continuare a lavorarci.

Obiettivo operativo

Alla fine della lezione devi saper progettare un sistema di prompt completo per un task reale, documentarlo in repo e difendere le scelte davanti a un team tecnico.

Scegliere il task

Il task deve essere reale, ricorrente e valutabile. Esempi buoni:

1. classificare issue o ticket;
2. generare test per funzioni pure;
3. fare triage di PR piccole;
4. estrarre dati da documenti standardizzati;
5. riassumere incident report;
6. suggerire risposta a richieste supporto;
7. controllare checklist di sicurezza su diff.

Esempi troppo grandi:

1. “automatizzare tutto il supporto”;
2. “fare code review perfetta”;
3. “sostituire il project manager”;
4. “costruire un agente che gestisce il prodotto”.

La forma corretta è verbo-oggetto-criterio:

Classificare ticket di supporto in una categoria ammessa, restituendo JSON valido e marcando per review umana i casi ambigui o ad alto rischio.

Struttura del progetto

Una struttura consigliata:

prompt-system/
  README.md
  prompts/
    classify-ticket/
      v1/
        prompt.md
        input.schema.json
        output.schema.json
        changelog.md
  evals/
    classify-ticket.jsonl
    report-v1-v2.md
  tools/
    catalog.md
    permissions.md
  docs/
    threat-model.md
    rollout.md
    governance.md

Non serve che tutto sia automatizzato. Serve che tutto sia esplicito.

Prompt e template

Il template deve includere:

1. ruolo operativo;
2. contesto necessario;
3. obiettivo;
4. vincoli;
5. formato output;
6. criteri di rifiuto o review;
7. variabili delimitate;
8. esempi se utili.

Ogni variabile deve avere significato chiaro. Evita placeholder generici come {{data}}. Usa nomi che raccontano dominio e responsabilità: {{ticket_body}}, {{allowed_categories}}, {{customer_plan}}, {{policy_excerpt}}.

Schema e parser

Se l’output guida codice, deve avere schema. Il capstone deve dichiarare:

1. campi obbligatori;
2. enum;
3. campi opzionali;
4. condizioni per needs_human_review;
5. cosa succede se il parser fallisce;
6. esempi validi e non validi.

La risposta non deve essere usata direttamente solo perché “sembra JSON”. Deve passare da validazione.

Eval set

Il dataset minimo deve contenere almeno 20 casi. Distribuiscili:

1. casi normali frequenti;
2. casi limite;
3. input ambigui;
4. input ostili o rumorosi;
5. casi ad alto rischio;
6. casi in cui il sistema deve chiedere review umana.

Per ogni caso scrivi aspettativa prima di eseguire. Non valutare a posteriori in base all’output che ti piace.

Iterazione

Il progetto deve mostrare almeno due versioni:

v1:
- prompt iniziale strutturato
- eval baseline

v2:
- modifica mirata
- stesso eval set
- confronto
- decisione

Il report deve includere miglioramenti, regressioni, costo, latenza e decisione finale. Se una regressione è accettata, spiega perché.

Sicurezza e dati

Anche un capstone piccolo deve includere threat model minimo:

1. input non fidati;
2. dati sensibili possibili;
3. prompt injection plausibili;
4. tool con side effect;
5. azioni vietate;
6. redazione;
7. conferme umane;
8. fallback.

Se il task non usa tool, dichiaralo. Se usa tool, aggiungi schema, permessi, dry run e rollback.

Budget e osservabilità

Stima:

1. token medi input/output;
2. costo per richiesta;
3. latenza target;
4. limiti hard;
5. fallback se supera budget;
6. eventi da loggare;
7. retention dei dati.

Non serve una previsione perfetta. Serve dimostrare che hai pensato al comportamento operativo.

Rollout e governance

Definisci:

1. owner;
2. revisori;
3. livello di rischio;
4. flag o modalità di rilascio;
5. metriche;
6. soglie rollback;
7. policy per modifiche future.

Il capstone deve poter passare di mano. Se solo tu sai come modificarlo, non è un sistema di team.

Laboratorio guidato

Lavora in quattro passaggi:

1. Design. Scegli task, obiettivo, utenti, rischi e output.
2. Implementazione. Scrivi template, schema, eventuali tool e README.
3. Evaluation. Costruisci dataset, esegui v1 e v2, produci report.
4. Produzione. Aggiungi budget, osservabilità, rollout e governance.

Alla fine prepara una presentazione tecnica di 5 minuti: problema, soluzione, trade-off, risultati eval, rischi residui.

Output atteso

Il capstone deve consegnare:

1. repo o directory versionata;
2. prompt template;
3. input e output schema;
4. dataset eval;
5. report confronto v1/v2;
6. threat model;
7. piano budget/fallback;
8. schema osservabilità;
9. rollout;
10. governance.

Rubrica di valutazione

Chiarezza del task. Il problema è stretto, reale e verificabile.

Qualità del prompt. Contesto, vincoli e formato sono chiari.

Qualità dell’eval. I casi coprono distribuzione reale e casi critici.

Robustezza. Sicurezza, dati sensibili e fallback sono considerati.

Mantenibilità. Versioni, changelog, owner e policy sono presenti.

Onestà tecnica. Limiti e regressioni sono dichiarati, non nascosti.

Errori comuni

Scegliere un task enorme. Meglio un sistema piccolo ma completo che un’idea grande non valutabile.

Mostrare solo successi. Un buon capstone include casi falliti e decisioni difficili.

Saltare eval. Senza confronto, hai solo un prompt scritto bene.

Dimenticare ownership. Un sistema senza proprietario decade velocemente.

Checklist di verifica

• il task è espresso come verbo-oggetto-criterio;
• prompt, schema, eval e README sono versionati;
• esistono almeno due versioni confrontate;
• sicurezza, budget, osservabilità e rollout sono documentati;
• il progetto può essere preso in mano da un altro sviluppatore.

Collegamenti

• Modulo: Prompt in produzione e governance — questa lezione è la numero 40 del corso.
• Riprende tutti i moduli precedenti e chiude il percorso con un artefatto unico.