Come raccogliere feedback dai propri agenti basati sull'intelligenza artificiale

Questa settimana un agente di intelligenza artificiale ha consegnato del codice per conto vostro. Ha letto le vostre istruzioni, ha analizzato il codice sorgente, si è imbattuto in un ostacolo dovuto a una documentazione errata, ha trovato una soluzione approssimativa per superarlo e ha proseguito. Poi la sessione si è conclusa e tutto ciò che aveva appreso sui punti critici del vostro progetto è andato perso. Nessuno ha chiesto all’unico partecipante che aveva appena trascorso un’ora all’interno del vostro repository cosa lo rallentasse.

Le retrospettive esistono proprio per colmare questa lacuna: il team si riunisce, individua ciò che ha aiutato e ciò che ha ostacolato il lavoro, e trasforma queste informazioni in cambiamenti concreti. Gli agenti di intelligenza artificiale stanno ormai svolgendo un lavoro concreto all’interno del Suo team e incontrano le stesse difficoltà dei Suoi collaboratori, talvolta anche maggiori. La domanda è quindi semplice. Se un agente svolge il lavoro del team, perché non viene incluso nella retrospettiva?

Questa guida tratta proprio dell’aggiunta di tale voce. Non si tratta di un nuovo formato di retrospettiva, né di automatizzare i contributi dei vostri collaboratori: si tratta di un nuovo partecipante. L’intelligenza artificiale fornisce un feedback; spetta comunque al vostro team decidere cosa significhi. Ecco come raccoglierlo e come integrarlo nella retrospettiva che già conducete.

Questo post costituisce una guida introduttiva. L’iniziativa dispone ora di una guida completa, Retrospettive degli agenti AI, che copre l’intero ciclo, dalla raccolta dei dati alla cerimonia di gruppo; inizi da qui, poi consulti quella guida per avere un quadro completo.

Perché vale la pena documentare l’esperienza del Suo agente di intelligenza artificiale

L’argomento a favore di un “retro” umano è che la memoria si affievolisce e le lezioni apprese non vengono condivise. Con un agente di intelligenza artificiale il problema è ancora più acuto: la sua memoria di lavoro non si affievolisce, ma svanisce. Nel momento in cui una sessione si chiude, il contesto scompare. Nulla di tutto ciò viene trasferito alla sessione successiva, a meno che non vi sia qualcosa che lo registri: il README mancante che avrebbe voluto esistesse, la variabile d’ambiente non documentata, le istruzioni che avrebbero potuto essere interpretate in tre modi diversi.

Inoltre, gli agenti raccolgono un tipo specifico e utile di segnale. Nel corso di un’ora di lavoro, un agente nota cose che una persona trascura, poiché quest’ultima ha già in mente il contesto:

• Il documento di onboarding che descrive una fase di compilazione che non esiste più.
• Poiché la funzione viene utilizzata in modo diverso nei tre punti di chiamata, “seguire lo schema” rimanda a tre schemi distinti.
• Le istruzioni che recitavano “ripulire la configurazione” senza specificare quale configurazione né in che modo.
• La suite di test che richiede l’esecuzione di un servizio che nessuno vi indica di avviare.

Anche uno sviluppatore in carne e ossa si imbatte in questi problemi, alza le spalle, trova una soluzione alternativa e raramente li segnala, poiché l’attrito è al di sotto della soglia che giustificherebbe di “sollevare la questione in riunione”. Un agente, se interpellato nel modo corretto, segnalerà ogni singolo caso, allegando le prove. È questo il valore: non che l’IA sia più esperta dei vostri processi, ma che rappresenti uno sguardo nuovo, privo di ego e di tolleranza accumulata nei confronti di questi piccoli intoppi. La collaborazione tra uomo e IA funziona al meglio quando entrambe le parti possono indicare ciò che le ha rallentate.

Un avvertimento prima di proseguire, poiché è fondamentale per tutto ciò che seguirà. L’IA è un partecipante, mai un facilitatore o un giudice. Contribuisce alla retrospettiva proprio come farebbe qualsiasi altro partecipante. Non conduce la riunione, non valuta il vostro team né decide cosa correggere. Sono le persone a leggere il suo feedback, a verificarne la validità e a scegliere ciò che conta. Mantenete chiara questa linea di demarcazione e la pratica rimarrà sana; se la rendete confusa, avrete affidato il vostro processo di miglioramento a uno strumento che non può essere ritenuto responsabile del risultato.

L’allenamento: un’analisi retrospettiva di fine sessione

