CLAUDE.md per i team: come abbiamo trasformato i ricordi generati dall’intelligenza artificiale di cinque persone in regole condivise

Ogni sviluppatore che lavora con un agente di programmazione basato sull’intelligenza artificiale sta silenziosamente redigendo un manuale di regole. La memoria automatica di Claude Code salva le note relative alle vostre correzioni man mano che lavora, il vostro profilo personale ~/.claude/CLAUDE.mdraccoglie le preferenze che vi siete stancati di ripetere e alcune competenze personali si sviluppano attorno alle attività che svolgete ogni settimana. Tutto ciò è privato. La memoria automatica è locale alla macchina e specifica per ogni repository: gli agenti dei vostri colleghi non ne hanno mai accesso.

Pertanto, cinque persone apprendono la stessa lezione separatamente, ciascuna in un file privato. Le regole di cui il vostro team ha maggiormente bisogno sono già state messe per iscritto. Semplicemente, non sono riportate in alcun documento condiviso.

A settembre, in cinque abbiamo organizzato un’iniziativa volta a raccogliere le esperienze: abbiamo messo in comune quei file personali e ci siamo chiesti quali regole meritassero di diventare regole di squadra. Ecco come abbiamo proceduto, quali regole sono state selezionate, dove è stata collocata ciascuna di esse e cosa abbiamo scoperto, comprese le regole che abbiamo valutato in modo errato.

Che cos’è un “raccolto di ricordi”

Una “raccolta di memorie” è un’attività di gruppo articolata in tre fasi. Ciascun partecipante esporta i propri ricordi relativi agli agenti privati e le proprie regole personali. Un revisore raggruppa le voci presenti nelle esportazioni di tutti i partecipanti. Le regole che più persone hanno annotato in modo indipendente vengono proposte per i file condivisi: il progettoCLAUDE.md``AGENTS.md, una competenza condivisa o un check-in nella CI.

Si tratta della fase di manutenzione che l’ingegneria del contesto solitamente tralascia. Abbiamo già sostenuto in precedenza che i file di contesto necessitano di un ciclo di feedback guidato dagli agenti che li utilizzano. Una “raccolta” (harvest) è lo stesso ciclo applicato alle persone anziché alle sessioni: si tratta della Fase 4 del ciclo di vita del feedback degli agenti, mirata alle note già rimaste confinate nella memoria privata.

Gli strumenti a disposizione per questo scopo sono limitati. Dei dieci strumenti di programmazione basati sull’intelligenza artificiale che abbiamo esaminato, solo Devin offre un ciclo che monitora una sessione, propone una regola condivisa e attende l’approvazione da parte di un utente. Gli altri si basano su file scritti e inviati manualmente dagli utenti, oppure su serie di istruzioni inviate da un amministratore. Nessuno di essi attinge dai ricordi personali di più persone per individuare possibili regole di squadra.

Cosa abbiamo fatto

Il 17 settembre 2026, cinque sviluppatori hanno eseguito ciascuno uno script di esportazione sulle proprie memorie di Claude Code, sul proprio globale personale eCLAUDE.md sulle proprie competenze personali. Lo script non trasmette nulla. Ciascuno ha letto il proprio pacchetto, ha eliminato tutto ciò che non doveva essere trasmesso e solo allora lo ha inviato.

I cinque pacchetti contenevano 444 voci di memoria, 5 CLAUDE.mdfile globali, 13 competenze personali e 194 righe che descrivevano le competenze installate in ciascun repository. Un revisore, un agente di intelligenza artificiale che collaborava con un essere umano, ha raggruppato le voci presenti in tutti e cinque i pacchetti e ha redatto una proposta per ciascun gruppo. Il 22 settembre, quattro di noi hanno votato su due pagine di revisione. Le promozioni sono state inviate come normali pull request in tre repository: il nostro repository principale del prodotto, un repository dedicato ai giochi e il nostro plugin condiviso per le competenze.

