Guida alle specifiche

Un compagno pratico agli Standard di Esecuzione. Gli Standard definiscono i livelli e i primitivi. Questa guida mostra come usarli.

Quando hai bisogno di una specifica?

Non ogni interazione IA richiede una specifica formale. Usa questo albero decisionale:

Usa un prompt quando:

Il compito è un singolo passaggio con criteri di successo ovvi
Valuterai l'output immediatamente
Il fallimento non costa nulla (puoi semplicemente ripromptare)

Usa un prompt + file di contesto quando:

Il compito richiede conoscenza del dominio (terminologia, voce del brand, vincoli tecnici)
Hai già fatto questo tipo di compito prima e la qualità è importante
L'output verrà usato da altri

Usa una specifica completa quando:

Il compito ha più passaggi o dipendenze
Più persone o agenti lavoreranno su parti di esso
Il fallimento è costoso (codice di produzione, output rivolto ai clienti, azioni irreversibili)
Hai bisogno che qualcun altro verifichi il risultato senza farti domande
Il compito verrà ripetuto e dovrebbe produrre risultati consistenti

La soglia non è la complessità – è il costo del fallimento. Un compito semplice con alta posta in gioco ha bisogno di una specifica. Un compito complesso con zero posta in gioco può iniziare con un prompt.

Scrivere una specifica richiede tempo. Ma la ricerca mostra che si ripaga: arricchire una descrizione del problema prima che un agente inizi il lavoro produce un miglioramento del 20% nei tassi di risoluzione, e gli agenti più deboli vedono i guadagni maggiori. È più economico migliorare la specifica che migliorare l'agente.

I quattro livelli in pratica

Gli Standard definiscono quattro livelli obbligatori. Questi livelli formano una progressione cumulativa di maturità – ogni livello si costruisce sul precedente. Ecco come appare ciascuno quando fatto bene.

Livello 1 – costruzione del prompt

La base. Stai scrivendo un'istruzione chiara.

Sembra ragionevole ma ha lacune:

Scrivi una sequenza di 3 email di onboarding per gli utenti di prova che non si sono ancora attivati. Rendila amichevole e utile. Includi CTA.

Meglio – abbastanza specifico da verificare:

Scrivi una sequenza di 3 email nurture per gli utenti di prova che si sono registrati ma non hanno completato l'onboarding entro 7 giorni. Obiettivo: farli completare il loro primo progetto. Tono: utile, non insistente. Ogni email dovrebbe essere sotto le 100 parole con una CTA chiara. Email 1 (giorno 3): evidenzia il modo più facile per iniziare. Email 2 (giorno 5): condividi un template che possono personalizzare. Email 3 (giorno 7): offri una chiamata di onboarding di 15 minuti. Le righe dell'oggetto dovrebbero essere conversazionali, non promozionali.

Il primo prompt sembra completo ma lascia aperte domande critiche: cosa significa "attivato"? Quante email? Quanto lunghe? A cosa punta la CTA? L'agente riempirà quei gap con supposizioni – e le supposizioni sono dove la qualità si deteriora.

La regola del ≤20% di correzioni: Se devi regolarmente correggere più del 20% dell'output IA, il problema è il tuo prompt, non il modello. Investi nell'istruzione, non nella modifica del risultato.

Livello 2 – ingegneria del contesto

Il contesto è tutto ciò che l'agente deve sapere che non è nel prompt. Andrej Karpathy definisce l'ingegneria del contesto come "l'arte e la scienza delicate di riempire la finestra di contesto con le informazioni giuste per il prossimo passaggio."

La domanda chiave non è "cosa potrebbe essere rilevante?" – è "cosa ha bisogno di vedere l'agente adesso?" Più contesto non è contesto migliore. La ricerca mostra che i modelli raggiungono limiti di prestazione quando sono sopraffatti da informazioni, indipendentemente dalla dimensione della finestra di contesto.

Cinque criteri di qualità (Vishnyakova, 2026):

Rilevante – solo ciò che è necessario per il passaggio corrente. I dati irrilevanti peggiorano attivamente l'output.
Sufficiente – tutto ciò che è necessario per prendere una decisione senza indovinare. Il contesto mancante è la principale causa architettonica delle allucinazioni.
Isolato – ogni passaggio o sotto-agente vede solo il proprio contesto. Condividere tutto causa fallimenti composti (vedi Modi di fallimento del contesto).
Economico – token minimi preservando la qualità. Anthropic inquadra questo come trovare "il più piccolo insieme possibile di token ad alto segnale."
Tracciabile – ogni pezzo di contesto attribuibile a una fonte. Quando qualcosa va storto, devi sapere quale input l'ha causato.

