Migliori pratiche di CLAUDE.md per i team

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 Suoi colleghi non possono mai accedervi.

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 di raccolta delle memorie: abbiamo messo in comune quei documenti personali e ci siamo chiesti quali regole meritassero di diventare regole del team. Ecco come abbiamo proceduto, quali regole sono state approvate, a quale ambito è stata assegnata ciascuna di esse e cosa abbiamo scoperto, comprese le regole su cui ci siamo sbagliati.

Che cos’è un “raccolto di ricordi”

Una “raccolta di memorie” è un’attività di gruppo articolata in tre fasi. Ciascun partecipante esporta le memorie del proprio agente privato 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 in 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” è 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 set di istruzioni impartiti 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 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 inviate solo le promozioni, ciascuna sotto forma di PR separata rispetto 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.

Si consideri l’utente più assiduo. Un unico bundle conteneva 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ù un altro», e un cluster privo dell’utente più assiduo costituiva una prova più rara e più solida. Abbiamo contrassegnato tali cluster separatamente.

Una persona equivale a un autore. Un sviluppatore 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 di riferimento, pertanto esso è 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 attinto ai 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 file di contesto senza renderli mai 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à è il suo livello: il livello in cui verrà effettivamente letta e applicata. (Il capitolo della nostra guida dedicato a dove dovrebbe essere inserita 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	Un’abilità 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 ferma
Per quanto riguarda le funzioni dell’agente, come i comandi Git o l’interruzione dei processi	Un hook in un plugin condiviso	CI non rileva mai le azioni dell’agente; un hook interrompe il comando
Una preferenza relativa ai propri strumenti, alla propria macchina o al proprio budget	La Sua esperienza personale `CLAUDE.md`o 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 eliminerà la memoria privata solo una volta che la destinazione si sarà caricata automaticamente. Se si sposta una regola in un documento che non viene caricato, l’agente semplicemente la dimentica. Nel caso 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. Risolvete le contraddizioni in base all’ambito d’applicazione, ove possibile, sostituite la parte obsoleta e inserite le divergenze relative alle preferenze in un contenitore esplicito dedicato alle questioni irrisolte.

Verificare 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 definito 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 essere quella obsoleta; pertanto, è quella da sostituire anziché da eliminare in modo discreto.

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. In questo modo, il prossimo revisore potrà 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, 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: undici 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 stesso. Dalla seconda pagina ne sono state approvate altre diciassette: fatti relativi a un singolo autore che la sala 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 in attesa di ulteriori discussioni o di una collocazione più adeguata, e tre sono stati approvati ma necessitano di codice o di una skill anziché di 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 quattro volte: i commenti riportano fatti oggettivi 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 stata messa per iscritto in alcun documento condiviso.

Un cluster correlato, relativo a due autori, riguardava uno stato Git obsoleto: un ramo locale molto indietro rispetto a quello remoto, una ricerca eseguita sul checkout 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 indicazioni errate, non solo quelle mancanti. Tre risultati hanno comportato 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 contro questa pratica: il repository non supera il controllo di lint nella versione di base, pertanto una correzione a livello di 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: la skill visualizza un avviso non critico, termina con codice di uscita 0 e lascia la richiesta di pull 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 repository diversi.
Un avviso già presente nella documentazione del nostro agente definiva “sicuro” un errore nel database poiché generava immediatamente un errore. Tre persone lo avevano commesso su tre tabelle diverse. In un caso, l’errore era passato la revisione, aveva superato il controllo di integrità (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 è lo strumento adeguato per garantirne l’applicazione. Altri due punti concordati erano già stati redatti come procedure dettagliate, il che li rende competenze. Diversi punti sono stati rimandati alla votazione come ticket anziché come 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 dei 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 la raccolta è stato individuato un errore nella raccolta stessa. Ogni bundle riportava un timbro di versione, per cui il processo di revisione si rifiutava di confrontare bundle creati con regole di raccolta diverse. Il timbro derivava dalla versione del plugin, non da quella dell’esportatore. Tutti e cinque i bundle erano stati creati 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 ad 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 coordinamento del team, dedichi cinque minuti a una verifica veloce: 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 contenente quattro tipi di contenuti: norme generali, procedure, riferimenti e cronologia, 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.

Cosa cambieremmo la prossima volta

Il confronto tra il nostro processo e gli strumenti in grado di apprendere autonomamente ha evidenziato quattro lacune. Stiamo inserendo una correzione per ciascuna di esse nell’harvest prima della prossima esecuzione.

Le regole relative alle azioni dell’agente stesso richiedono un hook. Due delle nostre promozioni riguardavano ciò che fa l’agente, non ciò che prevede il codice: i subagenti che effettuavano il commit sul ramo sbagliato e un’interruzione generale del processo che eliminava la shell in cui era in esecuzione. La CI non rileva mai nessuna delle due situazioni. Un hook può interrompere il comando prima che venga eseguito, mentre un plugin condiviso lo distribuisce a tutte le macchine su cui è installato.

Una regola che le persone continuano a imparare a proprie spese non funziona. Si tratta della modalità di errore “solo scrittura” di cui sopra, e un’analisi può rilevarla. Se una regola è stata promossa l’ultima volta e le persone hanno continuato a inserirla nella propria memoria privata anche in seguito, la linea condivisa non sta funzionando. Questo è il segnale per spostarla dal testo in un hook o in un controllo.

Verifichi che un avviso sia ancora valido prima di promuoverlo. Un avviso segnalava un bug attivo che era già stato risolto. Se fosse stato promosso, avrebbe inviato a tutti un avviso errato. Qualsiasi elemento che faccia riferimento a un file, a una funzione o a un bug verrà prima verificato rispetto al codice attuale.

Una raccolta riflette solo ciò che le persone hanno messo per iscritto. Il numero di voci registrate variava da 37 a 251 per persona, il che la dice lunga più su chi prende appunti che su chi incontra difficoltà. La prossima volta, ogni persona potrà innanzitutto chiedere al proprio agente di leggere le trascrizioni delle proprie sessioni recenti ed elencare le correzioni che la memoria non riesce a coprire. Sarà poi lei a decidere quali conservare. Le trascrizioni non verranno incluse nel fascicolo condiviso.

Abbiamo anche valutato la possibilità di affidare l’intero lavoro a un agente: monitorare le sessioni, redigere le proprie regole e caricarle automaticamente. Alcuni strumenti funzionano già in questo modo, e la nostra mappa dei cicli di feedback degli agenti ne include uno. Ciò funziona bene per la configurazione di una singola persona. Per quanto riguarda le regole su cui fa affidamento un intero team, desideriamo comunque che le persone leggano ciascuna di esse e votino.

Eseguirne uno manualmente

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

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.
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 inviato senza che il proprietario lo abbia prima letto.
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.
Contare gli autori distinti. Si considera candidato chi ha 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ù assiduo.
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.
Elencate le contraddizioni separatamente. Risolvete quelle relative all’ambito di applicazione, ove possibile; lasciate irrisolte le altre e specificatelo.
Si proceda alla votazione in aula. Si riportino le proposte su una pagina e i dati forniti da un unico autore su una seconda, e si decida insieme.
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 squadra per gli agenti di programmazione dell’IA: 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 squadra 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, conta comunque come un unico autore. Anche due persone che hanno copiato lo stesso testo pubblicato non sono considerate indipendenti. La soglia determina quali proposte vengono avanzate; 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 rientrare nel 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 nel file 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 vostro 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 ciascun utente.

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 insieme.

Si tratta di una retrospettiva con input diversi. Quando i nostri agenti di intelligenza artificiale hanno presentato i propri punti per la retrospettiva, le informazioni provenivano dalle loro sessioni. Questa volta provenivano dalle nostre note private, e la sala ha svolto lo stesso compito: leggere lo schema, scegliere il livello di dettaglio e assegnare a ogni punto un responsabile. 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.

Volete effettuare una raccolta in autonomia o ritenete che la nostra soglia sia errata? Fatecelo sapere: ai-discussion@teamretro.com.