I bundle risiedono su un ramo che non viene mai integrato. Vengono emesse solo le promozioni, ciascuna sotto forma di pull request separata relativa al repository che gestisce, sottoposta a revisione come qualsiasi altra modifica.

Cosa determina la promozione: si contano gli autori, non i contributi

Una regola viene promossa quando due o più persone l’hanno annotata in modo indipendente. Si contano gli autori distinti, mai le voci. Questa singola regola ha svolto la maggior parte del lavoro e ha richiesto tre perfezionamenti prima di poter essere considerata affidabile.

Valutiamo l’utente più assiduo. Un unico gruppo comprendeva 251 delle 444 voci, distribuite su 10 repository. Tutti gli altri hanno apportato da 37 a 68 voci distribuite su 1–4 repository. Pertanto, l’espressione «due autori» indicava solitamente «il nostro utente più assiduo dell’agente più uno», e un cluster privo dell’utente più assiduo rappresentava un’evidenza più rara e più solida. Abbiamo contrassegnato tali cluster separatamente.

Una persona equivale a un autore. Un programmatore ha effettuato l’esportazione da due macchine. Si tratta di un unico autore. Il fatto che una persona ribadisca la stessa regola per tre volte costituisce un’enfasi. Per una conferma è necessaria una seconda persona.

Le fonti condivise non sono indipendenti. I fileCLAUDE.md globali di due persone erano identici a livello di byte nelle prime quattro sezioni, poiché entrambi avevano adottato lo stesso testo pubblicato: le linee guida di codifica di Andrej Karpathy per gli agenti di intelligenza artificiale. Entrambi citavano un unico documento a monte, pertanto questo è stato considerato come un’unica fonte. Qualsiasi cluster futuro basato esclusivamente su quella coppia verrà prima verificato rispetto alla formulazione originale.

Per classificare ciascun cluster abbiamo adottato i quattro operatori di ExpeL, un metodo di ricerca dedicato agli agenti che apprendono regole dall’esperienza: AGGIUNGERE una nuova regola, VOTARE POSITIVAMENTE una già presente nei documenti condivisi, VOTARE NEGATIVAMENTE una contraddetta dalle prove, MODIFICARE una che è simile ma errata. Il voto negativo e la modifica sono importanti tanto quanto l’aggiunta. Un processo di raccolta in grado solo di aggiungere regole allunga i Suoi file di contesto senza mai renderli più corretti.

La soglia determina ciò che il revisore propone, non ciò che il team potrebbe adottare. Una seconda pagina di revisione elencava i contributi di un unico autore che sembravano meritevoli di essere condivisi, e i presenti hanno votato su ciascuno di essi. Sono stati accettati perché le persone li hanno letti e si sono dichiarate d’accordo.

Dove dovrebbe essere collocata ciascuna regola

Concordare una regola è metà della decisione. L’altra metà riguarda il suo livello: il livello in cui verrà effettivamente letta e applicata. (Il capitolo della nostra guida dedicato a dove dovrebbe essere collocata una correzione illustra l’intera struttura gerarchica.) Per le regole raccolte, questa è la tabella di instradamento che abbiamo utilizzato:

La regola è la seguente:	Appartiene a	Perché
Un dato di fatto che si ripete in ogni sessione in questo repository è che è necessario	Il progetto CLAUDE.md	Viene caricato all’inizio di ogni sessione
Lo stesso vale per ogni strumento di intelligenza artificiale utilizzato dal team	AGENTS.md, importato da CLAUDE.md	Un unico file leggibile da tutti gli strumenti
Riguarda solo una parte del codice sorgente	Una regola con ambito di percorso in .claude/rules/	Viene caricato solo quando l’agente rileva i file corrispondenti
Una procedura utilizzata in diversi repository	Una funzionalità in un plugin condiviso	I plugin offrono competenze, non CLAUDE.md
Una procedura specifica per un repository	Una competenza in materia di repo	Viene caricato quando l’attività lo richiede
I dettagli di riferimento sono troppo lunghi per ogni sessione	Un documento, più un’indicazione di una riga in CLAUDE.md	Un documento che non viene caricato è un documento che l’agente non legge mai
Verificabile meccanicamente	Una regola Lint, un test o un controllo CI	La prosa mette in guardia; un controllo la blocca
Una preferenza relativa ai propri strumenti, alla propria macchina o al proprio budget	La Sua esperienza personale CLAUDE.mdo il Suo ricordo	Non si tratta di un dato di fatto relativo al codice sorgente

