L'ingegneria del contesto richiede un ciclo di feedback

AGENTS.mdL’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 invece di procedere per tentativi. In pratica, per la maggior parte dei team, ciò si traduce in file: unCLAUDE.mdfile alla radice del repository, un file, 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 strategia più efficace che si possa adottare per rendere utili gli agenti. E quasi tutti coloro che la mettono in pratica si trovano ad affrontare lo stesso problema inespresso: 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. Questa disciplina prevede un input — la scrittura del contesto — ma non prevede un ciclo di manutenzione. È proprio questa lacuna l’argomento di questo post.

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 annotato viene superata — e la documentazione continua a descrivere con sicurezza la situazione precedente. 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 va e chiede chiarimenti a qualcuno. Un agente prendeCLAUDE.mdle istruzioni alla lettera. Se c’è scritto «esegui make setup» e quel target è stato eliminato lo scorso trimestre, l’agente non se ne fa una ragione: spreca tempo cercando di far funzionare ciò che non dovrebbe, oppure escogita una soluzione alternativa e va avanti, riportando l’istruzione errata nel proprio output.

In secondo luogo, un contesto errato è peggiore di un contesto mancante. Di fronte a una lacuna, l’agente a volte è in grado di ragionare per esclusione o di segnalarla. Di fronte a un’affermazione errata ma espressa con sicurezza, invece, 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 i metodi tradizionali non funzionano. Non è possibile effettuare una revisioneCLAUDE.mdriga per riga secondo una tabella di marcia prestabilita — nessuno lo fa. Dall’esterno non si nota 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 composto da tre schemi distinti. Tale conoscenza esiste — più o meno per tutta la durata della sessione, dopodiché svanisce.

Nessuno vi 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 dovete fare è chiedere all’agente di mettere per iscritto 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 modifica.

Il registro retroattivo della sessione costituisce il ciclo di manutenzione

Questo è esattamente il risultato di un’analisi retrospettiva dell’IA a fine sessione. Al termine di una sessione di lavoro, l’agente redige una breve e sincera nota: cosa è andato bene, dove si sono verificati intoppi e — la parte che qui conta — ogni intoppo viene contrassegnato con una delle dieci etichette fisse relative alle cause alla radice e si conclude con un «→ Risolvere:» delle dimensioni di un ticket. Due di queste dieci etichette rimandano direttamente ai vostri file di contesto:

• missing-documentation**** — l’agente aveva bisogno di un’informazione che il progetto avrebbe dovuto documentare, ma che non era stata riportata. Questa è la lista delle cose da scrivere del vostro file di contesto. Ognuna di queste voci è una riga che dovreste aggiungere allaCLAUDE.md vostra documentazione.
• incorrect-documentation**** — la documentazione esisteva, ma era errata o non aggiornata. Questo è l’elenco delle correzioni da apportare del vostro 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 delle operazioni di manutenzione di cui avrete mai bisogno: ambiguous-instruction****, ovvero quando un documento o una norma potrebbero essere interpretati 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 prevede esclusivamente il riferimento alle 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 contesto era talmente scarso che l’agente ha dovuto inventare una risposta. Legga le ipotesi di una settimana 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, di conseguenza, non riesce a individuare le lacune.

Ecco il formato 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 — la parte più dispendiosa — è già stato svolto.

Perché questo metodo è migliore rispetto alla revisione manuale

Si potrebbe provare a mantenere aggiornati i file di contesto alla vecchia maniera: programmare una revisione, leggerli dall’inizio alla fine, verificare ogni affermazione alla luce della realtà. Ciò non accade, e anche quando accade si tratta dello strumento sbagliato. Leggendo un documento in modo astratto, non è possibile capire 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 causato un errore in un agente, quindi 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 iincorrect-documentationproblemi questa settimana, le sessioni della prossima settimana incontreranno meno ostacoli, quindi il registro si accorcerà e si concentrerà su questioni più profonde. I vostri file di contesto tendono ad essere accurati non perché qualcuno li abbia verificati, ma perché le persone — e gli agenti — che li utilizzano hanno a disposizione un modo semplice e strutturato per segnalare le discrepanze. Questa è una sana collaborazione tra esseri umani e IA: l’agente individua la discrepanza, l’essere umano 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 il resoconto di fine sessione, una che sintetizza i resoconti 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 propri agenti IA illustra tutte e dieci le etichette, il controllo di validità effettuato da parte umana e il modo in cui i contributi alimentano una retrospettiva di gruppo — non solo i vostri file di contesto.

Una sfumatura che vale la pena tenere presente. Quando un agente segnala che la documentazione è errata, verifichi prima di apportare modifiche: a volte la documentazione è corretta e l’agente l’ha interpretata in modo errato. Si tratta comunque di un segnale utile (una frase facile da fraintendere è una frase che vale la pena riscrivere), ma la correzione da apportare è diversa, ed è per questo che una persona rimane coinvolta nel processo. L’agente è un partecipante che segnala ciò che ha destato il suo sospetto, mai l’autorità che decide cosa debba dire il vostro progetto.

L’efficacia dei vostri file di contesto dipende esclusivamente dall’ultima correzione accurata apportata. Gli agenti che li utilizzano vi forniscono 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 [AI retro]con , accanto al resto dei miglioramenti proposti dal vostro team.