L'ingegneria del contesto richiede un ciclo di feedback

L’ingegneria del contesto è la disciplina che consiste nel fornire a un agente di intelligenza artificiale le informazioni giuste, nella forma giusta e al momento giusto, affinché svolga un lavoro efficace anziché agire a caso. In pratica, per la maggior parte dei team, ciò si traduce in file: un file nellaCLAUDE.md directory principale del repository, un fileAGENTS.md, una cartella contenente regole e convenzioni, un prompt di sistema configurato una volta da qualcuno. Si descrive il funzionamento del proprio progetto in modo che l’agente non debba riscoprirlo ad ogni sessione.

È davvero la cosa che offre il massimo impatto per rendere utili gli agenti. E quasi tutti coloro che lo fanno si trovano ad affrontare lo stesso problema non detto: quei file diventano obsoleti e nessuno sa quali parti lo siano. Avete scritto il contesto una volta, il codice è andato avanti e ora metà di esso è silenziosamente errato. Questo approccio prevede un input, ovvero la scrittura del contesto, ma non un ciclo di manutenzione. È proprio questa lacuna l’argomento di questo articolo.

Il contesto è codice, e il codice si deteriora

Sappiamo già che la documentazione diventa obsoleta. La fase di compilazione che avete documentato viene sostituita, la cartella che avete descritto viene rinominata, la convenzione che avete riportato viene superata, e la documentazione continua a descrivere con sicurezza il mondo di un tempo. I file di contesto sono ancora peggiori della documentazione ordinaria sotto questo aspetto, per due motivi.

In primo luogo, un agente le interpreta alla lettera e agisce di conseguenza. Un essere umano dà una rapida occhiata a un file README obsoleto, intuisce che c’è qualcosa che non quadra e chiede chiarimenti a qualcuno. Un agente prende le istruzioni allaCLAUDE.md lettera. Se queste indicano «eseguire make setup» e tale target è stato eliminato lo scorso trimestre, l’agente non se ne cura. Spreca tempo cercando di far funzionare ciò che non dovrebbe, oppure escogita una soluzione alternativa e prosegue, riportando l’istruzione errata nel proprio output.

In secondo luogo, un contesto errato è peggiore di un contesto mancante. In caso di lacuna, l’agente a volte è in grado di ragionare per aggirarla o di segnalarla. Se invece si tratta di un’affermazione errata ma espressa con sicurezza, l’agente si fida. Le righe più costose nei vostri file di contesto non sono quelle mancanti, bensì quelle che un tempo erano vere.

Quindi è necessario un ciclo di manutenzione. Il problema è che le soluzioni tradizionali non funzionano. Non è possibile effettuare una revisione CLAUDE.mdriga per riga secondo una tabella di marcia prestabilita. Nessuno lo fa. Dall’esterno non vi accorgerete che il codice è obsoleto, poiché sembra funzionare correttamente. L’obsolescenza si rivela solo nel momento dell’utilizzo, a chiunque lo stia utilizzando. E sempre più spesso, chi lo utilizza non è una persona.

L’unico testimone che ne è a conoscenza

Ecco il punto cruciale. L’agente che ha appena eseguito una sessione sul vostro progetto è l’unico partecipante a sapere, concretamente, quali parti del vostro contesto siano state utili e quali invece lo abbiano indotto in errore. Ha semplicemente utilizzato i file. Ha eseguito il comando di compilazione obsoleto. Ha individuato la cartella che non esiste. Ha seguito lo schema che si è rivelato essere in realtà composto da tre schemi distinti. Tale conoscenza permane all’incirca per tutta la durata della sessione, dopodiché svanisce.

Nessuno Le indica quale contesto manchi o sia errato, se non proprio l’elemento che ne ha appena risentito. Ecco il ciclo di feedback, proprio lì, pronto per essere sfruttato. Tutto ciò che deve fare è chiedere all’agente di annotare ciò che ha appreso prima della chiusura della sessione e strutturare la richiesta in modo che il risultato indichi direttamente i file che necessitano di modifiche.

Il registro retroattivo della sessione costituisce il ciclo di manutenzione

Questo è esattamente il risultato di una retrospettiva sull’IA a fine sessione. Al termine di una sessione di lavoro, l’agente redige una breve e sincera relazione: cosa è andato bene, dove si sono verificati degli intoppi e, cosa più importante in questo contesto, ogni intoppo viene contrassegnato con una delle dieci etichette fisse relative alle cause alla radice e si conclude con un “→ Da risolvere:” delle dimensioni di un ticket. Due di queste dieci etichette rimandano direttamente ai Suoi file di contesto:

• missing-documentation****: l’agente aveva bisogno di un’informazione che il progetto avrebbe dovuto documentare, ma che non era stata documentata. Questa è la lista delle cose da scrivere del vostro file di contesto. Ognuna di queste voci è una riga che dovreste aggiungere CLAUDE.mdalla vostra documentazione.
• incorrect-documentation****: la documentazione esisteva, ma era errata o non aggiornata. Questo è l’elenco delle correzioni da apportare nel Suo file di contesto. Ognuna di queste voci rappresenta una riga obsoleta che l’agente ha individuato nell’unico modo possibile: utilizzandola e incontrando un ostacolo.