È necessario sottolineare due aspetti. Innanzitutto, un plugin Claude Code può includere skill, agenti e hook, ma non procedureCLAUDE.md. Le procedure sono condivise tra i vari repository all’interno di un plugin; le regole fisse devono essere inserite in ciascun repository che ne ha bisogno.

In secondo luogo, si deve eliminare la memoria privata solo una volta che la destinazione si è caricata automaticamente. Se si sposta una regola in un documento che non viene caricato, l’agente semplicemente la dimentica. Nei casi in cui una regola venisse inserita in documenti di riferimento, la memoria privata si riduceva a un puntatore anziché scomparire.

Come affrontare le contraddizioni

I ricordi aggregati presentano discrepanze. Risolva le contraddizioni in base all’ambito d’applicazione, ove possibile, sostituisca l’elemento obsoleto e inserisca le discrepanze relative alle preferenze in un contenitore esplicito dedicato alle questioni irrisolte.

Verifichi innanzitutto l’ambito di applicazione. Una contraddizione riguardava le modalità di configurazione delle dipendenze in una seconda copia di lavoro di un repository: due persone avevano scritto regole opposte. Entrambe erano valide nel proprio repository. Una successiva modifica apportata a una skill condivisa aveva risolto la questione per entrambi, e la memoria del nostro utente più assiduo si è rivelata quella obsoleta; pertanto, è quella da sostituire anziché da eliminare silenziosamente.

Sostituire, mai sovrascrivere. Quando una regola condivisa viene modificata, si aggiunga la nuova regola indicando la data e si mantenga leggibile quella precedente, proprio come un documento relativo a una decisione architettonica sostituisce una decisione precedente. Il revisore successivo potrà così vedere cosa è cambiato e perché.

Mantenere una questione in sospeso. La seconda contraddizione riguardava il modello di IA che i subagenti avrebbero dovuto utilizzare. Due persone desideravano un unico modello di alto livello per ciascun subagente; un’altra proponeva di scegliere i modelli in base all’attività. Il voto si è diviso in due «discutere» e due «d’accordo». La questione è rimasta volutamente irrisolta, poiché riguarda quanto ciascuno sia disposto a spendere a proprio carico, e non un aspetto del codice sorgente. Rimane nelle regole private di ciascuno.

Cosa è emerso dalla raccolta

Dalla prima pagina di revisione sono state approvate quindici promozioni: 11 per il nostro repository principale dei prodotti (due delle quali si applicavano anche al repository dei giochi), tre per il plugin delle competenze condivise e una che correggeva l’esportatore di Harvest. Dalla seconda pagina ne sono state approvate altre diciassette: fatti relativi a un unico autore che il gruppo ha concordato di condividere, più due gruppi che nel primo conteggio erano stati erroneamente registrati come relativi a un unico autore. Nella seconda pagina, un elemento è stato bocciato, tre sono stati accantonati per ulteriori discussioni o per trovare una collocazione più adeguata, e tre sono stati approvati ma richiedono codice o una skill anziché una semplice riga di documentazione. La questione relativa al modello è rimasta in sospeso.