Un file di contesto del team non è un dump del cervello. È un insieme curato di fatti di cui l'agente ha bisogno per i compiti ricorrenti. Mantienilo conciso e con solo le insidie – viene caricato in ogni sessione, quindi ogni riga deve essere universalmente applicabile.

# Contesto del Team Customer Success

## Obiettivi
- Fidelizzare i clienti esistenti (fidelizzazione > acquisizione)
- Ridurre il tempo di risoluzione per i ticket di supporto
- Identificare opportunità di espansione nei conti esistenti

## Vincoli
- Non condividere mai dati dei clienti tra conti
- Non promettere mai funzionalità non ancora rilasciate
- Escalation delle dispute di fatturazione oltre €500 a un manager
- SLA di tempo di risposta: prima risposta entro 4 ore

## Terminologia
- "Partner" = conto rivenditore (non un cliente normale)
- "White-label" = versione con marchio del cliente della piattaforma
- "Link branding" = dominio personalizzato per i link di tracciamento

## Standard di qualità
- Le risposte devono affrontare la domanda specifica, non le FAQ generiche
- Includere i passi successivi in ogni risposta
- Se non si è sicuri, dirlo – non indovinare

Just-in-time vs. upfront: Non caricare tutto in anticipo. Usa una strategia ibrida – carica sempre il file di contesto del team e la terminologia; carica dati specifici (dati dei clienti, cronologia dei ticket, documentazione) su richiesta. L'agente dovrebbe sapere dove trovare le informazioni, non memorizzarle tutte.

Per un trattamento più approfondito dell'ingegneria del contesto, vedi Effective Context Engineering for AI Agents di Anthropic.

Livello 3 – ingegneria dell'intento

L'intento risponde: "Per cosa dovrebbe ottimizzare l'agente, e quali compromessi può fare?"

Senza un intento esplicito, gli agenti ottimizzano la metrica più misurabile disponibile – che raramente è ciò che vuoi davvero. Il caso di studio Klarna lo illustra: il loro agente IA ha gestito due terzi delle richieste dei clienti e ha risparmiato 60 milioni di dollari, ma il CEO ha riconosciuto pubblicamente che la qualità ne aveva sofferto perché l'agente ottimizzava il costo per token, non il valore delle relazioni con i clienti. Come dice un ricercatore: "Il contesto senza intento è rumore."

Intento per un flusso di lavoro di supporto:

## Gerarchia degli obiettivi (in ordine di priorità)
1. Accuratezza – non dare mai informazioni errate
2. Risoluzione – risolvere il problema reale del cliente,
   non solo rispondere alla sua domanda
3. Tono – corrispondere alla voce del brand (amichevole, competente)
4. Efficienza – mantenere le risposte concise

## Regole di compromesso
- Accuratezza vs. velocità → scegli l'accuratezza
- Tono vs. efficienza → mantienilo caldo, anche se più lungo
- Incerto su una risposta tecnica → dirlo,
  non indovinare

## Condizioni di escalation
- Il cliente menziona azioni legali → immediatamente
- Disputa di fatturazione oltre €500 → manager
- Problema tecnico che affligge più clienti
  → ingegneria
- Stessa domanda posta tre volte → supporto senior

## Autorità decisionale
Può: redigere risposte, cercare dettagli del conto,
  citare la knowledge base
Non deve: promettere rimborsi, condividere dati di altri clienti,
  impegnarsi su funzionalità future

Intento per un flusso di lavoro di ingegneria:

## Gerarchia degli obiettivi (in ordine di priorità)
1. Correttezza – il codice deve superare tutti i test esistenti
2. Manutenibilità – leggibile da uno sviluppatore non familiare
   con il codebase
3. Prestazioni – soddisfare i requisiti SLA
4. Semplicità – preferire meno righe rispetto all'astrazione

## Regole di compromesso
- Correttezza vs. velocità → scegli la correttezza
- Manutenibilità vs. prestazioni → favorire la leggibilità
  a meno che l'SLA non sia a rischio
