Come si presenta un buon record di attrito

Perché i documenti e non i ricordi?

L’attrito che si verifica in una singola sessione è solo rumore. Lo stesso attrito che si ripete nell’arco di otto sessioni costituisce invece un modello che il vostro team può correggere, ma solo se quelle otto sessioni hanno lasciato tracce che potete effettivamente esaminare insieme: coerenti (stesso schema, in modo da essere comparabili) e attendibili (osservazioni supportate da prove concrete, non da impressioni soggettive).

Nessuna delle due cose avviene per impostazione predefinita. Il momento in cui si verifica un attrito è proprio quello in cui si dispone del massimo di informazioni al riguardo: l’esatta riga obsoleta nel runbook, l’esatto parametro che le istruzioni avevano lasciato in sospeso. Tali informazioni si esauriscono rapidamente. L’agente normalizza la propria soluzione alternativa nel giro di pochi cicli e, al termine della sessione, il segnale scompare a meno che non sia stato messo per iscritto; qualunque cosa un subagente riesca a capire «svanisce nel momento stesso in cui viene restituita» (Hindsight, maggio 2026). Il presente capitolo verte proprio sulla messa per iscritto.

Come si percepisce l’attrito

Prima che qualcosa possa essere registrato, deve essere notato. Quattro canali, e ciascuno di essi vede cose diverse:

L’agente si rende conto di trovarsi in difficoltà. Cicli di riprova, backtracking, rilettura dello stesso file o nuova interrogazione della stessa vista analitica, un’ipotesi imposta da una lacuna nelle istruzioni. Le piattaforme di produzione hanno sostanzialmente convergito su questo elenco di segnali comportamentali (Factory Signals, gennaio 2026). Il canale più economico, con due limiti evidenti: è cieco nei confronti di ciò che è assente (si avverte un ciclo di riprova; un documento che non è mai esistito non produce alcun segnale) e l’auto-osservazione supera l’autodiagnosi: i modelli individuano con scarsa efficacia i propri errori agenziali anche su tracce curate (~11%, TRAIL). Pertanto, il compito durante la sessione consiste nell’osservare i sintomi e citare le prove, mantenendo la diagnosi in via indicativa.

Un secondo agente esamina la trascrizione. Un revisore che non ha seguito il caso individua ciò che l’agente incaricato aveva considerato normale. È un approccio più obiettivo; richiede un secondo passaggio e comporta a sua volta errori di valutazione.

Un operatore umano corregge l’agente. Il sensore dominante rimane sempre lo stesso: uno studio di produzione della durata di 8 settimane ha rilevato che circa il 70% dei guasti silenziosi degli agenti è stato individuato per la prima volta da una persona che ha notato qualcosa di anomalo, e non tramite test unitari, controlli di integrità o audit di governance (arXiv 2606.14589). Ogni correzione (un «no, intendevo dire…» da parte di un revisore, una parte interessata che spiega nuovamente le indicazioni nel corso di un audit) indica esattamente il punto in cui il contesto si è discostato dall’intento, e l’agente è in grado di coglierlo sul momento senza alcun costo di processo aggiuntivo.

Telemetria. Tassi di errore degli strumenti, rifiuti di autorizzazioni, conteggi dei cicli, durate prolungate. Automatica e imparziale, ma superficiale: rileva che qualcosa è accaduto, ma non perché.

Le configurazioni più efficaci si basano su un approccio triangolare: la telemetria indica dove cercare, una fase di revisione spiega perché e la correzione manuale colma quella categoria di problemi che nessun segnale automatico è in grado di individuare. Qualunque sia la combinazione utilizzata, il risultato finale dovrebbe essere sempre lo stesso: un record.

Cosa spinge l’agente a registrarlo?

Un agente non registrerà un attrito che nessuno gli ha indicato di cercare. La maggior parte degli attriti non viene registrata non perché non sia stata notata, ma perché nulla ha innescato la registrazione. Quattro meccanismi, che differiscono principalmente per ciò che ne garantisce l’attivazione:

• Una competenza: una procedura scritta e soggetta a versionamento che l’agente esegue al termine della sessione. Contiene lo schema e le regole di onestà, in modo che ciò che viene attivato sia coerente: la stessa procedura funziona sia in caso di rifattorizzazione che di revisione di un account pubblicitario. Punto debole: l’attivazione è probabilistica; può non verificarsi mai senza alcun avviso.
• Un hook: è l’imbracatura stessa a innescare o a segnalare (un’iniezione all’inizio della sessione, un trigger alla fine della sessione). È deterministico (l’unica opzione che non dipende dal fatto che nessuno ricordi nulla), ma poco preciso (si attiva anche nelle sessioni di due minuti) e legato alla piattaforma.
• Una linea convenzionale: un’istruzione permanente nel file di contesto dell’ambito, o nella sua controparte non di codice, una fase della procedura operativa standard (SOP) del team: «concludere ogni sessione significativa assistita dall’IA registrando gli attriti». Infrastruttura pari a zero, ma si basa interamente sul fatto che il modello rispetti una riga tra tante, e perde efficacia man mano che il file cresce; la modalità di errore identificata è il file di memoria che ha «smesso di essere letto» (nota sul campo relativa agli anti-pattern).
• Un comando: un’istruzione digitata da una persona al/retro termine di un ramo di funzionalità o di un turno di triage. Deliberato e tempestivo; l’anello debole è la memoria umana.