Il meccanismo è volutamente semplice. Al termine di una sessione di lavoro (un’attività di programmazione, un lavoro di ricerca, una rifattorizzazione), l’agente scrive una breve riflessione sincera in un file all’interno del repository su cui stava lavorando. Ciò richiede all’agente meno di un minuto. Una persona impiega all’incirca lo stesso tempo per verificarne la correttezza. Questo è l’intero ciclo.

Un buon articolo si compone di quattro parti:

1. Cosa ha funzionato bene: i momenti che vale la pena conservare, riferiti a qualcosa di concreto accaduto durante la sessione. Non si tratta di elogi né di riempitivi. Se non è possibile ricondurlo a un momento specifico, non va inserito.
2. Attrito: i casi in cui il lavoro è risultato più impegnativo del necessario. Ogni elemento di attrito è contrassegnato con una delle dieci etichette fisse relative alle cause alla radice (di seguito) e si conclude con una nota delle dimensioni di un ticket ”→ Soluzione:”, ovvero la regola che lo rende utile. Nessuna constatazione senza una soluzione.
3. Una soluzione prioritaria del tipo “Da fare per prima cosa”: l’unica modifica che avrebbe aiutato maggiormente. Un unico punto, messo in evidenza in cima alla lista, in modo che un lettore indaffarato, che non legge nient’altro, possa leggere proprio ciò che conta.
4. Ipotesi formulate: ogni punto in cui l’agente ha colmato una lacuna con un’ipotesi. Queste sono preziose. Un’ipotesi indica un punto in cui il contesto era ambiguo o mancante; l’agente Le sta mostrando esattamente dove ha dovuto inventare una risposta.

Due principi garantiscono l’affidabilità dei contributi. Solo momenti supportati da prove: ogni punto fa riferimento a qualcosa che è realmente accaduto, in modo che nessuno legga consigli generici. E l’onestà è reciproca: l’agente critica il materiale che gli è stato fornito e i propri errori. Un contributo che si limita a incolpare il codice e non ammette mai «Ho interpretato male questo passaggio e ho perso venti minuti» non è onesto; questa pratica richiede entrambe le cose.

Le dieci etichette relative alle cause alla radice

A ogni elemento di attrito viene assegnata esattamente un’etichetta. È proprio un vocabolario ridotto e ben definito a trasformare un insieme di lamentele isolate in uno schema su cui è possibile agire: quando la stessa etichetta ricorre in dieci sessioni, saprete su cosa concentrare la vostra prossima ora di lavoro. Queste dieci etichette coprono tutti i modi in cui il lavoro vero e proprio viene ostacolato.

Etichetta	Cosa significa	Dove solitamente viene applicata la correzione
ambiguous-instruction	Il documento potrebbe essere interpretato in più di un modo.	La persona che redige l’incarico
missing-context	Le informazioni di cui l’agente aveva bisogno non sono state fornite.	Il brief, ovvero il contesto condiviso
incorrect-context	Le informazioni fornite erano errate o non aggiornate.	Il brief, ovvero il contesto condiviso
missing-documentation	Il repository non riporta alcune informazioni che dovrebbe riportare.	La documentazione / CLAUDE.md / AGENTS.md
incorrect-documentation	La documentazione esiste, ma è errata o non aggiornata.	La documentazione / CLAUDE.md / AGENTS.md
work-material-friction	Il materiale su cui si stava lavorando ha reso difficile la modifica (codice, account o modello disordinati).	Il portafoglio di attività / il debito tecnico
missing-access-or-tool	Non era disponibile una credenziale, un’autorizzazione o uno strumento.	Operazioni / piattaforma / controllo degli accessi
agent-error	L’agente ha commesso un errore: ha frainteso, ha preso la strada sbagliata, ha sprecato le sue energie.	Il racconto dell’agente stesso, in tutta sincerità
changed-requirements	Il gol è stato segnato a metà della sessione.	Pianificazione / gestione dell’ambito
environment-friction	L’ambiente di sviluppo ha reagito: build instabili, configurazione lenta, strumenti non funzionanti.	Esperienza degli sviluppatori

(Nella versione 2 delle competenze, il nome è stato modificato codebase-frictionin work-material-friction; le voci precedenti che riportano la vecchia denominazione continuano a essere considerate come la stessa causa.)

Si noti come le etichette suddividano chiaramente le responsabilità. Alcune rimandano a voi: ambiguous-instruction, missing-context. Altre rimandano al progetto: missing-documentation, work-material-friction, environment-friction. E agent-errorrimanda all’agente. È proprio questa diversificazione il punto fondamentale: impedisce che il registro diventi un elenco di lamentele e lo trasforma in una mappa che indica dove sono necessari miglioramenti, da ogni parte.

Il log: in formato Markdown semplice, nel Suo repository