- Quando più approcci sono validi → scegliere quello
  con meno accoppiamento ad altri moduli

## Condizioni di escalation
- Il cambiamento richiede la modifica di un'API pubblica → escalation
- L'impatto sulle prestazioni supera il 10% sui percorsi critici
  → escalation
- La soluzione richiede una migrazione del database → escalation

## Autorità decisionale
Può: fare refactoring nell'ambito del compito,
  aggiungere funzioni helper, aggiornare i test correlati
Non deve: modificare API pubbliche, modificare codice non correlato,
  saltare la copertura dei test

Livello 4 – ingegneria delle specifiche

Una specifica è un insieme completo e autocontenuto di istruzioni per un compito non banale. Include tutto ciò di cui l'agente ha bisogno e nulla di ciò di cui non ha bisogno.

I sette componenti richiesti (dagli Standard):

Descrizione del problema – cosa deve accadere e perché
Ambito – cosa è incluso e cosa esplicitamente non lo è
Input – a cosa ha accesso l'agente
Vincoli – le categorie Deve / Non deve / Preferisce / Escalation
Criteri di accettazione – come verificare che l'output sia corretto (come appare "fatto", obiettivamente)
Condizioni di fallimento – cosa conta come un tentativo fallito
Test di successo – scenari specifici che l'output deve gestire

I cinque primitivi con esempi

Primitivo 1 – descrizioni del problema autocontenute

Il test: qualcuno senza contesto sul tuo progetto potrebbe eseguire questo compito usando solo ciò che è scritto?

Sembra completo ma non lo è:

Lo scheduler dei lavori è troppo lento per i batch grandi. Correggi il sistema di priorità in modo che i lavori più piccoli non rimangano bloccati dietro quelli grandi. Usa BullMQ.

Autocontenuto:

Lo scheduler dei lavori (src/jobs/queue.ts) elabora i compiti in sequenza. I lavori grandi (50K+ elementi) bloccano i lavori più piccoli in coda – gli utenti con lavori piccoli aspettano 30+ minuti per l'inizio dell'elaborazione. La correzione dovrebbe aggiungere la programmazione basata sulla priorità: i lavori sotto i 5K elementi ottengono priorità più alta. La configurazione del rate limiter (100 req/s) non deve cambiare. La funzionalità di priorità BullMQ esistente dovrebbe essere usata se possibile. Se la soluzione richiede la modifica dello schema del lavoro, escalation prima di implementare.

La prima versione suona come fattibile ma nasconde domande: quale file? Cosa significa "troppo lento" in numeri? Quali sono i vincoli? L'agente farà supposizioni su tutto questo – e potrebbero essere sbagliate.

La ricerca sugli agenti di codifica lo conferma: fornire contesto architetturale, dipendenze tra file e suggerimenti di esplorazione in anticipo impedisce agli agenti di sprecare passaggi in una traversata non focalizzata del repository.

Versione marketing – sembra completa ma non lo è:

Crea una campagna di email drip per gli utenti di prova che non hanno convertito. Concentrati sul mostrare il valore del prodotto. 3 email, tono amichevole, con CTA.

Autocontenuta:

Il tasso di conversione trial-to-paid è del 12%. Il benchmark del settore è del 18%. Gli utenti che completano l'onboarding entro 72 ore convertono al 31%. Progetta una sequenza di 3 email attivata quando un utente di prova non ha completato il suo primo progetto entro il giorno 3. Obiettivo: farli completare l'onboarding. Ogni email sotto le 100 parole, una CTA per email, funziona in IT e EN. Nessuna menzione di prezzi, nessuna tattica di urgenza.

La prima versione produrrebbe una campagna drip generica. La seconda fornisce all'agente il contesto aziendale (perché è importante) e i vincoli (cosa evitare) che producono un risultato mirato.

Primitivo 2 – criteri di accettazione

Scrivi tre frasi che permettano a qualcun altro di verificare l'output senza farti domande.

Sembra testabile ma non lo è:

Il dashboard dovrebbe visualizzare accuratamente le metriche chiave e caricarsi rapidamente su tutti i browser.

Effettivamente testabile:

Il dashboard visualizza MRR, tasso di abbandono e utenti attivi per l'intervallo di date selezionato. Il MRR corrisponde al numero del team finanziario entro €100. La pagina si carica in meno di 2 secondi su una connessione standard. I grafici si renderizzano senza errori in Chrome e Firefox.