Il tema più ricorrente riguardava i commenti. Tre autori, uno dei quali lo aveva annotato ben quattro volte: i commenti riportano fatti oggettivi e duraturi relativi al codice; non descrivono mai la modifica né la sua storia. Un autore ha osservato che i “subagenti” sono i principali responsabili di questa pratica.

La questione più ampia riguardava le prove. Quattro dei cinque autori avevano redatto una versione del principio secondo cui «occorre verificare prima di affermare; una ricerca infruttuosa non costituisce prova di assenza». Le affermazioni dei revisori sono ipotesi, e il fatto di non riuscire a riprodurre un bug non dimostra che esso non possa verificarsi. Era quanto di più simile a una regola interna condivisa il team avesse, e non era stato messo per iscritto in alcun documento condiviso.

Un gruppo correlato, a cura di due autori, riguardava uno stato Git non aggiornato: un ramo locale molto indietro rispetto a quello remoto, una ricerca eseguita sull’ambiente di lavoro errato. Ciascuno dei cinque incidenti ha generato un’affermazione errata, ma espressa con sicurezza, che è stata inserita in un messaggio di commit o nella descrizione di una pull request.

La raccolta ha corretto le indicazioni errate, non solo quelle mancanti. Tre risultati riguardavano richieste di VOTO NEGATIVO o MODIFICA relative a indicazioni di cui già disponevamo:

• Il nostro gruppo ha indicatoAGENTS.md agli agenti di applicare la modifica a tutto il repository allint:fix momento di modificare le regole di lint. Tre persone avevano messo in guardia separatamente da questa pratica: il repository non supera il controllo di lint nella versione di base, pertanto una correzione a livello di intero repository nasconde il vostro diff tra modifiche di formattazione non pertinenti.
• Si tratta di una skill condivisa che, secondo quanto indicato, dovrebbe ricorrere all’API in caso di erroregh pr edit. Tuttavia, non si verifica alcun errore: viene visualizzato un avviso non critico, viene restituito un codice di uscita pari a 0 e la richiesta di pull rimane invariata. Un meccanismo di fallback basato su un errore che non si verifica mai non viene mai eseguito. Tre autori hanno riscontrato questo problema in tre diversi repository.
• Un avviso già presente nella documentazione del nostro agente definiva “sicuro” un errore nel database, poiché questo generava immediatamente un errore. Tre persone lo avevano commesso su tre tabelle diverse. In un caso, l’errore era passato il controllo di qualità, aveva superato la verifica CI e si era verificato solo in fase di esecuzione.

Alcune regole concordate rientravano in un controllo automatico. L’avviso relativo al database riportato sopra è verificabile automaticamente: un test che analizzi lo schema porrebbe fine all’intera classe, mentre la documentazione si limita a segnalare il problema. La regola «Non modificare mai manualmente il file dello schema generato» è stata concordata come vera e rimane ancora in sospeso, poiché la formulazione testuale non costituisce un metodo di applicazione adeguato. Altri due punti concordati erano già stati redatti come procedure dettagliate, il che li rende competenze. Diversi punti sono stati rimossi dalla votazione e trasformati in ticket anziché in documentazione.

Una regola può rappresentare un comportamento predefinito e tuttavia richiedere di essere messa per iscritto. Due persone avevano scritto, indipendentemente l’una dall’altra, «non effettuare mai un commit né un push a meno che non venga richiesto». Uno di loro lo ha espresso al meglio: «scrivere i file non equivale ad avere il permesso di effettuare il commit». Qualsiasi agente dovrebbe già comportarsi in questo modo. Due persone lo hanno messo per iscritto perché la situazione continuava comunque a verificarsi, il che costituisce l’argomento a favore di renderlo esplicito.