Non è necessario installare alcun prodotto per la fase di acquisizione. L’agente scrive in formatodocs/ai-retros/entries/ Markdown semplice, che viene sottoposto a commit insieme al codice. Si tratta di una scelta deliberata:

• Si trova proprio dove è stato svolto il lavoro. L’attrito si è verificato in questo repository; lo stesso vale per la relativa documentazione. Chiunque legga la cronologia Git vede il feedback accanto alla modifica che lo ha generato.
• È possibile confrontare le differenze ed effettuare ricerche con grep. Desidera tutti gli elementimissing-documentation dell’ultimo mese? È un gioco da ragazzigrep. Vuole verificare se il tasso di abbandono è diminuito dopo aver corretto la build? È tutto nel sistema di controllo delle versioni.
• È indipendente dallo strumento utilizzato. Il Markdown contenuto in una cartella funziona con qualsiasi agente, qualsiasi editor e qualsiasi processo. Nulla di proprietario, nulla da migrare in seguito.

Ecco un esempio illustrativo di registrazione. Si tratta di una sessione fittizia volta a illustrare la struttura, non di dati reali relativi a un pilota:

# Session retro — add rate limiting to the public API
Agent: Claude Code · 2026-07-13 · ~50 min

## Do this first
→ Fix: Document the Redis connection setup in CLAUDE.md — three of us
  will hit this same wall. (missing-documentation)

## What went well
- The `middleware/` folder has a clear pattern; the existing auth
  middleware was a clean model to copy for the rate limiter.
- Tests ran fast once the service was up.

## Friction
- Nothing documented that the test suite needs Redis running locally.
  Spent ~15 min chasing a connection error before finding it by reading
  docker-compose.yml. (missing-documentation)
  → Fix: Add a "Running tests locally" section to CLAUDE.md naming the
    Redis dependency and the `docker compose up redis` command.
- The brief said "add sensible rate limits" without numbers. I chose
  100 req/min per key. (ambiguous-instruction)
  → Fix: Decide the real limits with the team and put them in the ticket.
- `config/limits.ts` and `config/throttle.ts` both looked like the right
  home for the setting; I couldn't tell which was canonical. (work-material-friction)
  → Fix: Merge or clearly comment which config owns rate limiting.

## Guesses I made
- Assumed 100 req/min because the payment endpoints use that. May be
  wrong for read-heavy public endpoints — please check.
- Assumed rate-limit responses should be 429 with a Retry-After header.

Consideratelo come l’appunto di un partecipante, perché è proprio questo che è. È specifico, espone le proprie ipotesi e ogni problema è accompagnato da un passo successivo.

Come inserirlo nella retrospettiva del Suo team

Le singole segnalazioni costituiscono la materia prima. Prima della vostra riunione retrospettiva, una fase di sintesi complementare esamina le segnalazioni pervenute dall’ultima volta e produce un riassunto di una pagina per la riunione: gli attriti che si sono ripetuti, le soluzioni principali raggruppate per etichetta, le ipotesi che continuano a ricomparire nello stesso punto. È soggetto agli stessi standard delle voci (nessuna lode né riempitivo, nessuna constatazione senza una soluzione), e la sua onestà vale in entrambi i sensi: critica le voci che gli sono state fornite (prove insufficienti, una soluzione troppo vaga per essere messa in pratica) con la stessa prontezza con cui le riassume.

Poi la parte umana, che non cambia:

1. Legga il documento informativo prima della riunione di retrospettiva: lo consideri come la lettura preliminare di un altro partecipante, non come l’ordine del giorno.
2. Inserite la prima o le prime due voci sulla bacheca, accanto a ciò che hanno portato i vostri collaboratori. Ora la notamissing-documentation dell’IA si trova accanto alla frase di un collega che recita “l’inserimento mi ha richiesto una settimana”, e potete constatare che si tratta dello stesso problema.
3. Discutete e decidete in gruppo. L’agente ha sollevato la questione; spetta alle persone presenti nella stanza decidere cosa succederà in seguito. Alcune questioni verranno affrontate, altre accantonate, altre ancora non troveranno consenso. Va tutto bene: si tratta del contributo di un partecipante, non di un sistema che impone qualcosa.

Esistono due modi per completare quest’ultimo passaggio, e il primo non comporta alcun costo:

• Con qualsiasi strumento retro. Il brief è semplicemente un documento. Leggetelo prima della riunione, aggiungete uno o due punti principali alla bacheca che utilizzate, post-it compresi. L’intero processo funziona in questo modo, dall’inizio alla fine, senza TeamRetro né alcun altro prodotto specifico.
• Con TeamRetro, l’agente pubblica autonomamente i propri post. Se il vostro team gestisce le proprie retrospettive su TeamRetro, l’agente può preparare i propri suggerimenti sulla base del log e, previa vostra conferma su ciascun elemento, pubblicarli tramite il server MCP di TeamRetro: elementi in sospeso in coda per la vostra prossima retrospettiva, azioni da intraprendere quando una soluzione ha già un responsabile, oppure idee inserite direttamente nella bacheca. Ogni elemento pubblicato è preceduto dal prefisso [AI retro], in modo che i partecipanti alla riunione possano vedere chi lo ha sollevato. Ecco la differenza in una sola riga: invece di essere voi a portare il feedback dell’IA alla riunione, è il partecipante stesso a presentarlo.

Iniziare in circa 10 minuti

L’intero progetto è open source con licenza MIT. Il repository TeamRetro-skills copre entrambi i percorsi: ai-session-retro(scrive la voce di fine sessione) e ai-retro-brief(sintetizza le voci nel brief pre-retro) non richiedono alcun prodotto, mentre teamretro-post-recommendationsaggiunge il percorso di pubblicazione per i team TeamRetro. Un pacchetto di prompt indipendente dallo strumento utilizzato completa il tutto.

Per cominciare:

1. Clonate il repository e inserite le competenze nella vostra configurazione di Claude Code, oppure copiate il pacchetto di prompt se utilizzate un altro strumento.
2. Non utilizzate Claude Code? Il pacchetto di prompt è stato concepito per funzionare con Cursor, GitHub Copilot o qualsiasi altro agente a cui sia possibile fornire un prompt di sistema: stessa struttura in quattro parti, stesse dieci etichette, stesso principio “nessun risultato senza una soluzione”.
3. Esegua una sessione con il programma attivo. Al termine, legga la nota che è stata generata. Quella prima lettura è solitamente il momento in cui si ha l’illuminazione: l’agente avrà individuato un aspetto del Suo progetto di cui era vagamente consapevole ma che non aveva mai messo per iscritto.

Indicate nelle voci una cartelladocs/ai-retros/entries/ all’interno del repository in cui operano i vostri agenti, eseguite il commit e il gioco è fatto.

Limiti reali

Si tratta di uno studio giovane che si guadagna la fiducia dei clienti dimostrando chiarezza su ciò che non è in grado di fare.

• Un’intelligenza artificiale non è in grado di individuare tutti i propri errori. Alcuni agent-errorattriti risultano invisibili all’agente che li ha generati. Essa non sa ciò che non sa. La revisione umana non è un semplice elemento accessorio; è il modo in cui si individuano i punti ciechi. Ecco perché l’intelligenza artificiale rimane un partecipante e non assume mai il ruolo di giudice.
• Una singola registrazione è un aneddoto. Occorrono circa cinque registrazioni prima che gli schemi assumano un significato. Un intoppo in una singola sessione potrebbe essere semplicemente sfortuna; lo stesso codice cinque volte è invece un segnale. Attendete un paio di settimane prima di trarre conclusioni definitive.
• L’agente riporta la propria esperienza, non la realtà oggettiva. Quando afferma che la documentazione è errata, verifichi: a volte la documentazione è corretta e l’agente l’ha interpretata in modo errato. Ciò è comunque utile (significa che la documentazione è facile da fraintendere), ma richiede una soluzione diversa.
• Le istruzioni di lavoro scadenti generano risultati scadenti. Questa pratica mette in luce le difficoltà; non crea intuizioni dove non ce n’erano. Una sessione con istruzioni chiare e un repository ben organizzato produce un risultato breve e poco interessante, il che è esattamente ciò che ci vuole.

Nulla di tutto ciò sminuisce la validità della questione. I vostri agenti di intelligenza artificiale stanno già svolgendo il lavoro e stanno già incontrando degli ostacoli. L’unica domanda è se ve ne rendete conto. Concedete loro un minuto alla fine della sessione per esprimersi, leggete ciò che vi viene riportato con il giudizio di una persona e inserite le osservazioni sincere nella retrospettiva che già conducete. È lì che va inserito il feedback di un partecipante: proprio accanto al vostro personale.

Abbiamo completato l’intero percorso con la nostra squadra, agenti inclusi. Scoprite cosa è successo quando i nostri compagni di squadra IA si sono uniti alla nostra sessione di retrospettiva.

---

State creando file di contesto per i vostri agenti? Scoprite perché l’ingegneria del contesto necessita di un ciclo di feedback. E se siete alle prime armi con lo svolgimento delle retrospettive, iniziate con come condurre una retrospettiva agile.