CLAUDE.md pour les équipes : comment nous avons transformé les souvenirs générés par l'IA de cinq personnes en règles communes

Chaque développeur qui travaille avec un agent de codage IA rédige discrètement un recueil de règles. La mémoire automatique de Claude Code enregistre les notes issues de vos corrections au fur et à mesure de son fonctionnement, votre profil personnel ~/.claude/CLAUDE.mdrecueille les préférences que vous en aviez assez de répéter, et quelques compétences personnelles se développent autour des tâches que vous effectuez chaque semaine. Tout cela reste privé. La mémoire automatique est locale à la machine et propre à chaque dépôt : les agents de vos collègues n’y ont jamais accès.

Ainsi, cinq personnes apprennent la même leçon chacune de leur côté, dans un fichier privé. Les règles dont votre équipe a le plus besoin sont déjà consignées. Elles ne figurent simplement pas dans un document partagé.

En septembre, nous étions cinq à organiser une « récolte de souvenirs » : nous avons rassemblé ces fichiers personnels et nous nous sommes demandé quelles règles méritaient de devenir des règles d’équipe. Voici comment nous nous y sommes pris, quelles règles ont été retenues, où chacune d’entre elles a trouvé sa place, et ce que nous avons découvert, y compris les règles sur lesquelles nous nous étions trompés.

Qu’est-ce qu’une « récolte de souvenirs » ?

Une « récolte de souvenirs » est un exercice d’équipe qui se déroule en trois étapes. Chaque participant exporte les souvenirs de son agent privé ainsi que ses règles personnelles. Un réviseur regroupe les entrées issues des exportations de chacun. Les règles que plusieurs personnes ont consignées indépendamment les unes des autres sont proposées pour les fichiers partagés : le projetCLAUDE.md``AGENTS.md, une compétence partagée ou une validation dans CI.

C’est l’étape de maintenance que l’ingénierie contextuelle omet généralement. Nous avons déjà fait valoir que les fichiers contextuels nécessitent une boucle de rétroaction pilotée par les agents qui les utilisent. Une « récolte » correspond à cette même boucle appliquée aux personnes plutôt qu’aux sessions : il s’agit de la phase 4 du cycle de vie de la rétroaction des agents, qui vise les notes déjà reléguées dans la mémoire privée.

Les outils disponibles à cet effet sont peu nombreux. Sur les dix outils de codage IA que nous avons examinés, seul Devin propose une boucle qui surveille une session, suggère une règle commune et attend qu’un utilisateur l’approuve. Les autres s’appuient soit sur des fichiers rédigés et validés manuellement par les utilisateurs, soit sur des ensembles d’instructions diffusés par un administrateur. Aucun d’entre eux n’exploite les souvenirs personnels de plusieurs personnes pour proposer des règles d’équipe.

Ce que nous avons fait

Le 17 septembre 2026, cinq développeurs ont chacun exécuté un script d’exportation sur leurs propres mémoires Claude Code, leur « global » personnel etCLAUDE.md leurs compétences personnelles. Le script ne transmet aucune donnée. Chacun a lu son propre ensemble de données, a supprimé tout ce qui ne devait pas être transmis, puis l’a soumis.

Les cinq ensembles contenaient 444 entrées de mémoire, 5 CLAUDE.mdfichiers globaux, 13 compétences personnelles et 194 lignes décrivant les compétences installées dans chaque dépôt. Un réviseur, un agent d’IA travaillant aux côtés d’un humain, a regroupé les entrées des cinq ensembles en clusters et a rédigé une proposition pour chaque cluster. Le 22 septembre, quatre d’entre nous ont voté sur deux pages de révision. Les promotions ont été intégrées sous forme de pull requests classiques dans trois dépôts : notre dépôt principal de produit, un dépôt dédié aux jeux et notre plugin de compétences partagé.