La prima versione usa parole che sembrano precise ("accuratamente", "rapidamente", "tutti i browser") ma che nessuno può verificare senza porre domande di follow-up. La seconda versione definisce numeri specifici, metriche specifiche e browser specifici.

Primitivo 3 – architettura dei vincoli

Quattro categorie. Compila tutte e quattro per ogni compito non banale.

Esempio: sistema di risposta automatica ai ticket di supporto

Categoria	Regole
Deve	Rivolgersi al cliente per nome. Fare riferimento al suo problema specifico. Includere un passo successivo.
Non deve	Non condividere mai credenziali o dettagli interni del sistema. Non promettere mai un tempo di risoluzione specifico. Non chiudere mai automaticamente un ticket.
Preferisce	Collegare articoli pertinenti della knowledge base quando esistono. Usare la lingua del cliente in base alle impostazioni del suo conto. Mantenere le risposte sotto le 200 parole.
Escalation	Il cliente menziona la cancellazione. Il problema comporta perdita di dati. Lo stesso problema riportato 3+ volte in 24 ore. Il cliente è su un piano enterprise.

Primitivo 4 – decomposizione

Suddividi i compiti in pezzi indipendenti con input e output chiari. Target: sottocompiti che richiedono ≤2 ore e che possono essere verificati da soli.

Sembra decomposto ma è ancora accoppiato:

Progetta il modello dati e costruisci l'API
Costruisci il frontend che usa l'API
Scrivi i test e distribuisci

Effettivamente indipendente:

Passaggio	Input	Output	Verifica
1. Migrazione dello schema	Schema corrente + documento dei requisiti	File di migrazione + file di rollback	La migrazione funziona avanti e indietro senza errori
2. Endpoint API	Migrazione + spec API	Route handler con validazione	Tutti i 5 casi di test passano, restituisce i codici di stato corretti
3. Form frontend	Spec API + mockup di design	Componente React con validazione del form	Il form viene inviato correttamente, gli errori di validazione vengono visualizzati correttamente
4. Test di integrazione	Tutti e tre i precedenti	Test end-to-end	L'utente può completare il flusso completo in staging

La prima versione ha dipendenze nascoste (il passaggio 1 raggruppa due preoccupazioni, il passaggio 2 non può iniziare finché il passaggio 1 non è completamente fatto, il passaggio 3 raggruppa test e distribuzione). La seconda versione ha input, output e verifica chiari ad ogni passaggio. Anthropic raccomanda questo pattern orchestratore-lavoratori per i compiti multi-componente.

Primitivo 5 – progettazione della valutazione

Costruisci 3-5 casi di test con output noti di buona qualità. Eseguili dopo ogni cambiamento.

Esempio: generatore di oggetti email

Caso di test	Input	Caratteristiche dell'output atteso
1. Email di benvenuto	Nuovo utente, iscritto oggi, nome: Maria	Contiene il nome dell'utente. Sotto i 50 caratteri. Nessuna parola che attiva i filtri spam.
2. Re-engagement	Utente inattivo da 30 giorni	Fa riferimento a un arco di tempo specifico o all'ultima attività. Crea curiosità. Non induce senso di colpa.
3. Annuncio di funzionalità	Nuova funzionalità editor, tutti gli utenti	Evidenzia il beneficio, non il nome della funzionalità. Nessun gergo tecnico.
4. Locale italiano	Uguale al #1 ma il locale utente è IT	Italiano grammaticalmente corretto. Non una traduzione parola per parola.
5. Caso limite: nessun nome	L'utente non ha nome nel sistema	Non dice "Ciao null" o "Ciao ". Usa un saluto generico.

Non testi l'output esatto (l'IA è non deterministica). Testi le caratteristiche dell'output. Questa è valutazione, non test unitario. Anthropic raccomanda di abbinare ogni prompt di valutazione con risultati verificabili e di tracciare accuratezza, runtime e tassi di errore nel tempo.

Modi di fallimento del contesto

Quando l'output dell'IA va storto, diagnostica quale fallimento del contesto l'ha causato prima di riprovare. Questi quattro modi di fallimento sono ben documentati nella letteratura sull'ingegneria del contesto:

Avvelenamento

Un errore entra nel contesto e si compone attraverso i turni. L'agente ha allucinato un nome di funzione nel passaggio 2, poi continua a chiamare quella funzione inesistente nei passaggi 3-5.

Correzione: Pulisci il contesto tra i passaggi. Non lasciare che gli output degli strumenti dei passaggi iniziali persistano in profondità nella conversazione. Riassumi ai confini invece di portare avanti la cronologia grezza.

Distrazione

Il contesto è così lungo che l'agente ripete pattern dalla cronologia invece di ragionare sul passaggio corrente. La ricerca ha osservato questo degrado dopo aver superato i 100K token.

Correzione: Comprimi o riassumi il contesto più vecchio. Quando la conversazione si allunga, crea una nuova sessione con un riepilogo delle decisioni prese finora.

Confusione

Troppi strumenti o troppa documentazione nel contesto. L'agente sceglie lo strumento sbagliato o cita documentazione irrilevante perché non riesce a distinguere cosa è rilevante.

Correzione: Riduci ciò che è caricato. Esponi solo strumenti e documenti rilevanti per il compito corrente. Come dice Anthropic: "Se un umano non può definitivamente scegliere lo strumento corretto, un agente non può fare meglio."

Conflitto

Informazioni contraddittorie nel contesto. La guida di stile dice "sii conciso" ma il template dice "includi una spiegazione dettagliata". Uno studio Microsoft/Salesforce ha mostrato un calo del 39% della qualità quando erano presenti informazioni contraddittorie.

Correzione: Controlla il tuo contesto per le contraddizioni. Quando aggiorni i file di contesto, rimuovi la vecchia guida – non aggiungere semplicemente la nuova guida accanto ad essa. Un'unica fonte di verità per argomento.

Scrivere specifiche per diversi ruoli

Specifica ingegneristica

## Problema
Lo scheduler dei lavori elabora i compiti in sequenza. I lavori grandi
(50K+ elementi) bloccano i lavori più piccoli in coda. Gli utenti con
lavori piccoli aspettano 30+ minuti per l'inizio dell'elaborazione.

## Ambito
- Modificare la coda dei lavori per supportare la programmazione basata sulla priorità
- I lavori piccoli (< 5K elementi) ottengono priorità più alta
- NON modificare i limiti di velocità di elaborazione o
  la pipeline di rendering

## Input
- Implementazione della coda dei lavori: src/jobs/queue.ts
- Modello del lavoro: src/models/job.ts
- Test attuali: src/jobs/__tests__/queue.test.ts

## Vincoli
- Deve: mantenere l'ordine FIFO all'interno dello stesso livello di priorità
- Deve: elaborare tutti i lavori entro i limiti di velocità esistenti
- Non deve: eliminare o riordinare i lavori già in corso
- Non deve: richiedere una migrazione del database
- Preferisce: usare la funzionalità di priorità BullMQ esistente
- Escalation: se la soluzione richiede la modifica dello schema del lavoro

## Criteri di accettazione
1. Un lavoro da 1K elementi accodato dopo un lavoro da 100K inizia
   l'elaborazione entro 5 minuti, non 30+
2. Nessun lavoro viene privato di risorse – tutti i lavori completano
   entro 2x la loro durata prevista
3. I test esistenti passano senza modifiche
4. Nuovi test coprono l'ordinamento per priorità e la prevenzione
   della privazione di risorse

## Condizioni di fallimento
- Qualsiasi lavoro elaborato con input errati
- Qualsiasi lavoro elaborato due volte
- Deadlock della coda sotto invii concorrenti

## Test di successo
1. Accoda 3 lavori: 100K, 1K, 500. Verifica che 1K e 500
   inizino prima che 100K completi.
2. Accoda 20 lavori piccoli e 1 grande. Verifica che tutti completino.
3. Invia lavori concorrentemente da 3 client API.
   Verifica nessun duplicato o lavoro perso.

Specifica marketing

## Problema
Il tasso di conversione trial-to-paid è del 12%. Il benchmark del
settore è del 18%. Gli utenti che completano l'onboarding entro
72 ore convertono al 31%. La maggior parte degli utenti di prova
non completa mai l'onboarding.