Durante il processo di raccolta è stato individuato un errore nel processo stesso. Ciascun pacchetto riportava un timbro di versione, per cui il sistema di revisione si rifiutava di confrontare pacchetti generati da regole di raccolta diverse. Il timbro derivava dalla versione del plugin, non da quella dell’esportatore. Tutti e cinque i pacchetti erano stati generati da script identici a livello di byte e contrassegnati con tre versioni diverse. Il meccanismo di sicurezza non avrebbe mai potuto attivarsi in caso di una reale modifica delle regole, mentre si sarebbe attivato in occasione di ogni aggiornamento del plugin non correlato. Tale correzione era una delle quindici.

Con quale frequenza eseguirlo

Il primo raccolto è quello più impegnativo: mesi di appunti personali, sintetizzati in un’unica sessione intensiva. Dopodiché, durante le riunioni periodiche di sincronizzazione del team, dedichate cinque minuti a una verifica veloce in piedi: c’è qualcosa di nuovo che più di una persona ha annotato?

Cinque modalità di guasto da tenere in considerazione in fase di progettazione:

• Solo scrittura: le regole vengono promosse e nessuno verifica se il comportamento dell’agente sia cambiato.
• Obsoleta e senza proprietario: una regola condivisa sopravvive al codice che descrive.
• Promozione su n=1: l’opinione decisa di una sola persona diventa una regola del gruppo semplicemente perché è stata la prima a esprimerla.
• Un unico documento che racchiude quattro tipi di contenuti: norme generali, procedure, riferimenti e cronistoria, il tutto in un unico file che nessuno legge dall’inizio alla fine.
• Astratta al punto da diventare inutile: una regola generalizzata a tal punto rispetto all’evento che l’ha determinata da non indicare più all’agente cosa fare.

Eseguirne uno manualmente

Non sono necessari strumenti speciali. Il nostro file di esportazione era un piccolo script, ma ogni fase può essere eseguita manualmente:

1. Esportazione in forma riservata. Ciascuna persona copia la propria cartella di memoria automatica (in Claude Code, ~/.claude/projects/<project>/memory/), le proprie e~/.claude/CLAUDE.md le eventuali abilità personali in una cartella individuale per persona.
2. Effettuare una revisione prima della condivisione. Ciascuno deve eliminare tutto ciò che non deve essere divulgato: credenziali, dati dei clienti, qualsiasi informazione relativa a un collega specifico. Nulla deve essere diffuso senza che il titolare abbia prima letto il contenuto.
3. Raggruppamento in base al significato. Un revisore, sia esso una persona o un agente, raggruppa le voci che esprimono lo stesso concetto con parole diverse e registra chi ha redatto ciascuna di esse.
4. Contare gli autori distinti. Si considera candidato chiunque abbia due o più autori indipendenti. Unire i dispositivi di una stessa persona, escludere il testo condiviso a monte e prendere nota di quali cluster rimangono senza il vostro utente più attivo.
5. Classificare e instradare. Assegnare a ciascun candidato l’etichetta ADD, UPVOTE, DOWNVOTE o EDIT, quindi indicarne la destinazione in base alla tabella di instradamento riportata sopra.
6. Elencate le contraddizioni separatamente. Risolvete quelle relative all’ambito di applicazione, ove possibile; lasciate irrisolte le altre e specificatelo.
7. Si proceda alla votazione dell’assemblea. Si riportino le proposte su una pagina, i dati forniti da un unico autore su una seconda, e si decida di comune accordo.
8. Trattate ogni promozione come una campagna di pubbliche relazioni a sé stante rispetto al repository a cui si riferisce. Mantenete i pacchetti grezzi fuori dal ramo principale.

Domande frequenti

Che cos’è un “memory harvest”?

La “raccolta delle memorie” è una pratica di gruppo per gli agenti di programmazione basati sull’intelligenza artificiale: ogni sviluppatore esporta le memorie private del proprio agente e le proprie regole personali; un revisore raggruppa le voci presenti nelle esportazioni di tutti i partecipanti e le regole che diverse persone hanno scritto in modo indipendente vengono trasferite in file condivisi quali oCLAUDE.md AGENTS.md. Si tratta della fase di manutenzione a livello di team nell’ambito dell’ingegneria del contesto.