Aggiungetene un terzo e avrete coperto la maggior parte della manutenzione di cui avrete mai bisogno: ambiguous-instruction****, ovvero nei casi in cui una memoria o una norma possano essere interpretate in più di un modo. Questo è il circolo vizioso. Non si effettuano revisioni dei propri file di contesto secondo un calendario; si lascia che siano gli agenti che li utilizzano a indicare, nel momento stesso dell’uso, esattamente quali righe modificare, con le prove allegate, poiché la prassi si basa esclusivamente sulla citazione delle prove.

E c’è un quarto segnale che è facile trascurare: le ipotesi. Una buona voce elenca ogni punto in cui l’agente ha colmato una lacuna con un’ipotesi. Ogni ipotesi rappresenta un punto in cui il vostro contesto era talmente scarso che l’agente ha dovuto inventare una risposta. Legga le ipotesi di una settimana intera e otterrà un elenco di cose da fare per i Suoi file di contesto che non avrebbe mai potuto redigere da solo, poiché conosce già le risposte e quindi non è in grado di individuare le lacune.

Ecco la struttura dei risultati ottenuti. Si tratta di un esempio illustrativo, non di dati reali:

## Friction
- CLAUDE.md says "run `make setup`" but that target was removed; the
  actual setup is `pnpm install && pnpm db:migrate`. Lost ~10 min.
  (incorrect-documentation)
  → Fix: Update the "Getting started" block in CLAUDE.md to the pnpm commands.
- Nothing documents that integration tests need the worker running.
  Found it by reading the CI config. (missing-documentation)
  → Fix: Add a "Running tests" note naming `pnpm worker` as a prerequisite.

## Guesses I made
- Assumed the `api/` package is the public surface and `internal/` is not,
  because nothing states it. Please confirm before I rely on it again.

Ogni riga corrisponde a una modifica specifica apportata a un file specifico. Si tratta di un ciclo di manutenzione che una persona eseguirà effettivamente, poiché il lavoro di individuazione del problema, ovvero la parte più dispendiosa, è già stato svolto.

Perché questo metodo è migliore rispetto alla revisione contabile manuale

Si potrebbe provare a mantenere aggiornati i file di contesto alla vecchia maniera: pianificare una revisione, leggerli dall’inizio alla fine, verificare ogni affermazione alla luce della realtà. Ciò non avviene, e anche quando accade si tratta dello strumento sbagliato. Leggendo un documento in modo astratto, non è possibile individuare quali righe siano obsolete. Sembrano tutte plausibili. L’obsolescenza è visibile solo durante l’uso. Il registro retrospettivo è una manutenzione del contesto guidata dall’uso reale: vengono contrassegnate solo le righe che hanno effettivamente fatto scattare un agente, così si corregge ciò che è realmente difettoso invece di rileggere ciò che funziona già correttamente. È la differenza tra un rilevatore di fumo e il percorrere l’edificio alla ricerca di tracce di fumo.

Inoltre, si tratta di un processo cumulativo. Risolvendo i problemiincorrect-documentation questa settimana, nelle sessioni della prossima settimana si incontreranno meno ostacoli, quindi il registro si accorcerà e si concentrerà su questioni più profonde. I Suoi file di contesto tendono ad essere accurati non perché qualcuno li abbia sottoposti a revisione, ma perché le persone e gli agenti che li utilizzano disponevano di un metodo economico e strutturato per segnalare le discrepanze. Questa è una sana collaborazione tra uomo e IA: l’agente individua la discrepanza, l’uomo decide la modifica.

Avviare il ciclo

Se state già investendo nell’ingegneria del contesto, questa è la metà che mancava: il ciclo di manutenzione che impedisce all’investimento di andare sprecato. È open source e distribuito con licenza MIT:

• Scaricate le competenze e il pacchetto di prompt: github.com/TeamRetroHQ/teamretro-skills: una skill Claude Code che redige la voce di fine sessione, una che sintetizza le voci in una sintesi e un pacchetto di prompt indipendente dallo strumento per Cursor, GitHub Copilot o qualsiasi altro agente a cui sia possibile inviare prompt.
• Consultate la guida completa: Come raccogliere feedback dai vostri agenti IA illustra tutte e dieci le etichette, il controllo di validità effettuato da un essere umano e il modo in cui i dati raccolti alimentano una retrospettiva di gruppo, non solo i vostri file di contesto.
• Approfondimento sul ciclo stesso: i cicli di feedback degli agenti descrivono il quadro completo: il ciclo “rilevazione-correzione”, gli strumenti che lo gestiscono e il ruolo che vi ricopre una sessione.

Una sfumatura da tenere presente. Quando un agente segnala che la documentazione è errata, verifichi prima di apportare modifiche, poiché talvolta la documentazione è corretta e l’agente l’ha interpretata in modo errato. Si tratta comunque di un segnale utile (una frase che si presta a essere fraintesa è una frase che vale la pena riscrivere), ma la correzione da apportare è diversa, ed è per questo che è necessario il coinvolgimento di una persona. L’agente è un partecipante che segnala ciò che ha destato il suo sospetto, mai l’autorità che stabilisce cosa debba dire il vostro progetto.

L’efficacia dei Suoi file di contesto dipende esclusivamente dall’ultima correzione accurata apportata. Gli agenti che li utilizzano Le trasmettono tali correzioni al termine di ogni sessione. Non vi resta che annotarle. E se il vostro team desidera che tali correzioni vengano inserite in un luogo già consultato dagli utenti, l’agente può preparare i propri suggerimenti e pubblicarli direttamente sulla vostra bacheca tramite il server MCP di TeamRetro, previa vostra conferma, contrassegnati con [AI retro], accanto al resto dei miglioramenti apportati dal vostro team.