Questi elementi costituiscono il sistema; li si deve stratificare. Un trigger deterministico (un hook o una fase SOP di fine turno), un payload procedurale (la competenza) e una linea convenzionale che definisce la pratica come norma. Scegliete almeno un trigger; due sono meglio. Anche i fornitori hanno colto l’intuizione: le linee guida di Codex di OpenAI recitano «quando Codex commette lo stesso errore due volte, chiedetegli di effettuare una retrospettiva e aggiornate AGENTS.md» (migliori pratiche).

L’anatomia di un buon inizio

Un record rappresenta il contratto tra la sessione che ha rilevato l’attrito e tutti gli elementi a valle. La qualità della sintesi è limitata dalla qualità del record. Quattro componenti portanti:

1. Un evento documentato, con il relativo costo. Cosa è accaduto, quando è avvenuto e quale conseguenza osservabile ne è derivata, in modo sufficientemente specifico da consentire a chi non era presente alla sessione di agire di conseguenza. Per «costo» si intende lavoro rifatto, tempo sprecato, risultato errato; una registrazione priva di indicazione del costo non potrà essere classificata in seguito. La stima del costo da parte dell’agente è approssimativa: è preferibile indicarlo piuttosto(est.) che fingere precisione.

2. Esattamente un’etichetta di causa principale scelta da un vocabolario fisso composto da dieci etichette. I vocabolari fissi consentono un’etichettatura affidabile (MAST ha raggiunto un κ = 0,88 su 14 modalità di guasto; si veda arXiv 2503.13657); le categorie a forma libera variano da persona a persona e non consentono più l’aggregazione. Le dieci:

• ambiguous-instruction: la richiesta ha tralasciato un parametro fondamentale (destinatari, ambito, definizione, arco temporale) e ha costretto a formulare un’ipotesi
• missing-context: un fatto ben noto al team, ma che non è stato comunicato
• incorrect-context: le informazioni fornite erano errate
• missing-documentation: manca un documento che dovrebbe essere presente (nessun README, specifica, runbook o procedura operativa standard)
• incorrect-documentation: esiste un documento, ma è obsoleto o errato, e ci si è basati su di esso
• work-material-friction: il materiale su cui si stava lavorando ha reso il lavoro lento o soggetto a errori: debito tecnico o struttura confusa nel codice; un account, un pannello di controllo, un foglio di calcolo o un modello disordinato al di fuori di esso (indichi sempre il materiale specifico)
• missing-access-or-tool: non era disponibile un connettore, un’autorizzazione o uno strumento necessario
• agent-error: un errore commesso dall’agente stesso (ipotesi errata, informazioni obsolete, un bug da lui causato)
• changed-requirements: le indicazioni sono cambiate nel corso della sessione e il lavoro è stato rifatto
• environment-friction: malfunzionamenti degli strumenti, timeout, problemi relativi alla sandbox o alla piattaforma

Un’etichetta per ogni risultato garantisce l’integrità delle distribuzioni: scegliete quella che meglio si adatta, prendete nota delle incongruenze nelle prove, non inventate mai un’etichetta a metà della voce. Tre regole di delimitazione svolgono la maggior parte del lavoro di disambiguazione. Il test della conoscibilità da parte dell’agente: il fatto era individuabile in qualsiasi luogo in cui l’agente potesse ragionevolmente cercare? Non trovato dove avrebbe dovuto essere → missing-documentation; fornito solo in un secondo momento, da una persona → missing-context. L’errore dell’agente è il residuo: utilizzatelo solo quando gli input erano adeguati e l’agente ha comunque commesso un errore; se l’errore è riconducibile a un input errato, etichettate l’input. E ambiguità contro cambiamento: se il chiarimento ha rivelato ciò che era sempre stato inteso, si tratta di ambiguous-instruction; se l’obiettivo è realmente cambiato, si tratta di changed-requirements.

3. Una soluzione delle dimensioni di un biglietto, che ne indichi il livello. Il livello è l’ambito a cui si riferisce la soluzione: memoria, competenze, ambiente, documentazione, il materiale stesso, processo o fase a monte. Una segnalazione di problema a cui non è allegata alcuna soluzione costituisce un reclamo.

Ecco una voce completa tratta da una sessione non dedicata alla programmazione, ovvero la revisione mensile dell’account pubblicitario:

- **[missing-context]** The brief didn't say the French campaigns were deliberately
  paused for Q3; ~40 min (est.) auditing a "broken" campaign that was fine.
  → Fix (altitude: process): add campaign-status flags to the monthly brief template