Les bundles résident sur une branche qui ne fait jamais l’objet d’une fusion. Seules les promotions en sortent, chacune sous la forme d’une pull request distincte visant le dépôt qu’elle gère, et sont examinées comme n’importe quelle autre modification.

Ce qui permet d’obtenir une promotion : ce sont les auteurs qui comptent, pas les contributions

Une règle est promue lorsque deux personnes ou plus l’ont notée indépendamment les unes des autres. Comptez les auteurs distincts, jamais les entrées. Cette règle a fait l’essentiel du travail, et il a fallu trois ajustements avant de pouvoir s’y fier.

Tenez compte de l’utilisateur intensif. Un ensemble regroupait 251 des 444 entrées, réparties sur 10 référentiels. Tous les autres ont apporté entre 37 et 68 entrées réparties sur 1 à 4 dépôts. Ainsi, « deux auteurs » signifiait généralement « notre plus grand utilisateur de l’agent plus un autre », et un groupe ne comprenant pas ce grand utilisateur constituait une preuve plus rare et plus solide. Nous avons marqué ces groupes séparément.

Une personne correspond à un auteur. Un développeur a exporté des données depuis deux machines. Cela correspond à un auteur. Une personne qui réitère trois fois la même règle, c’est pour insister. Pour corroborer, il faut une deuxième personne.

Les sources partagées ne sont pas indépendantes. Les fichiersCLAUDE.md « global » de ces deux personnes étaient identiques au niveau des octets dans leurs quatre premières sections, car toutes deux avaient repris le même texte publié : les consignes de codage d’Andrej Karpathy pour les agents d’IA. Toutes deux citaient un seul et même document en amont, ce qui a donc été considéré comme une seule source. Tout futur cluster reposant uniquement sur cette paire sera d’abord comparé au libellé source.

Pour classer chaque groupe, nous avons emprunté les quatre opérateurs à ExpeL, une méthode de recherche consacrée aux agents qui apprennent des règles à partir de l’expérience : AJOUTER une nouvelle règle, VOTER POUR une règle déjà présente dans les documents partagés, VOTER CONTRE une règle contredite par les preuves, MODIFIER une règle qui s’en rapproche mais qui est erronée. Le « downvote » et la modification sont tout aussi importants que l’ajout. Une collecte qui ne sait qu’ajouter des règles ne fait qu’allonger vos fichiers de contexte sans jamais les rendre plus corrects.

C’est le seuil qui détermine ce que le relecteur propose, et non ce que l’équipe est susceptible d’adopter. Une deuxième page de relecture répertoriait les faits rédigés par un seul auteur qui semblaient mériter d’être partagés, et l’assemblée a voté sur chacun d’entre eux. Ils ont été retenus parce que les participants les ont lus et se sont mis d’accord.

Où chaque règle doit-elle être placée ?

S’accorder sur une règle, c’est déjà la moitié du chemin. L’autre moitié, c’est son niveau hiérarchique : le niveau auquel elle sera effectivement lue et appliquée. (Notre chapitre du guide consacré à la place qu’une correction doit occuper aborde ce sujet dans son intégralité.) Pour les règles extraites, voici la table de routage que nous avons utilisée :

La règle est la suivante :	Cela se trouve dans	Pourquoi ?
À chaque session, ce dépôt nécessite impérativement	Le projet CLAUDE.md	Il se charge au début de chaque session
Il en va de même pour tous les outils d’IA utilisés par l’équipe	AGENTS.md, importé depuis CLAUDE.md	Un fichier lisible par tous les outils
Ne concerne qu’une partie du code source	Une règle à portée de chemin dans .claude/rules/	Ne se charge que lorsque l’agent détecte des fichiers correspondants
Une procédure utilisée dans plusieurs dépôts	Une compétence dans un plugin partagé	Les plugins apportent des compétences, et non CLAUDE.md
Une procédure spécifique à un dépôt	Une compétence de repo	Se charge lorsque la tâche l’exige
Les détails de la référence sont trop longs pour chaque session	Un document, ainsi qu’un pointeur d’une ligne dans CLAUDE.md	Un document qui ne se charge pas est un document que l’agent ne lit jamais
Vérifiable mécaniquement	Une règle Lint, un test ou une vérification CI	La prose met en garde ; un chèque y met fin
Une préférence concernant vos propres outils, votre machine ou votre budget	Votre vie personnelle CLAUDE.mdou vos souvenirs	Ce n’est pas un fait concernant le code source

