Dove dovrebbe essere applicata la correzione?
Se si associa a ciascun caso di attrito dell’agente la sua causa principale, si individua il livello (memoria, documentazione, processo o a monte) in cui va applicata la soluzione definitiva.
Due squadre, lo stesso attrito, un quarto diverso
Entrambe le squadre iniziano a registrare le difficoltà incontrate dai propri agenti IA: le richieste ambigue, la documentazione obsoleta, gli strumenti inaffidabili, le esecuzioni ripetute.
Il primo team risolve ogni problema al livello più immediato. Ogni fastidio ricorrente diventa una modifica istantanea o una nota di promemoria; qualsiasi questione più complessa diventa un altro paragrafo nel file di contesto. Tre mesi dopo, i loro agenti operano sulla base di istruzioni gonfiate che nessuno legge dall’inizio alla fine, e gli attriti che contavano davvero (il modello di brief che lascia indefinito l’ambito di intervento, l’account pubblicitario la cui struttura ostacola ogni sessione) sono ancora presenti, poiché nessuna modifica immediata può risolverli.
Il secondo team pone una domanda in più per ogni modello: a quale ambito appartiene effettivamente questa correzione? Il cluster “gli agenti continuano a cercare di indovinare il nostro pubblico” si trasforma in una modifica alle modalità di definizione del lavoro: una correzione di processo, concordata durante una riunione di team. Il cluster relativo al «manuale operativo obsoleto» si traduce in una modifica alla documentazione, con un responsabile designato. L’anomalia isolata diventa una semplice nota di promemoria e nulla più. Tre mesi dopo, i loro file di istruzioni sono più concisi rispetto a quando hanno iniziato e le categorie di attrito che hanno risolto mostrano una tendenza al ribasso.
La differenza non sta nella disciplina di registrazione. Entrambe le squadre hanno effettuato le registrazioni. La differenza sta in una questione di percorso che la prima squadra non si è mai posta.
La mossa chiave: i punti di attrito in quota
Quando una sessione assistita dall’intelligenza artificiale incontra delle difficoltà, la causa principale rimanda a un livello in cui risiede la soluzione duratura. La chiamiamo altitudine della soluzione; le altitudini disponibili vanno da quelle effimere a quelle strutturali:
memoria → competenza/suggerimento → ambiente e configurazione → documentazione → il materiale di lavoro stesso → processo/flusso di lavoro → prodotto o fornitore a monte
Indicare con precisione il problema trasforma una lamentela in una correzione definibile. «L’agente ha sbagliato di nuovo la strategia di offerta» è una lamentela. «La decisione relativa alla strategia di offerta non è mai stata messa per iscritto in alcun luogo in cui l’agente potesse trovarla: si tratta di una correzione alla documentazione, ed ecco il runbook in cui va inserita» è un’attività da svolgere con un riferimento preciso.
Una valutazione errata dell’ambito comporta due tipi di problemi. Il targeting insufficiente, una nota personale che in realtà sostituisce un documento di team mancante, comporta il ripetersi di attriti per tutti tranne che per voi: un costo di ripetizione a carico del resto del team. L’eccesso di definizione degli obiettivi (una nuova competenza per un’attività una tantum, un altro paragrafo in un file di contesto già gonfiato) rappresenta un onere di manutenzione per l’artefatto; il settore ha definito con precisione questi anti-modelli: proliferazione delle competenze (da 16 a 48 competenze in 15 giorni: “Aggiungere competenze è facile. … La gestione è la parte difficile.”) e il gonfiamento del file di contesto (“un file di memoria che ha smesso di essere letto”, secondo questa nota di settore). I fornitori hanno convergito sullo stesso gradiente partendo dall’altra estremità: ridimensionare la memoria effimera, promuovere l’apprendimento duraturo nel controllo di versione: Windsurf/Devin («scrivetelo come Regola o aggiungetelo a AGENTS.md… piuttosto che affidarvi a Memorie generate automaticamente», documentazione), OpenAI Codex («quando Codex commette lo stesso errore due volte, chiedetegli un’analisi retrospettiva e aggiornate AGENTS.md», migliori pratiche), la scadenza deliberata di 28 giorni della memoria di Copilot.
Pertanto, il settore conosce entrambe le modalità di guasto. Ciò che mancava era uno strumento di instradamento.
Un vocabolario fisso che indirizza
La nostra proposta operativa: associare a ogni problema di attrito esattamente una causa principale, scelta da un vocabolario prestabilito composto da dieci etichette suddivise in cinque gruppi: sufficientemente snello da poter essere memorizzato facilmente, incentrato sulle cause piuttosto che sui sintomi e volutamente indipendente dagli strumenti e dalle discipline:
- Briefing:
ambiguous-instruction,missing-context,incorrect-context,changed-requirements - Documentazione:
missing-documentation,incorrect-documentation - Materiale di lavoro:
work-material-friction - Attrezzatura:
missing-access-or-tool,environment-friction - Agente:
agent-error
Il gruppo costituisce la chiave di instradamento. Nel momento in cui un risultato viene etichettato, il suo instradamento è già a metà:
| Dominante del gruppo | La correzione si trova solitamente in | Artefatti tipici |
|---|---|---|
| Briefing | processo (le modalità di assegnazione dei compiti) o una memoria persistente | modello di sintesi, lista di controllo per l’avvio del progetto, archivio di riferimento |
| Documentazione | documenti | README, runbook/SOP, file di contesto, specifiche |
| Materiale di lavoro | il materiale stesso | codice: la riorganizzazione a cui il fattore di attrito continua a fare riferimento; non codice: la riorganizzazione dell’account, della bacheca o del modello |
| Attrezzature | environment/config oppure a monte | impostazioni, configurazione MCP, autorizzazione di accesso, ticket del fornitore |
| Agente | segnale, abilità o misura di sicurezza | modifica abilità, hook, eval |
Una precisazione di fondo: i gruppi prendono il nome dalle loro destinazioni fisse, quindi l’affermazione secondo cui «l’etichetta determina in parte il percorso» è vera per definizione, essendo una scelta progettuale piuttosto che una scoperta empirica. L’affermazione empirica sottesa è che le etichette relative al momento dell’acquisizione siano accurate e coerenti, che è esattamente ciò che non abbiamo ancora misurato (maggiori dettagli di seguito).
Prestino attenzione a ciò che questo termine comprendework-material-friction, poiché è proprio in questo ambito che il vocabolario giustifica la sua pretesa di essere indipendente dalla disciplina. Nel codice, si tratta del “debito tecnico”: quel modulo su cui ogni sessione inciampa. Al di fuori del codice, è altrettanto reale. Immaginate un team di marketing il cui agente esamina un account Google Ads cresciuto per accumulo: tre generazioni di convenzioni di denominazione, campagne sospese che nessuno osa eliminare, parole chiave duplicate in gruppi di annunci sovrapposti. Ad ogni sessione, l’addetto impiega i primi minuti a ricostruire a quale campagna appartenga cosa, e ogni raccomandazione è accompagnata da un’avvertenza. Nessuna soluzione immediata risolve il problema; nessuna nota di promemoria lo risolve per la persona successiva. L’etichetta è work-material-friction, sempre abbinata al materiale concreto denominato (questo account), e l’altitudine è il materiale stesso: la ristrutturazione verso cui l’attrito continua a puntare. Lo stesso schema si ritrova in fogli di calcolo intricati, nel caos dei modelli CMS e nelle librerie di macro di supporto; un ciclo modellato sull’agente di programmazione non ha dove collocare tutto ciò.
Perché “fissa” anziché “emergente”? Perché, per un team, la tassonomia è uno strumento di coordinamento, non un esercizio di classificazione. «Lo stesso attrito riscontrato in otto sessioni costituisce un problema di processo» ha senso solo se tutte e otto le sessioni lo hanno etichettato allo stesso modo; le affermazioni relative alla distribuzione necessitano di un denominatore stabile; e le linee di tendenza («l’attrito nei briefing è diminuito da quando abbiamo standardizzato il modello di briefing?») hanno senso solo se un’etichetta ha lo stesso significato sia a marzo che a luglio. Le categorie emergenti, in cui ogni persona assegna le proprie etichette, sono la scelta giusta se si opera da soli, ma all’interno di un team tendono a divergere da persona a persona, e nulla si aggrega senza una fase di riconciliazione di cui nessuno si assume la responsabilità. Manteniamo attivo il motore delle categorie emergenti in due modi: una nota che cita le prove a sostegno sotto ogni etichetta e una revisione periodica del vocabolario in cui le note accumulate mettono alla prova le etichette. Il vocabolario è soggetto a versioni; è progettato per cambiare alla luce delle prove, non per essere difeso.
Ciò che già esiste, messo a confronto in modo obiettivo
Non siamo stati noi a inventare le tassonomie del fallimento, e quelle esistenti sono efficaci per lo scopo a cui sono destinate.
MAST (arXiv 2503.13657) è la tassonomia fissa di riferimento: 14 modalità di fallimento suddivise in 3 categorie, ricavate da 150 tracciati esaminati da esperti e convalidate su un corpus di oltre 1600 casi, con un elevato grado di concordanza tra gli annotatori (κ = 0,88). Essa classifica le modalità di guasto dei sistemi multi-agente; è stata sviluppata a fini di ricerca e benchmarking, ed è la più affine alla nostra per disciplina, pur differendo per oggetto: noi classifichiamo invece le cause dell’attrito insorto nella collaborazione tra esseri umani e agenti.
La scuola dell’analisi degli errori, la metodologia di valutazione di Husain e Shankar (FAQ sulle valutazioni, gennaio 2026), sostiene l’opposto di un elenco fisso: le categorie «dovrebbero emergere dai modelli di errore osservati… non da classificazioni predeterminate delle query», e la lettura aperta delle proprie tracce è «l’attività più importante nelle valutazioni».” Riteniamo che abbiano ragione a livello individuale e che la situazione si ribalti a livello di squadra, per i motivi di aggregazione sopra indicati. La loro disciplina di lettura è comunque fondamentale nella nostra proposta; è ciò che rappresentano le note di evidenza.
Intorno a questi poli: la tassonomia a quattro livelli (Greyling, maggio 2026) classifica quale livello dello stack abbia fallito, attribuendo solo circa il 9,9% dei fallimenti al ragionamento del modello: la maggior parte dei fallimenti è costituita da problemi relativi all’harness (l’harness è l’impalcatura che circonda il modello), motivo per cui la nostra etichettaagent-error è di natura residuale, utilizzata solo quando gli input erano adeguati (la scuola di ingegneria dell’harness rifiuta esplicitamente l’attribuzione predefinita della colpa all’agente, correggendo l’harness anziché l’agente: Osmani, Agent Harness Engineering). TraceProbe classifica le azioni di gestione degli errori nelle tracce. Garg’s Feedback Flywheel raccoglie quattro tipi di segnali negli artefatti di team, il framework in cui si inserisce il nostro: il suo contesto ≈ i nostri gruppi di briefing + documentazione; il suo ramo dedicato ai guasti è ciò che la nostra tassonomia scompone. Factory Signals classifica i sintomi delle sessioni in ticket archiviati automaticamente; Braintrust Topics rappresenta il prodotto derivante da questa scuola emergente, che raggruppa nuovamente le vostre tracce su base giornaliera.
Due interpretazioni obiettive di tale confronto. In primo luogo, la maggior parte di queste classificazioni riguarda sintomi, livelli o destinazioni; la nostra classifica le cause, ed è proprio questo che rende l’etichetta una chiave di instradamento, e costituisce l’effettivo elemento di novità, per così dire. In secondo luogo, e cosa ancora più importante: MAST ha misurato l’affidabilità dell’assegnazione delle etichette, mentre noi non l’abbiamo fatto. L’affidabilità inter-valutatore sulle nostre dieci etichette non è stata misurata, e noi consideriamo questo aspetto un prerequisito, non una nota a margine: l’esperimento (valutatori indipendenti che assegnano etichette in cieco alle stesse voci reali, con la concordanza riportata qualunque sia il risultato) è in corso sulle voci provenienti dalla nostra stessa prova dal vivo, con il κ = 0,88 di MAST come parametro di riferimento. Fino a quando non verranno resi noti i risultati, questa tassonomia è una proposta di lavoro con etichette versionate, non uno strumento convalidato. Preferiamo comunicarvelo noi piuttosto che lasciarvi scoprirlo da soli.
Sosteniamo inoltre tutti i loop già in esecuzione: Loop Engineering, Compound Engineering, agent-retro, le retrospettive AGENTS.md, i sistemi di memoria dei fornitori e i rapporti automatici sulle sessioni. Manteneteli tutti; nulla di quanto qui esposto li sostituisce.
Perché l’altitudine è una questione che riguarda tutta la squadra
Ecco il punto in comune tra i cicli esistenti: quasi tutti sono “in solitaria” (un singolo sviluppatore e il suo agente, oppure un singolo fornitore e la sua flotta). E i dati stessi del settore indicano che la fase costosa non è quella del monitoraggio: circa il 90% dei team strumenta le tracce degli agenti, ma solo circa il 37–52% le valuta sistematicamente (LangChain State of Agent Engineering, giugno 2026). Il livello ancora non sfruttato è la sintesi a livello di team, ed è proprio qui che la visione d’insieme inizia ad assumere importanza, per due ragioni.
L’aggregazione ridefinisce le priorità. Un fastidio di dieci minuti per una persona è solo rumore di fondo; nessuno lo risolve razionalmente. La stessa etichetta, se presente in otto sessioni e attribuita a cinque persone, rappresenta uno dei costi maggiori per il team, e solo la visione aggregata permette di individuarlo. L’aggregazione è anche il risultato del vocabolario standardizzato: i conteggi hanno senso solo se tutti utilizzano le stesse etichette.
I livelli più elevati sono di competenza del team. Un singolo individuo può definire autonomamente la propria memoria, i propri prompt e le proprie impostazioni. Tuttavia, le modifiche ai processi, le valutazioni trasversali tra strumenti, il budget destinato agli strumenti, le escalation a livelli superiori – ovvero quei livelli in cui solitamente si concentrano i maggiori attriti ricorrenti – sono decisioni che nessun individuo può prendere da solo. Questo è anche il motivo per cui riteniamo che il ruolo umano nella sintesi permanga, indipendentemente da quanto siano validi i modelli: le correzioni si concretizzano in elementi di cui gli esseri umani sono responsabili e per i quali rispondono: brief, processi, budget, accordi di team. Si tratta di un’affermazione relativa all’autorità organizzativa, non alla capacità dei modelli. Si tratta di un ruolo all’interno del ciclo decisionale, non di un punto di controllo nella pipeline: gli agenti dovrebbero rilevare, registrare, raggruppare e redigere liberamente; gli esseri umani aggiungono il giudizio orientativo e si assumono la responsabilità.
Se il vostro team organizza già una sessione dedicata al miglioramento continuo, questa si inserisce perfettamente in tale contesto: viene presentato il quadro complessivo degli attriti, il team si chiede «dove si colloca ciascuna correzione?», e ogni modello viene associato a un’altitudine e a un responsabile. Non si tratta di un nuovo rituale, ma semplicemente di una retrospettiva con input migliori. Gli ingegneri di ML la definiscono «analisi degli errori»; i team chiamano questa sessione «retro».
Cosa potrebbe farci cambiare idea?
Trattandosi di un documento di discussione, ecco gli aspetti sui quali nutriamo sinceri dubbi:
- Affidabilità. Se l’esperimento inter-valutatore evidenzia una scarsa concordanza, le regole di delimitazione (o le etichette stesse) sono errate e provvederemo a rivederle nell’ambito del numero di versione, anziché difenderle.
- Dimensione. Il numero di etichette (dieci) è ereditato, non derivato. MAST ne utilizza 14; Four-Layer ne utilizza 4. La nostra distribuzione delle etichette dopo un quarto delle voci effettive costituisce la prova che conferma o modifica tale numero.
- Modalità mancanti. Gli attriti tra agenti (perdita di passaggio tra sottoagenti, errori di orchestrazione) sono attualmente classificati sotto
environment-friction; eventuali casi reali potrebbero richiedere una categoria a sé stante. - Ambito delle revisioni non relative al codice. Definiamo l’ambito delle revisioni in base alla destinazione delle correzioni: il repository per la maggior parte del lavoro di sviluppo; “account”, “area di lavoro” o “incarico” al di fuori di esso. Tali confini non relativi al codice sono proposte che desideriamo vengano testate con team reali.
- Fattibilità in tempo reale. I team molto impegnati sono in grado di attribuire le cause sul momento, oppure tale attribuzione deve avvenire in fase di revisione? I team che provassero a farlo chiarirebbero la questione più rapidamente di quanto potremmo fare noi con le nostre teorie.
Se eseguite una qualsiasi versione di questo ciclo (categorie emergenti, una pipeline di fornitori, un semplice foglio di calcolo), vorremmo sapere in quale punto la tabella di instradamento presenta delle anomalie. In particolare, se potete mostrarci un modello di attrito che non indichi affatto un’altitudine: ai-discussion@teamretro.com.
Capitolo successivo: Il rapporto esiste. La stanza no.: perché l’assegnazione delle correzioni è una decisione di squadra e cosa fa il team quando arriva il rapporto sui conflitti. Parte della guida alle retrospettive degli agenti di intelligenza artificiale.