Un momento, un costo contrassegnato da un (est.)indicatore, un’etichetta, una soluzione che qualcuno potrebbe adottare la settimana prossima. Si confronti la versione inutilizzabile della stessa osservazione: «le istruzioni erano confuse»: nessun momento, nessun costo, nessun passo successivo. La vaghezza è di per sé una forma di fallimento.

4. Il diritto di non dire nulla. “Nulla di rilevante” è una risposta valida e utile; un registro gonfiato da risultati inventati finisce per oscurare quelli reali.

Un ulteriore aspetto da considerare nella progettazione: la registrazione dovrebbe essere senza restrizioni: un agente che necessita di autorizzazione per registrare i momenti di attrito tende a sottostimarli. Lasciategli registrare liberamente e fate sì che il feedback umano funga da correzione a posteriori: un segnale aggiuntivo proveniente dalla persona che ha partecipato alla sessione, non un punto di controllo in attesa del quale il ciclo rimane in sospeso.

Le regole “never-log”

I record sopravvivono alle sessioni: vengono salvati, condivisi e aggregati. Alcuni dati non vengono mai inseriti:

• Segreti, credenziali, token o chiavi API, in qualsiasi forma, anche parziali.
• Dati dei clienti o informazioni personali.
• Dati aziendali non ancora resi noti o cifre riservate: descriva l’effetto, non i dati.
• Soprattutto, le persone. Mai un nome, un ruolo o qualsiasi altro elemento che identifichi chi abbia causato una lacuna. Descriva la lacuna e quali ne sono state le conseguenze: «il brief ha lasciato il pubblico all’oscuro», non «il brief di X». Le voci del registro criticano gli input e i sistemi, non le persone. È la stessa disciplina su cui si basa una buona retrospettiva, ed è ciò che rende il registro sicuro da leggere insieme.

È normale che i dati in ingresso siano oggetto di critica: brief poco chiari, contesto mancante e requisiti forniti in ritardo sono solitamente gli aspetti su cui si concentrano gli elementi su cui è possibile intervenire. L’agente dovrebbe autovalutarsi con la stessa onestà. Se non è possibile descrivere gli attriti relativi a un determinato ambito senza ricorrere a informazioni sensibili, si raccomanda di mantenere private le voci relative a tale ambito e di condividere solo il brief aggregato.

Dove si trova il registro

Un registro per ogni ambito di revisione: il confine entro il quale vengono applicate le correzioni. Per la maggior parte del lavoro di sviluppo, tale ambito è il repository: la sua documentazione, la configurazione e le convenzioni risiedono nel repository, pertanto anche il relativo registro delle correzioni deve trovarsi lì. Al di fuori del codice, l’ambito è costituito dall’account pubblicitario, dalla casella di posta dell’assistenza e dal coinvolgimento del cliente; conservate il registro nella cartella dei documenti di quell’area di lavoro. Una registrazione archiviata al di fuori del proprio ambito è una registrazione che il responsabile della correzione non troverà mai; una voce scritta in una directory temporanea viene eliminata al termine della sessione.

Ciò che deve rimanere identico ovunque non è lo spazio di archiviazione, bensì la struttura: è lo schema, non lo spazio di archiviazione, a consentire l’aggregazione delle voci in un secondo momento. Questo è il punto centrale di questo capitolo dal punto di vista del lavoro di squadra: sono proprio i record comparabili, tra persone, agenti, sessioni e strumenti, a rendere possibile l’aggregazione a livello di team. Adattate liberamente lo spazio di archiviazione; preservate lo schema.

Cosa succederà ora

Una pila di registrazioni valide costituisce materia prima, non una visione d’insieme. I capitoli successivi proseguono da qui: la scelta dell’altitudine di ciascun punto di riferimento (la differenza tra una nota di memoria e il rifattorizzazione a cui l’attrito continua a rimandare); la sintesi delle voci in un riassunto di una pagina che il team possa leggere insieme; e la cerimonia in cui le persone e il registro si incontrano (la retrospettiva, con le registrazioni dell’agente come input per i partecipanti). Questo ciclo costituisce un’istanza del Feedback Flywheel: reintegrare gli insegnamenti appresi negli artefatti che forniscono il contesto (martinfowler.com). E la disciplina alla base delle voci è l’analisi degli errori, «l’attività più importante nelle valutazioni» (Husain & Shankar, FAQ sulle valutazioni), spostata nel momento meno oneroso possibile: mentre la sessione in cui si è verificato l’attrito è ancora in corso.

Tutto quanto sopra funziona con un file di testo e qualsiasi agente compatibile. Se preferite non creare il modello autonomamente, la ai-session-retroskill gratuita implementa questa struttura di inserimento dall’inizio alla fine; il post di avvio rapido illustra come installarla in circa dieci minuti.

Capitolo successivo: Dove dovrebbe essere applicata la correzione? tratta il problema dell’altitudine e la tabella di instradamento.