Deux points méritent d’être soulignés. Premièrement, un plugin Claude Code peut fournir des compétences, des agents et des hooks, mais pas de procéduresCLAUDE.md. Les procédures s’appliquent à plusieurs dépôts au sein d’un plugin ; les règles générales doivent donc être définies dans chaque dépôt qui en a besoin.

Deuxièmement, ne supprimez la mémoire privée qu’une fois que la destination s’est chargée automatiquement. Si vous déplacez une règle vers un document qui ne se charge jamais, l’agent l’oublie tout simplement. Lorsqu’une règle était placée dans des documents de référence, la mémoire privée se réduisait à un pointeur au lieu de disparaître.

Comment gérer les contradictions ?

Les mémoires mises en commun présentent des divergences. Résolvez les contradictions en fonction de la portée lorsque cela est possible, remplacez la partie obsolète et placez les divergences liées aux préférences dans un ensemble explicite de données non résolues.

Vérifiez d’abord le champ d’application. Une contradiction portait sur la manière de configurer les dépendances dans une deuxième copie de travail d’un dépôt : deux personnes avaient rédigé des règles opposées. Les deux étaient valables dans leur propre dépôt. Une modification ultérieure apportée à une compétence partagée avait depuis réglé la question pour les deux, et il s’est avéré que la règle de notre utilisateur le plus assidu était celle qui n’était plus à jour ; c’est donc celle-ci qu’il convient de remplacer plutôt que de la supprimer discrètement.

Remplacez, ne remplacez jamais par-dessus. Lorsqu’une règle partagée change, ajoutez la nouvelle règle en indiquant la date et veillez à ce que l’ancienne reste lisible, de la même manière qu’un compte rendu de décision architecturale remplace une décision antérieure. Le prochain relecteur pourra ainsi voir ce qui a changé et pourquoi.

Conserver un point en suspens. La deuxième contradiction portait sur le modèle d’IA que les sous-agents devaient utiliser. Deux personnes souhaitaient un modèle de premier plan pour chaque sous-agent ; une autre proposait de choisir les modèles en fonction de la tâche. Le vote s’est réparti en deux « à discuter » et deux « d’accord ». La question est restée délibérément en suspens, car elle concerne le montant que chaque personne est prête à dépenser de sa propre poche, et non un aspect technique du code source. Elle relève des règles privées de chacun.

Ce que la récolte a révélé

Quinze promotions ont été validées à l’issue de la première page de révision : 11 pour notre dépôt de produits principal (dont deux concernaient également le dépôt des jeux), trois pour le plugin de compétences partagées, et une corrigeant l’exportateur propre à Harvest. Dix-sept autres ont été validées à partir de la deuxième page : des faits rédigés par un seul auteur que l’assemblée a accepté de partager, ainsi que deux groupes que le premier décompte avait erronément enregistrés comme provenant d’un seul auteur. Sur la deuxième page, un élément a été rejeté, trois ont été mis en attente pour faire l’objet d’une discussion plus approfondie ou pour trouver un emplacement plus approprié, et trois ont été approuvés mais nécessitent du code ou une compétence plutôt qu’une simple ligne de documentation. La question relative au modèle est restée en suspens.

Le thème le plus souvent cité concernait les commentaires. Trois auteurs, dont l’un l’avait noté à quatre reprises, ont indiqué que les commentaires énoncent des faits durables concernant le code ; ils ne décrivent jamais la modification ni son historique. Un auteur a fait remarquer que les sous-agents en sont généralement responsables.

