Prompt Engineering professionale

1. Anatomia di un prompt professionale

Un prompt efficace ha quasi sempre la stessa struttura. Non è una ricetta magica: è la stessa disciplina di uno user story ben scritto applicata a un interlocutore non umano.

1. Ruolo e contesto — chi stai parlando, in quale progetto, con quali vincoli.
2. Obiettivo — cosa deve produrre il modello, in una frase.
3. Input — i dati concreti su cui lavorare (codice, testo, specifica).
4. Vincoli — cosa NON deve fare, stile, formato, lunghezza, librerie ammesse.
5. Output atteso — formato, schema, esempi.
6. Criteri di qualità — come riconoscerai una risposta buona.

Ruolo: sei un senior .NET engineer in Blulink.
Contesto: stiamo manutenendo un microservizio di fatturazione,
stack .NET 8, Entity Framework Core, xUnit per i test.
Obiettivo: aggiungere validazione del campo "PartitaIVA" con
le regole italiane sul check digit.
Input: <codice della classe InvoiceValidator>
Vincoli:
  - niente nuove dipendenze esterne
  - mantenere la firma pubblica dei metodi
  - test unitari obbligatori per casi validi e invalidi
Output:
  - diff unificato dei file modificati
  - elenco dei test aggiunti con breve descrizione
Qualità:
  - i test passano
  - copertura dei casi edge (stringhe vuote, null, lunghezza
    sbagliata, check digit errato)

2. Tecniche: zero-shot, few-shot, chain-of-thought guidato

Zero-shot

Descrizione diretta del task, senza esempi. Funziona quando il task è chiaro e frequente nel training del modello ("scrivimi un test xUnit per questa classe"). È la tecnica di default: non aggiungere esempi se non servono.

Few-shot

Si forniscono 1–5 esempi di input/output che mostrano al modello il formato e lo stile desiderati. Indispensabile quando il task è strano rispetto al pre-training: trasformazioni di formato proprietarie, stili di commit aziendali, convenzioni di naming interne.

Genera messaggi di commit nel formato Blulink:
<scope>: <verbo imperativo> <oggetto> [ticket]

Esempi:
invoicing: add PartitaIVA check digit validation [AB-1423]
auth:      fix token refresh race condition [AB-1401]
docs:      update deploy runbook for staging [AB-1389]

Adesso, dato questo diff, produci un solo messaggio di commit:
<diff>

Chain-of-Thought (CoT) guidato

Invece di chiedere la risposta finale, si chiede al modello di pianificare prima: "prima analizza, poi proponi un piano, poi implementa". Abbassa drasticamente il tasso di errori su task non banali. Nei modelli moderni con reasoning è spesso implicito, ma esplicitarlo aiuta comunque sui task di engineering.

Structured output

Quando l'output deve essere consumato da un'altra pipeline, chiedere JSON con uno schema preciso (o usare le API di structured output di OpenAI/Anthropic). Elimina le parsing failure e rende il prompt parte di un vero contratto.

3. Prompt per coding, analisi, debugging e refactoring

Prompt per scrivere codice

Regola base: non chiedere codice, chiedi specifiche eseguite. Un prompt di coding dovrebbe quasi sempre contenere: il pezzo di codice rilevante, i test che devono passare, i vincoli di stile, e come il modello deve consegnare il risultato (diff vs file intero, singolo file vs multifile).

Prompt per analisi tecnica

Esempio: "spiegami cosa fa questa classe e perché è scritta così, evidenziando potenziali bug e decisioni di design implicite". È uno dei prompting più efficaci in assoluto nelle codebase legacy. Il modello diventa un pair senior che legge il codice insieme a te.

Prompt per debugging

Fornire: il codice, il messaggio di errore completo, i passi per riprodurre, cosa hai già provato. Quest'ultimo punto è quello che i developer dimenticano più spesso e che rende la differenza tra "il modello propone la soluzione ovvia che non funziona" e "il modello propone la meno ovvia che funziona".

Ho questo errore in produzione:
<stack trace>

Il codice rilevante è:
<snippet>

