Approccio AI
L'AI scrive il codice che prima ci portava via le giornate. A noi resta il tempo per fare quello che davvero conta: architettura, performance, sicurezza, validazione. Insieme all'AI, non al posto suo.
> /task analizza il modulo /api/contact e proponi 3 hardening
// contesto: file allegato, limite 10k token
[claude] letto src/app/api/contact/route.ts (87 LOC, 1 endpoint POST)
finding 1 · body parsing accetta JSON arbitrario
suggerimento: validazione con zod, schema esplicito
impatto: blocca payload deformati prima dell'insert DB
finding 2 · niente rate limit né origin check
suggerimento: middleware su 1 req/30s per IP, allowlist origin
impatto: protegge da spam e CSRF semplici
finding 3 · errore generico 500 espone stack trace
suggerimento: logger interno + risposta sanitizzata
impatto: niente leak di dettagli infrastruttura
[applico le fix? y / n / mostra-diff]
Principi
Sono le cose che applichiamo prima di scrivere qualsiasi prompt o aprire qualsiasi sessione di Claude Code.
01
Ogni interazione produttiva con un modello parte da una direttiva scritta: vincoli, output atteso, criteri di accettazione. Le chat libere sono per esplorare; il lavoro reale viaggia su prompt strutturati e versionati.
02
Più contesto si fornisce, più la risposta è informata. Ma il contesto va selezionato, non riversato. Tagliamo rumore, citiamo file precisi, includiamo solo ciò che serve a quel task. Niente "ti incollo l'intero repo".
03
Ogni output che entra in produzione passa attraverso review umana o una pipeline di evaluation automatica. Niente codice nei main branch generato senza essere stato letto, capito e firmato da una persona.
04
Token, latenza, acceptance rate, costo per task. Se un'integrazione AI non si misura, non si discute. La sostenibilità economica e operativa di un sistema AI vive nei numeri, non nelle promesse.
Stack AI
Strumenti che usiamo davvero, non un catalogo di tutto. Ognuno ha il suo posto preciso nei progetti.
Modello principale per integrazioni AI in produzione: ragionamento, generazione, code analysis. 1M token di context per progetti enterprise grandi.
Come lo usiamo
Backbone di ogni feature AI: orchestrator di agenti, RAG con grandi knowledge base, classification e extraction su documenti complessi.
CLI agentic per coding nel repo: legge i file, modifica codice, esegue comandi, fa commit. Lavora con permessi granulari e checkpoint.
Come lo usiamo
Refactoring estesi, generazione di scaffolding, esplorazione di codebase nuovi, bugfix con riproducibilità. Sempre con review umana prima del merge.
Protocollo aperto per esporre tool e risorse al modello: filesystem, database, GitHub, sistemi interni del cliente. Estende le capabilities in modo controllato.
Come lo usiamo
Server MCP custom per ogni cliente: l'agente accede a documenti, ticket, PR, log con permessi precisi e audit trail.
SDK per costruire agenti con tool calling strutturato, planning multi-step, gestione stato. Schema input/output validati con Zod.
Come lo usiamo
Workflow verticali (es. estrazione dati da contratti, ticket triage, generazione report) con tool definiti, vincoli espliciti, fallback umano.
Cache server-side dei contesti ripetuti: riduce drasticamente i costi e la latenza quando lo stesso prompt strutturato si applica a input diversi.
Come lo usiamo
Sistema RAG, document Q&A su corpus stabile, code review automatizzato. Costi giù del 90% sui token cached.
Modalità di ragionamento esteso del modello per task complessi che richiedono step intermedi: piani, design review, debugging architetturale.
Come lo usiamo
Analisi di trade-off tecnici, audit di sicurezza, refactoring strutturali, sanity check su scelte critiche.
Workflow
Stesso percorso su ogni integrazione AI seria, sia che si tratti di un piccolo classifier sia di un agente complesso.
Capire se l'AI è davvero la risposta o se serve un buon vecchio script. La maggior parte dei task aziendali si risolve senza modelli generativi.
Definiamo input attesi, output atteso, vincoli, criteri di accettazione. Il prompt diventa un artefatto del progetto, versionato come il codice.
Prima di ottimizzare costruiamo 20-50 casi reali di input con output corretto. Da qui misuriamo ogni cambiamento: prompt, modello, retrieval.
Iterazioni rapide sull'eval set finché la qualità è accettabile. Solo dopo si discute scaling, costi, latenza. Niente ottimizzazione prematura.
Il sistema entra nel flusso applicativo con validation, fallback, observability completa. Nessun chiamata diretta al modello senza wrapper interno.
Dashboard di cost, latency, acceptance rate, esempi di failure. Review periodica dell'eval set con i casi reali raccolti dal traffico vero.
Pattern
Non sono opinabili: sono il minimo sindacale per un sistema AI che debba reggere in produzione.
Vector database (pgvector di default) ancorato ai documenti del cliente. Embedding con encoder dedicato, retrieval ibrido (semantic + keyword), citation espliciti nelle risposte. Niente allucinazioni mascherate.
Ogni tool dell'agente ha schema input/output validato runtime. Errori di chiamata vengono catturati, riformulati e ritentati con backoff, mai propagati silenziosamente in produzione.
Per ogni feature AI manteniamo un eval set di casi reali con output atteso. Modificare un prompt o cambiare modello richiede passare la baseline, come per qualsiasi test di regressione.
Validazione struttura output, filtri di policy, controlli di consistenza con dati di sistema, fallback a umano quando la confidence cala. Nessun output va all'utente finale senza essere attraversato.
Ogni integrazione ha un budget di costo per richiesta e una soglia di latenza p95. Se le metriche sforano, l'allarme suona prima del cliente. Si ottimizza prima che diventi un problema operativo.
Sui task ad alto impatto (decisioni clienti, scritture in DB, comunicazioni esterne) inseriamo punti di review umana. Sui task a basso rischio l'agente è autonomo. La soglia è esplicita, non emergente.
Quello che non facciamo
L'AI vista da chi la usa davvero, non da chi la racconta sui social. Ecco le scorciatoie che si pagano dopo.
Generare e accettare codice senza esperienza progettuale alle spalle. Il vibe coding funziona quando chi guida sa già dove stanno i layer, gli accoppiamenti, i punti di rottura. Senza quel mestiere, l'AI moltiplica solo il debito tecnico.
Lasciare un agente decidere su pagamenti, comunicazioni a clienti, scritture irreversibili sui dati senza supervisione umana. La probabilità di errore è bassa, ma la coda di rischio è inaccettabile.
Cambiare provider perché "oggi va questo". Le scelte di modello vanno motivate da eval comparativi sui task reali del cliente, non dalle release del giorno.
Affidare un flusso utente al modello senza piano B per quando fallisce, ha latenza alta, o costa troppo. Ogni integrazione AI deve avere un comportamento degradato accettabile.
Misurazione
Ogni integrazione AI che mandiamo in produzione ha observability completa: token consumption per task, latency p50/p95, acceptance rate degli output, costo per query e per cliente, esempi di failure salvati per la review periodica.
Quando una metrica esce dai range concordati, la dashboard suona prima del cliente. È così che un sistema AI continua a comportarsi bene mentre il traffico cambia, i prompt evolvono, i modelli si aggiornano.
Token / request
tracciati
Latenza p95
alert
Acceptance rate
weekly
Cost per query
budget
Failure samples
raccolti
Eval set
in CI
FAQ
Una call breve, lo scope reale, un piano scritto entro pochi giorni. Niente pitch, solo conversazione tecnica.