La critique la plus générale portait sur les preuves. Quatre des cinq auteurs avaient rédigé une version du principe suivant : « Vérifiez avant d’affirmer ; une recherche infructueuse ne prouve pas l’absence d’un phénomène. » Les affirmations des relecteurs sont des hypothèses, et le fait de ne pas parvenir à reproduire un bug ne prouve pas que celui-ci ne puisse pas se produire. C’était ce qui se rapprochait le plus d’une règle interne commune à l’équipe, mais elle n’était consignée nulle part de manière partagée.

Un ensemble d’incidents connexes, signalés par deux auteurs, concernait un état Git obsolète : une branche locale très en retard par rapport à la branche distante, une recherche effectuée sur une version incorrecte. Chacun de ces cinq incidents a donné lieu à une affirmation erronée, mais présentée avec certitude, qui s’est retrouvée dans un message de commit ou dans la description d’une pull request.

La collecte porte sur les recommandations erronées qui ont été corrigées, et pas seulement sur celles qui manquaient. Trois constatations concernaient des demandes de « VOTE NÉGATIF » ou de « MODIFICATION » portant sur des recommandations dont nous disposions déjà :

• Notre guide commun indiquaitAGENTS.md aux contributeurs d’appliquer la modification à l’ensemble du dépôt lorslint:fix de la modification des règles de lint. Trois personnes avaient mis en garde séparément contre cette pratique : le dépôt ne passe pas le lint avec succès à l’état initial ; par conséquent, une correction à l’échelle du dépôt noie votre diff sous des modifications de formatage sans rapport.
• Une compétence partagée qui, en théorie, devrait se rabattre sur l’API en cas d’échecgh pr edit. Or, elle ne plante pas : elle affiche un message d’avertissement non critique, renvoie un code de sortie 0 et laisse la pull request inchangée. Un mécanisme de repli basé sur un échec qui ne se produit jamais ne s’exécute donc jamais. Trois auteurs ont rencontré ce problème dans trois dépôts différents.
• Une mise en garde figurant déjà dans la documentation de notre agent qualifiait une erreur de base de données de « sans danger », car elle provoquait une erreur immédiate. Trois personnes avaient rencontré cette erreur sur trois tables différentes. Dans un cas précis, l’erreur avait passé la phase de révision, avait été validée par l’intégration continue (CI) et n’avait provoqué un plantage qu’au moment de l’exécution.

Certaines règles convenues relevaient d’une vérification automatique. L’avertissement de la base de données ci-dessus est vérifiable automatiquement : un test lisant le schéma mettrait fin à l’ensemble de la classe, alors que la documentation se contente d’émettre un avertissement à ce sujet. La règle « Ne modifiez jamais manuellement le fichier de schéma généré » a été reconnue comme vraie mais reste en attente, car un simple texte ne constitue pas un moyen d’application adéquat. Deux autres points approuvés avaient déjà été rédigés sous forme de procédures étape par étape, ce qui en fait des compétences. Plusieurs points ont quitté le vote sous forme de tickets plutôt que de documentation.

Une règle peut correspondre à un comportement par défaut tout en nécessitant d’être formulée. Deux personnes avaient écrit, indépendamment l’une de l’autre : « Ne jamais effectuer de commit ni de push sans y avoir été invité ». L’une d’elles l’a très bien formulé : « Le fait d’écrire des fichiers ne donne pas le droit de les valider. » Tout agent devrait déjà se comporter ainsi. Ces deux personnes l’ont noté parce que cela continuait de se produire malgré tout, ce qui justifie de le préciser explicitement.