Quante persone devono dare il proprio consenso affinché una regola venga inserita nel file CLAUDE.md?

Ci avvaliamo di due o più autori indipendenti. Si contano le persone distinte, non i contributi: una persona che ripete una regola tre volte, o che effettua un’esportazione da due dispositivi, è comunque considerata un unico autore. Anche due persone che hanno copiato lo stesso testo pubblicato non sono da considerarsi indipendenti. La soglia stabilisce quali proposte vengono prese in considerazione; il team vota comunque su ogni promozione.

Cosa rientra nell’ambito del team CLAUDE.md e cosa nella memoria personale?

È un dato di fatto che ogni sessione in quel repository debba far parte del progettoCLAUDE.md, poiché viene caricata automaticamente. Le procedure vanno inserite nella sezione “skills”, i dettagli di riferimento nella sezione “docs” con un rimando, e tutto ciò che una macchina può verificare va inserito in una regola di lint o in un test. Le preferenze relative ai propri strumenti, al proprio computer o al proprio budget rimangono personali.

Le regole della squadra dovrebbero essere inserite nel file CLAUDE.md o in quello AGENTS.md?

Le regole che ogni strumento di IA dovrebbe seguire vanno inserite in AGENTS.md; le istruzioni specifiche per Claude vanno inserite in CLAUDE.md. Claude Code è in grado di leggere AGENTS.mddirettamente o tramite un’importazione@AGENTS.md, pertanto un unico file può essere utilizzato per tutti gli strumenti impiegati dal Suo team.

Cosa si fa quando i ricordi di due sviluppatori si contraddicono a vicenda?

Verifichi innanzitutto l’ambito: entrambe le opzioni possono essere valide in repository diversi, e un successivo cambio di strumento potrebbe aver risolto la questione. Se una delle due parti è obsoleta, la sostituisca anziché sovrascriverla. Se la discrepanza riguarda una preferenza piuttosto che un aspetto concreto del codice, la lasci irrisolta e la mantenga nelle regole private di ciascuno.

Con quale frequenza un team dovrebbe eseguire un’operazione di “memory harvest”?

Esegua una sessione limitata nel tempo per smaltire l’arretrato, quindi preveda un controllo rapido di cinque minuti durante una riunione di sincronizzazione periodica del team per individuare nuovi candidati. La prima selezione è quella più onerosa; in seguito, il volume dovrebbe essere ridotto.

Prendete questa decisione in modo collettivo

In un processo di raccolta delle memorie, è il team a decidere quali regole diventino condivise; il revisore si limita a formulare proposte. L’esportazione, il raggruppamento e il conteggio possono essere tutti automatizzati. La votazione, invece, non può e non deve esserlo. Quali regole siano vincolanti per tutti, quali rimangano personali e quali disaccordi rimangano aperti sono decisioni che spettano alle persone che dovranno conviverci. È lo stesso punto che sottolineiamo nel rapporto «Esiste il contenuto, non la stanza»: una visione d’insieme è utile solo quando le persone responsabili delle correzioni decidono di comune accordo.

Si tratta di una retrospettiva basata su input diversi. Quando i nostri agenti di intelligenza artificiale hanno presentato i propri spunti per la retrospettiva, le informazioni provenivano dalle loro sessioni. Questa volta, invece, provenivano dalle nostre note private, e la sala ha svolto lo stesso compito: individuare lo schema, stabilire il livello di dettaglio e assegnare un responsabile a ciascun punto. Se il vostro team organizza già regolarmente una retrospettiva, la raccolta dei ricordi può essere inserita come punto all’ordine del giorno. La procedura completa è descritta nella nostra guida alle retrospettive degli agenti di IA.

Desiderate effettuare una raccolta in autonomia o ritenete che la nostra soglia sia errata? Ci scriva all’indirizzo: ai-discussion@teamretro.com.