Dove dovrebbe essere applicata la correzione?

Due squadre, lo stesso attrito, un quarto diverso

Entrambe le squadre iniziano a registrare gli ostacoli che i loro agenti di intelligenza artificiale incontrano: le richieste ambigue, la documentazione obsoleta, gli strumenti inaffidabili, le ripetizioni delle operazioni.

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 (il modello di brief che lascia indefinito l’ambito, 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 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. La «stranezza isolata» diventa una semplice nota di promemoria e nulla più. Tre mesi dopo, i loro file di istruzioni sono più concisi rispetto all’inizio 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 un ostacolo, 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

Identificare il problema trasforma una lamentela in una soluzione individuabile. «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 un 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.

Errare la valutazione comporta due conseguenze negative. Il sottotargeting, ovvero una nota personale che sostituisce di fatto un documento di team mancante, comporta il ripetersi dell’attrito per tutti tranne che per voi: un “costo di ricorrenza” a carico del resto del team. Le note già rimaste isolate in questo modo possono essere recuperate attraverso una raccolta di informazioni all’interno del team. **Obiettivo eccessivo (una nuova competenza per un caso isolato, 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 campo). 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 una retrospettiva e aggiornate AGENTS.md», best practice), 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 fisso composto da dieci etichette suddivise in cinque gruppi: sufficientemente snello da poter essere memorizzato, 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
• Attrezzature: 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 nel 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 “friction” 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 sottostante è che le etichette relative al momento dell’acquisizione siano accurate e coerenti, che è esattamente ciò che non abbiamo ancora misurato (maggiori dettagli di seguito).

La tabella assegna a una correzione il suo primo indirizzo, e la ricorrenza può spostarla. Quando il problema si ripresenta dopo una correzione apportata alla documentazione o al file di contesto, è probabile che il testo non funzioni correttamente. Spostate la correzione in un «paracadute»: un hook o un controllo CI, che la mantenga indipendentemente dal fatto che qualcuno la legga o meno. È lo stesso ragionamento che sta alla base della scelta di un trigger di acquisizione: una regola convenzionale dipende dal fatto che qualcuno se ne ricordi, mentre un hook no.

Prestate attenzione a ciò che questo concetto 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 avvertimento. Nessuna soluzione immediata risolve il problema; nessuna nota di promemoria lo risolve per chi verrà dopo. L’etichetta è work-material-friction, sempre abbinata al materiale concreto a cui si riferisce (questo account), e l’altitudine è il materiale stesso: la ristrutturazione verso cui l’attrito continua a indicare. 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 la propria etichetta, sono la scelta giusta se considerate singolarmente, 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 fa carico. Manteniamo attivo il meccanismo di emergere in due punti: una nota che cita le prove 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, un confronto onesto

Non siamo stati noi a inventare le tassonomie del fallimento, e quelle esistenti svolgono egregiamente la loro funzione.

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 per la ricerca e il benchmarking, è la più affine alla nostra per disciplina, ma si differenzia per oggetto: noi classifichiamo le cause degli attriti nella collaborazione tra esseri umani e agenti.

La scuola di 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 dell’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’impostazione predefinita che attribuisce la colpa all’agente, preferendo correggere l’harness piuttosto che l’agente: Osmani, Agent Harness Engineering). TraceProbe classifica le azioni di gestione degli errori nelle tracce. Il Feedback Flywheel di Garg raccoglie quattro tipi di segnali in artefatti di team, il framework in cui si inserisce il nostro: il suo contesto ≈ i nostri gruppi di briefing + documentazione; il suo «braccio dei guasti» è ciò che la nostra tassonomia scompone. Factory Signals classifica i sintomi delle sessioni in ticket archiviati automaticamente; Braintrust Topics è il prodotto derivato da questa scuola emergente, che raggruppa nuovamente le vostre tracce ogni giorno.

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 rappresenta l’effettiva novità, per così dire. In secondo luogo, e cosa ancora più importante: MAST ha misurato l’affidabilità dell’etichettatura, mentre noi non l’abbiamo fatto. L’affidabilità inter-valutatore sulle nostre dieci etichette non è stata misurata, e noi la consideriamo un prerequisito, non una nota a margine: l’esperimento (valutatori indipendenti che assegnano etichette in cieco alle stesse voci reali, con la concordanza riportata così com’è) è 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 riportati i risultati, questa tassonomia è una proposta di lavoro con etichette versionate, non uno strumento convalidato. Preferiamo comunicarvelo noi piuttosto che lo scopriate da soli.

Sosteniamo inoltre tutti i loop già in funzione: Loop Engineering, Compound Engineering, agent-retro, le retrospettive di AGENTS.md, i sistemi di memoria dei fornitori e i report automatici delle sessioni. Manteneteli tutti; nulla di quanto qui descritto 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 del settore stesso indicano che la fase più costosa non è il monitoraggio: circa il 90% dei team implementa il tracciamento degli agenti, ma solo circa il 37–52% li valuta sistematicamente (LangChain State of Agent Engineering, giugno 2026). Il livello non ancora sfruttato è la sintesi a livello di team, ed è proprio qui che la visione d’insieme inizia a fare la differenza, per due motivi.

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 ripetuta in otto sessioni e da 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ù alti 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 dell’intervento umano nella sintesi rimanga irrinunciabile, per quanto avanzati possano diventare i modelli: le soluzioni si concretizzano in artefatti 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 alle capacità del modello. 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 sull’orientamento e si assumono la responsabilità.

Anche l’analisi trasversale tra persone e repository mette in luce lezioni che si contraddicono a vicenda. Sostituire anziché sovrascrivere: la nuova lezione viene inserita come voce datata che fa riferimento a quella precedente, e quest’ultima rimane leggibile, in modo che nessuno possa in seguito ricominciare a dedurre erroneamente la convinzione errata. Per scegliere tra le due, verifichi innanzitutto la provenienza (le prove di prima mano prevalgono su una lezione che è stata solo ripetuta), poi la data di pubblicazione, controllando i timestamp effettivi. Se nessuno dei due criteri è determinante, contrassegni la coppia come irrisolta anziché imporre un vincitore. Verifichi anche l’ambito di applicazione. Uno dei nostri repository conteneva una regola secondo cui non si doveva mai creare un collegamento simbolico a un worktreenode_modules; un altro affermava che era necessario crearlo, altrimenti la compilazione falliva. Ciascuna era vera nel proprio repository. Una soluzione condivisa in seguito, ovvero una copia con collegamento fisico, ha funzionato in entrambi, pertanto la regola relativa al collegamento simbolico è stata sostituita.

Se il Suo team organizza già una sessione dedicata al miglioramento continuo, questa si inserisce perfettamente in tale contesto: viene presentato il quadro d’insieme degli attriti, il team si chiede «dove si colloca ciascuna soluzione?», e ogni modello viene assegnato a un livello di priorità e a un responsabile. Non si tratta di un nuovo rituale, ma semplicemente di una retrospettiva con input migliori. Gli ingegneri di ML chiamano questa analisi «analisi degli errori di lettura»; i team definiscono questa sessione «retro».

Cosa potrebbe farci cambiare idea?

Trattandosi di un documento di discussione, ecco gli aspetti sui quali nutriamo effettivamente dei dubbi:

• Affidabilità. Se l’esperimento di 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 pari a 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 la conferma o la modifica.
• 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 “progetto” 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 risolverebbero la questione più rapidamente di quanto potremmo fare noi con le nostre teorie.

Se utilizzate 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.