Le processus de collecte a détecté une erreur au sein même de ce processus. Chaque bundle comportait un horodatage de version, de sorte que le contrôle refusait de comparer des bundles créés selon des règles de collecte différentes. Cet horodatage provenait de la version du plugin, et non de celle de l’exportateur. Les cinq bundles avaient tous été créés à partir de scripts identiques au niveau des octets, mais portaient trois versions différentes. Le mécanisme de sécurité ne pouvait jamais se déclencher en cas de véritable modification des règles, mais se déclenchait à chaque mise à jour de plugin sans rapport avec celles-ci. Cette correction faisait partie des quinze.

À quelle fréquence faut-il l’exécuter ?

La première récolte est celle qui coûte le plus cher : des mois de notes personnelles, traitées en une seule séance intensive. Par la suite, prévoyez un point rapide de cinq minutes lors de chaque réunion d’équipe : y a-t-il des éléments nouveaux que plusieurs personnes ont notés ?

Cinq modes de défaillance à prendre en compte lors de la conception :

• En écriture seule : les règles sont mises en œuvre et personne ne vérifie si le comportement de l’agent a changé.
• Obsolète et sans propriétaire : une règle partagée survit au code qu’elle décrit.
• « Promu sur la base de n=1 » : l’opinion tranchée d’une seule personne devient une règle d’équipe simplement parce qu’elle a été la première à l’exprimer.
• Un seul document regroupant quatre types de contenu : les règles générales, les procédures, les références et l’historique, le tout dans un fichier que personne ne lit du début à la fin.
• Abstrait au point d’en devenir inutile : une règle tellement éloignée de l’incident qui l’a motivée qu’elle n’indique plus à l’agent ce qu’il doit faire.

Exécutez-en un manuellement

Vous n’avez pas besoin d’outils spécifiques. Notre exportation consistait en un petit script, mais chaque étape peut être effectuée manuellement :

1. Exportation en toute confidentialité. Chaque personne copie son dossier de mémoire automatique (dans Claude Code, ~/.claude/projects/<project>/memory/), ~/.claude/CLAUDE.mdainsi que ses compétences personnelles, dans un dossier individuel.
2. Vérifiez le contenu avant de le partager. Chacun supprime tout ce qui ne doit pas être diffusé : identifiants, coordonnées des clients, toute information concernant un collègue nommé. Rien ne doit être transmis sans que son auteur ne l’ait lu au préalable.
3. Regroupez par sens. Un réviseur, qu’il s’agisse d’une personne ou d’un agent, regroupe les entrées qui expriment la même idée avec des mots différents et note qui a rédigé chacune d’entre elles.
4. Comptez le nombre d’auteurs distincts. Un candidat est défini comme un groupe comportant au moins deux auteurs indépendants. Regroupez les machines d’une même personne, ne tenez pas compte du texte partagé en amont, puis notez quels groupes subsistent lorsque vous excluez votre utilisateur le plus actif.
5. Classer et acheminer. Attribuez à chaque élément candidat l’étiquette « ADD », « UPVOTE », « DOWNVOTE » ou « EDIT », puis attribuez-lui une destination à partir de la table d’acheminement ci-dessus.
6. Énumérez les contradictions séparément. Résolvez-les en fonction de leur portée lorsque cela est possible ; laissez les autres non résolues et précisez-le.
7. Mettons tout le monde au vote. Rassemblez les propositions sur une page, les faits présentés par un seul auteur sur une autre, puis décidez ensemble.
8. Traitez chaque promotion comme une opération de relations publiques distincte par rapport au dépôt qu’elle concerne. Ne placez pas les paquets bruts dans le brancher principal.

Foire aux questions

Qu’est-ce qu’une « récolte de souvenirs » ?

Une « récolte de mémoires » est une pratique d’équipe destinée aux agents de codage IA : chaque développeur exporte les mémoires de son agent privé ainsi que ses règles personnelles ; un réviseur regroupe ensuite les entrées issues des exportations de chacun, et les règles rédigées indépendamment par plusieurs personnes sont transférées vers des fichiers partagés tels que CLAUDE.mdou AGENTS.md. Il s’agit de l’étape de maintenance au niveau de l’équipe dans le cadre de l’ingénierie contextuelle.