## Ambito
Progetta una sequenza di 3 email di onboarding attivata quando un
utente di prova non ha completato il suo primo progetto entro il
giorno 3. Obiettivo: farli completare l'onboarding. Questo è solo
il contenuto dell'email – il trigger di automazione esiste già.

## Input
- Email di benvenuto attuale (allegata)
- Top 3 template per utilizzo (allegati)
- Guida alla voce del brand: amichevole, competente, mai aziendale
- Prodotto: editor visuale, libreria di template, gestione dei progetti

## Vincoli
- Deve: ogni email sotto le 100 parole
- Deve: una CTA chiara per email
- Deve: funzionare in IT e EN
- Non deve: menzionare prezzi o limitazioni del piano
- Non deve: usare tattiche di urgenza ("la tua prova sta scadendo!")
- Preferisce: mostrare, non dire (link a un template, non a una
  lista di funzionalità)
- Escalation: se la sequenza ha bisogno di più di 3 email

## Criteri di accettazione
1. Ogni email ha esattamente una CTA che rimanda a un'azione
   specifica nel prodotto
2. Il tono corrisponde alla guida alla voce del brand
3. Nessuna email supera le 100 parole
4. Le righe dell'oggetto sono sotto i 50 caratteri
5. Un non-cliente può capire la proposta di valore
   senza conoscenza precedente del prodotto

## Condizioni di fallimento
- Qualsiasi email supera le 100 parole
- La CTA rimanda a una pagina generica invece di un'azione specifica
- Appare linguaggio di urgenza ("tempo limitato", "in scadenza",
  "ultima possibilità")
- La versione italiana è una traduzione letterale piuttosto che
  prosa naturale

## Test di successo
1. Leggi l'email 1 a freddo. Riesci a identificare cosa fa il prodotto
   e quale azione intraprendere? (sì/no)
2. Leggi tutte e 3 in sequenza. La progressione sembra
   naturale, non ripetitiva? (sì/no)
3. Le versioni italiane si leggono naturalmente, non come traduzioni.
   (verificato da madrelingua)

Specifica supporto

## Problema
Il tempo medio di risposta al supporto è di 6 ore. Il 40% dei
ticket sono domande già risposte nella knowledge base. Gli agenti
trascorrono tempo a cercare risposte che già esistono.

## Ambito
Costruisci un sistema di risposta bozza assistito dall'IA. Quando
arriva un ticket, il sistema cerca nella knowledge base e redige
una risposta che l'agente di supporto esamina e invia.
L'agente esamina sempre prima di inviare – nessuna risposta automatica.

## Input
- Articoli della knowledge base (~200 articoli)
- Cronologia dei ticket (ultimi 90 giorni, anonimizzata)
- Dati del conto cliente (tipo di piano, durata, attività recente)
- Template di risposta predefiniti (32 template)

## Vincoli
- Deve: un umano esamina ogni risposta prima dell'invio
- Deve: citare l'articolo della knowledge base usato
- Deve: segnalare quando non esiste un articolo rilevante
  (segnale per crearne uno)
- Non deve: accedere ai dati dei clienti da altri conti
- Non deve: promettere tempi di risoluzione
- Non deve: chiudere automaticamente i ticket
- Preferisce: corrispondere alla lingua del cliente
- Preferisce: mantenere le bozze sotto le 200 parole
- Escalation: dispute di fatturazione oltre €500, menzioni di
  cancellazione, problemi di perdita di dati

## Criteri di accettazione
1. Le bozze vengono generate entro 30 secondi dalla creazione del ticket
2. Il 70%+ delle bozze richiede meno del 20% di modifica
3. Gli articoli della knowledge base citati sono rilevanti alla domanda
4. Gli agenti possono ignorare o scartare qualsiasi bozza con un clic

## Condizioni di fallimento
- Risposta inviata senza revisione umana
- Dati del conto A appaiono nella risposta del conto B
- La bozza cita un articolo KB obsoleto o errato
- Il sistema genera una bozza per un ticket che dovrebbe escalare

## Test di successo
1. "Come imposto i domini personalizzati?" → La bozza fa riferimento
   all'articolo KB sulla configurazione del dominio con istruzioni corrette
2. "Sono stato addebitato due volte" → La bozza segnala per escalation,
   non tenta di risolvere la fatturazione
3. Domanda in italiano → La bozza è in italiano,
   fa riferimento ai passaggi di risoluzione dei problemi rilevanti