Cosa ho già escluso:
- non è un problema di connessione al DB (verificato con telnet)
- non è un problema di permessi (l'utente ha i ruoli corretti)
- il test <nome> passa in locale

Aiutami a identificare ipotesi che non ho considerato,
ordinate per probabilità, con per ognuna il modo di verificarla.

Prompt per refactoring

Il refactoring è il caso d'uso dove gli LLM brillano di più — se fatto con metodo. Tre passaggi: (1) caratterizzare il comportamento attuale con test, (2) pianificare il refactoring in passi piccoli e reversibili, (3) eseguire un passo alla volta rilanciando i test.

4. Prompt per la documentazione tecnica

La documentazione è probabilmente il singolo caso d'uso con il ROI più alto e più sottovalutato. In Blulink, dove esistono sia sviluppatori interni sia utenti finali, il prompt engineering per le docs va suddiviso per pubblico.

Docs interne: per sviluppatori

Tipi di output: README di modulo, ADR (Architectural Decision Records), runbook operativi, onboarding doc, commenti di codice "perché" (non "cosa").

Pattern di prompt: fornire il codice rilevante, la storia delle decisioni (commit messages, PR description) e chiedere un output in Markdown con struttura fissa. Output atteso tipicamente è un diff sul file docs, non un testo libero.

Genera un ADR in formato standard (Title / Status / Context /
Decision / Consequences) per questa scelta.

Contesto tecnico:
<descrizione>

Alternative valutate:
<lista>

Decisione presa:
<descrizione>

Target lettore: ingegnere che arriva in azienda fra 12 mesi e
deve capire perché abbiamo fatto così.

Docs esterne: guide utente, help online, release notes

Tipi di output: manuali operativi, FAQ, help contestuale, note di rilascio leggibili da non-tecnici. Il prompt engineering cambia radicalmente: servono persone utente esplicite, linguaggio controllato (glossario aziendale), screenshot e riferimenti a passi concreti nell'interfaccia.

Sei un technical writer di Blulink. Scrivi note di rilascio
per la versione 2024.03 del prodotto.
Lettore tipo: responsabile qualità in azienda manifatturiera
italiana, conosce il prodotto a livello funzionale ma non tecnico.

Tono: professionale, chiaro, in italiano, senza gergo tecnico.
Formato: intro (2 righe), lista feature (titolo, beneficio per
l'utente, istruzioni in 2–3 passi), bug fix (lista secca),
note di upgrade.

Input:
- changelog tecnico: <...>
- ticket risolti: <...>
- nuove funzionalità descritte dal PM: <...>

5. Automazione: pipeline AI-driven per la documentazione

Una pipeline di documentazione AI-driven è un sistema che rigenera automaticamente parti della docs a partire da eventi ingegneristici (merge su main, nuovo tag, nuovo changelog, modifica di un file).

Architettura di riferimento

1. Trigger. Un evento su Azure DevOps (push, PR mergiata, pipeline completata).
2. Collettore di contesto. Uno script che raccoglie: diff, commit messages, file modificati, eventuali work item collegati.
3. Classificatore. Un LLM decide se la modifica richiede aggiornamento docs e quali sezioni toccare. Structured output obbligatorio.
4. Generatore. Un LLM (o un agente) aggiorna le sezioni identificate, lavorando su una copia locale dei file di docs.
5. Review gate. La pipeline apre una PR sul repo della documentazione. Un umano fa review in qualche minuto.

Perché questo pattern funziona in enterprise

• La documentazione è sempre dietro a una PR e un review umano: niente docs inventate che finiscono pubblicate senza controllo.
• La pipeline può essere disattivata su cartelle sensibili (es. policy di sicurezza, contratti).
• Tutto è versionato e auditabile: sai chi ha approvato cosa, quando.

Esempio: pipeline per release notes automatiche

# pseudo-pipeline Azure DevOps
trigger:
  tags: ['v*']

steps:
  - raccogli commit tra tag precedente e corrente
  - raggruppa per scope (feature, fix, docs, chore)
  - invoca modello con:
      * lista commit raggruppati
      * template release notes aziendale
      * glossario prodotto
      * ultimo release notes come stile di riferimento
  - ottieni markdown strutturato
  - apri PR su repo docs/release-notes
  - notifica il PM su Teams

6. Standardizzazione dei prompt a livello team

I prompt che funzionano sono asset aziendali, non frammenti personali. Un team maturo li gestisce come codice: versionati, revisionati, testati.

Prompt library

Una cartella nel repo (es. /.ai/prompts/) con un file Markdown per ogni prompt riutilizzabile: code review, generazione test, redazione release notes, classificazione ticket. Ogni prompt ha frontmatter con metadata (autore, scope, modello target, versione).

System prompts condivisi

Tutti gli strumenti AI-first permettono di definire un system prompt a livello progetto (Claude Code: CLAUDE.md; Cursor: .cursorrules; Copilot: custom instructions). Questi file sono il posto dove codificare le regole di team: stile di codice, convenzioni di naming, stack, vincoli di sicurezza, linguaggio italiano nella documentazione.

Test dei prompt

Sì, anche i prompt andrebbero testati. Esistono framework (vedi risorse) che eseguono lo stesso prompt su un set di input e verificano proprietà dell'output (tipo, struttura, presenza di campi, eventualmente assertion semantiche). Utile soprattutto per pipeline AI-driven in produzione.

Ciclo di vita

Ogni prompt ha un ciclo di vita: proposta → revisione in PR → merge → uso in team → metriche di efficacia → evoluzione. È engineering, non folklore.