Combien de personnes doivent donner leur accord avant qu’une règle ne soit intégrée dans CLAUDE.md ?

Nous faisons appel à au moins deux auteurs indépendants. Comptez les personnes distinctes, et non les contributions : une personne qui reformule une règle trois fois, ou qui effectue une exportation à partir de deux machines, compte toujours pour un seul auteur. Deux personnes ayant copié le même texte publié ne sont pas non plus considérées comme indépendantes. Le seuil détermine ce qui est proposé ; l’équipe vote néanmoins sur chaque promotion.

Qu’est-ce qui relève de la base de données d’équipe CLAUDE.md et qu’est-ce qui relève de la mémoire personnelle ?

Les éléments immuables de chaque session de ce dépôt doivent figurer dans le projetCLAUDE.md, car celui-ci se charge automatiquement. Les procédures sont classées dans la section « compétences », les détails de référence dans la section « documentation » avec un lien, et tout ce qu’une machine peut vérifier est intégré dans une règle de lint ou un test. Vos préférences concernant vos propres outils, votre machine ou votre budget restent personnelles.

Les règles de l’équipe doivent-elles figurer dans le fichier CLAUDE.md ou dans le fichier AGENTS.md ?

Les règles que chaque outil d’IA doit respecter sont à indiquer ici AGENTS.md; les instructions spécifiques à Claude restent iciCLAUDE.md. Claude Code peut lire ces fichiers directementAGENTS.md ou via une importation@AGENTS.md ; un seul fichier peut ainsi servir à tous les outils utilisés par votre équipe.

Que faites-vous lorsque les souvenirs de deux développeurs se contredisent ?

Vérifiez d’abord le contexte : les deux peuvent être valables dans des dépôts différents, et un changement d’outil ultérieur a peut-être résolu le problème. Si l’une des deux versions est obsolète, remplacez-la plutôt que de la réécrire. Si le désaccord porte sur une préférence plutôt que sur un élément concret du code, ne le résolvez pas et conservez-le dans les règles privées de chaque personne.

À quelle fréquence une équipe devrait-elle procéder à une « récolte de souvenirs » ?

Organisez une session limitée dans le temps pour traiter l’arriéré, puis prévoyez un point rapide de cinq minutes lors d’une réunion de synchronisation régulière de l’équipe pour identifier de nouveaux candidats. La première sélection est celle qui coûte le plus cher ; par la suite, le volume devrait être faible.

Faites-en une décision collective

Lors d’une collecte de souvenirs, c’est l’équipe qui décide quelles règles seront partagées ; le réviseur se contente de faire des propositions. L’exportation, le regroupement et le comptage peuvent tous être automatisés. Le vote, en revanche, ne peut pas l’être, et ne doit pas l’être. Quelles règles s’imposent à tous, lesquelles restent personnelles, et quels désaccords restent en suspens : ce sont là des décisions qui reviennent aux personnes qui devront vivre avec. C’est le même argument que nous avançons dans le rapport « Ce qui existe, c’est le rapport, pas la salle » : une vue d’ensemble n’est utile que lorsque les personnes responsables des corrections prennent une décision commune.

Il s’agit d’une rétrospective avec des sources d’information différentes. Lorsque nos agents IA ont soumis leurs propres éléments de rétrospective, les données provenaient de leurs sessions. Cette fois-ci, elles provenaient de nos propres notes privées, et la salle a rempli le même rôle : analyser la tendance, déterminer le niveau d’importance et attribuer un responsable à chaque point. Si votre équipe organise déjà régulièrement des rétrospectives, une « récolte de souvenirs » peut s’intégrer comme point à l’ordre du jour. La méthode complète est décrite dans notre guide consacré aux rétrospectives des agents IA.

Vous avez réalisé votre propre récolte, ou vous pensez que notre seuil est erroné ? Faites-le-nous savoir : ai-discussion@teamretro.com.