4. Input incomprensibile → Il sistema segnala come poco chiaro,
   non genera una bozza

Il ciclo di miglioramento delle specifiche

Una specifica non è mai finita al primo tentativo. Usa il modello di responsabilità per i fallimenti:

Scrivi la specifica usando i cinque primitivi
Eseguila – lascia che l'agente esegua
Valuta l'output rispetto ai tuoi criteri di accettazione
Diagnostica i fallimenti per livello:

Cosa è andato storto	Quale livello correggere
L'output è sbagliato o di bassa qualità	Livello 1 – migliora il prompt
L'output ignora la conoscenza del dominio	Livello 2 – migliora il contesto
L'output ottimizza la cosa sbagliata	Livello 3 – chiarisci l'intento
L'output è incompleto o manca dei requisiti	Livello 4 – stringe la specifica

Correggi un livello alla volta. Non cambiare mai più livelli contemporaneamente – non saprai cosa ha funzionato.
Aggiorna la specifica con ciò che hai imparato. Le migliori specifiche sono scritte da persone che hanno visto fallire gli agenti.

Questo approccio iterativo si allinea con la raccomandazione di Anthropic di "iniziare in modo minimale con il miglior modello, poi aggiungere iterativamente istruzioni basate sulle modalità di fallimento osservate."

Errori comuni

Sovra-specificare. Una specifica che descrive ogni dettaglio di implementazione è solo pseudocodice. Specifica il cosa e i vincoli, non il come. Lascia che l'agente scelga l'approccio entro i tuoi limiti.

Sotto-specificare. "Miglioralo" non è una specifica. Se non riesci a descrivere "fatto", non sei pronto a delegare.

Dump del contesto. Caricare ogni documento che hai nel contesto "nel caso fosse utile". Le informazioni irrilevanti peggiorano attivamente l'output. Il principio fondamentale di Anthropic: trova il più piccolo insieme di token ad alto segnale, non il maggior numero di token.

Ottimizzare i prompt quando il problema è il contesto. Se l'agente continua a produrre output irrilevante, aggiungere "sii più rilevante" al prompt non aiuterà. L'agente ha bisogno di informazioni diverse, non di istruzioni migliori. Usa il modello di responsabilità per i fallimenti per diagnosticare il livello giusto.

Saltare la progettazione della valutazione. Senza casi di test, ti affidi all'intuito per giudicare la qualità dell'output. Costruisci prima i casi di test – ti forzano a chiarire cosa vuoi davvero.

Riprovare invece di diagnosticare. Quando l'output fallisce, l'istinto è di rigenerare. Fermati. Scopri quale livello ha causato il fallimento. Correggi quel livello. Poi riprova.

Riferimento rapido

Prima di delegare, conferma:

Posso descrivere il problema senza fare riferimento a cose che l'agente non conosce
Posso scrivere tre frasi che verificano il successo
Ho elencato cosa deve accadere, cosa non deve accadere e quando fermarsi e chiedere
Ho suddiviso il compito in pezzi abbastanza piccoli da verificare indipendentemente
Ho casi di test con caratteristiche note di buona qualità

Quando l'output fallisce, diagnostica:

Sintomo	Causa probabile	Azione
L'output è sbagliato	Prompt	Migliorare le istruzioni, aggiungere esempi
L'output ignora il tuo dominio	Contesto	Aggiungere o aggiornare il file di contesto
L'output ottimizza la cosa sbagliata	Intento	Definire la gerarchia degli obiettivi e i compromessi
L'output è incompleto	Specifica	Aggiungere requisiti mancanti, restringere l'ambito

Ulteriori letture

Building Effective Agents – Guida di Anthropic ai pattern di architettura degli agenti
Effective Context Engineering for AI Agents – Gestire lo stato completo dei token attraverso i loop degli agenti
Writing Tools for Agents – Principi di progettazione degli strumenti e metodologia di valutazione
Context Engineering for Agents – Framework delle quattro operazioni di LangChain (Write, Select, Compress, Isolate)
A Survey of Context Engineering for LLMs – Survey accademica che stabilisce una tassonomia formale
CodeScout: Contextual Problem Statement Enhancement – Ricerca che mostra il miglioramento del 20% da specifiche migliori in anticipo

← Torna alla home · Standard di Esecuzione · Il quadro di riferimento · Glossario