CLAUDE.md voor teams: hoe wij de AI-herinneringen van vijf personen hebben omgezet in gedeelde regels

Elke ontwikkelaar die met een AI-codeeragent werkt, stelt in stilte een regelboek op. Het automatische geheugen van Claude Code slaat tijdens het werken aantekeningen op van uw correcties, uw persoonlijke instellingen ~/.claude/CLAUDE.mdverzamelen de voorkeuren die u niet steeds opnieuw wilt herhalen, en er ontstaan enkele persoonlijke vaardigheden rondom de taken die u wekelijks uitvoert. Dit alles is privé. Het automatische geheugen is lokaal op de machine en per repository: de agents van uw teamgenoten krijgen dit nooit te zien.

Vijf mensen leren dus elk afzonderlijk dezelfde les, elk in een eigen bestand. De regels die uw team het hardst nodig heeft, staan al opgeschreven. Ze staan alleen nog niet op een plek die voor iedereen toegankelijk is.

In september hebben wij met vijf personen een ‘herinneringsoogst’ gehouden: wij hebben die persoonlijke dossiers gebundeld en ons afgevraagd welke regels het waard waren om tot teamregels te worden verheven. Hieronder leest u hoe wij te werk zijn gegaan, welke regels de selectie hebben gehaald, waar elke regel terechtkwam en wat wij hebben ontdekt, inclusief de regels die wij verkeerd hadden ingeschat.

Wat een herinneringen zijn er toch te verzamelen

Een ‘memory harvest’ is een teamoefening die uit drie stappen bestaat. Iedereen exporteert zijn of haar eigen agentherinneringen en persoonlijke regels. Eén beoordelaar groepeert de items uit de exportbestanden van alle deelnemers. De regels die door meerdere personen onafhankelijk van elkaar zijn opgeschreven, worden voorgesteld voor de gedeelde bestanden: het projectCLAUDE.md, AGENTS.md, een gedeelde vaardigheid of een check-in in CI.

Het is de onderhoudsstap die bij contextengineering doorgaans overgeslagen wordt. Wij hebben eerder betoogd dat contextbestanden een feedbacklus nodig hebben die wordt aangestuurd door de agenten die er gebruik van maken. Een ‘harvest’ is dezelfde lus, maar dan toegepast op mensen in plaats van op sessies: het is fase 4 van de feedbackcyclus van de agent, gericht op de aantekeningen die al in het persoonlijke geheugen zijn achtergebleven.

De tooling hiervoor is beperkt. Van de tien AI-programmeertools die wij hebben onderzocht, biedt alleen Devin een lus die een sessie volgt, een gedeelde regel voorstelt en wacht tot een mens deze goedkeurt. De overige tools zijn afhankelijk van bestanden die mensen met de hand schrijven en vastleggen, of van instructiesets die een beheerder doorgeeft. Geen enkele daarvan put uit de persoonlijke herinneringen van meerdere personen om kandidaat-teamregels te genereren.

Wat wij hebben gedaan

Op 17 september 2026 voerden vijf ontwikkelaars elk een exportscript uit op hun eigen Claude Code-herinneringen, hun persoonlijke globale gegevens enCLAUDE.md hun persoonlijke vaardigheden. Het script verzendt niets. Iedereen las zijn of haar eigen bundel door, verwijderde alles wat niet mocht worden verzonden en verstuurde deze pas daarna.

De vijf bundels bevatten 444 geheugenvermeldingen, 5 globale CLAUDE.mdbestanden, 13 persoonlijke vaardigheden en 194 rijen waarin de in elke repository geïnstalleerde vaardigheden werden beschreven. Eén beoordelaar, een AI-agent die samenwerkte met een mens, groepeerde de vermeldingen over alle vijf bundels heen en stelde voor elk cluster een voorstel op. Op 22 september hebben vier van ons gestemd op twee beoordelingspagina’s. De promoties werden als gewone pull-verzoeken in drie repositories opgenomen: onze hoofdproductrepository, een gamesrepository en onze gedeelde vaardighedenplugin.

De bundels bevinden zich op een branch die nooit wordt samengevoegd. Alleen de promoties worden doorgevoerd, elk als een afzonderlijke PR voor de repository waarop zij betrekking hebben, en worden net als elke andere wijziging beoordeeld.

Wat telt voor promotie: het aantal auteurs, niet het aantal inzendingen

Een regel wordt gepromoveerd wanneer twee of meer personen deze onafhankelijk van elkaar hebben opgeschreven. Tel het aantal verschillende auteurs, nooit het aantal vermeldingen. Deze ene regel heeft het grootste deel van het werk verricht, en er waren drie aanpassingen nodig voordat men erop kon vertrouwen.

Houd rekening met de intensieve gebruiker. Eén bundel bevatte 251 van de 444 vermeldingen, verspreid over 10 repositories. Alle anderen leverden 37 tot 68 vermeldingen in, verdeeld over 1 tot 4 repositories. „Twee auteurs” betekende dus doorgaans „onze grootste gebruiker van de agent plus één”, en een cluster zonder deze grote gebruiker was zeldzamer en vormde sterker bewijs. Wij hebben die clusters apart gemarkeerd.

Eén persoon is één auteur. Eén ontwikkelaar die gegevens heeft geëxporteerd vanaf twee computers. Dat is één auteur. Wanneer één persoon dezelfde regel driemaal herhaalt, is dat ter benadrukking. Voor bevestiging is een tweede persoon nodig.

Gedeelde bronnen zijn niet onafhankelijk. De globale bestandenCLAUDE.md van beide personen waren in de eerste vier secties byte-voor-byte identiek, omdat beiden dezelfde gepubliceerde tekst hadden overgenomen: de codeerrichtlijnen van Andrej Karpathy voor AI-agenten. Beiden citeerden één document uit de upstream, zodat dit als één enkele bron werd beschouwd. Elk toekomstig cluster dat uitsluitend op dat paar berust, wordt eerst getoetst aan de bewoordingen van het bronmateriaal.

Om elk cluster te classificeren hebben wij de vier operatoren overgenomen uit ExpeL, een onderzoeksmethode voor agenten die regels leren uit ervaring: TOEVOEGEN van een nieuwe regel, UPVOTE voor een regel die al in de gedeelde documenten staat, DOWNVOTE voor een regel die in tegenspraak is met het bewijsmateriaal, BEWERKEN van een regel die er dichtbij zit maar onjuist is. Downvote en edit zijn net zo belangrijk als add. Een ‘harvest’ die alleen regels kan toevoegen, maakt uw contextbestanden langer, maar nooit correcter.

De drempel bepaalt wat de recensent voorstelt, niet wat het team eventueel aanneemt. Op een tweede beoordelingspagina stonden de bijdragen van één auteur vermeld die de moeite waard leken om te delen, en de aanwezigen stemden over elk daarvan. Ze werden opgenomen omdat de mensen ze hadden gelezen en het ermee eens waren.

Waar elke regel thuishoort

Het overeenkomen van een regel is de helft van de beslissing. De andere helft betreft het niveau waarop de regel daadwerkelijk wordt gelezen en toegepast. (In het hoofdstuk van onze handleiding over waar een aanpassing moet worden doorgevoerd, wordt deze ladder uitgebreid behandeld.) Voor de verzamelde regels hebben wij de volgende routeringstabel gebruikt:

De regel luidt als volgt:	Het hoort thuis in	Waarom
Een vaststaand feit is dat elke sessie in deze repository	Het project CLAUDE.md	Het wordt aan het begin van elke sessie geladen
Hetzelfde geldt voor elke AI-tool die het team gebruikt	AGENTS.md, geïmporteerd uit CLAUDE.md	Eén bestand dat door elk programma kan worden gelezen
Alleen van toepassing op een deel van de codebase	Een regel met een pad-bereik in .claude/rules/	Wordt alleen geladen wanneer de agent overeenkomende bestanden aanraakt
Een procedure die in meerdere repositories wordt toegepast	Een vaardigheid in een gedeelde plug-in	Plug-ins bevatten vaardigheden, niet CLAUDE.md
Een procedure die specifiek is voor één repo	Een repo-vaardigheid	Wordt geladen wanneer de taak dit vereist
De referentiegegevens zijn te lang om bij elke sessie te vermelden	Een document, plus een aanwijzing van één regel in CLAUDE.md	Een document dat niet wordt geladen, is een document dat de agent nooit leest
Mechanisch controleerbaar	Een Lint-regel, test of CI-controle	Proza waarschuwt; een controle houdt het tegen
Een voorkeur met betrekking tot uw eigen gereedschap, machine of budget	Uw persoonlijke CLAUDE.mdof herinnering	Dit is geen feit met betrekking tot de codebase

Er zijn twee punten die extra aandacht verdienen. Ten eerste kan een Claude Code-plugin vaardigheden, agents en hooks bevatten, maar geen proceduresCLAUDE.md. Procedures gelden voor meerdere repositories binnen een plugin; vaste regels moeten worden opgenomen in elke repository waarvoor ze nodig zijn.

Ten tweede: verwijder het privégeheugen pas zodra de bestemming automatisch wordt geladen. Als u een regel naar een document verplaatst dat niet wordt geladen, vergeet de agent deze simpelweg. Wanneer een regel in referentiedocumenten werd opgenomen, kromp het privégeheugen in tot een pointer in plaats van dat het verdween.

Hoe om te gaan met tegenstrijdigheden

De verzamelde herinneringen spreken elkaar tegen. Los een tegenstrijdigheid waar mogelijk op basis van het toepassingsgebied op, vervang de verouderde versie en plaats meningsverschillen over voorkeuren in een expliciete, onopgeloste categorie.

Controleer eerst het toepassingsgebied. Er was één tegenstrijdigheid over de manier waarop afhankelijkheden in een tweede werkkopie van een repository moesten worden ingesteld: twee personen hadden tegengestelde regels opgesteld. Beide regels waren correct binnen hun eigen repository. Een latere wijziging in een gedeelde skill had dit inmiddels voor beiden opgelost, en het bleek dat de versie van onze meest intensieve gebruiker verouderd was; daarom dient deze te worden vervangen in plaats van stilletjes te worden verwijderd.

Vervang, maar overschrijf nooit. Wanneer een gedeelde regel wordt gewijzigd, voeg dan de nieuwe regel toe met een datum en zorg ervoor dat de oude regel leesbaar blijft, net zoals een verslag van een architectuurbeslissing een eerdere beslissing vervangt. De volgende beoordelaar kan dan zien wat er is gewijzigd en waarom.

Houd een onbesliste categorie aan. De tweede tegenstrijdigheid betrof de vraag welk AI-model de subagenten moesten gebruiken. Twee personen wilden één topmodel voor elke subagent; één persoon koos modellen op basis van de taak. De stemming leverde twee stemmen voor „bespreken“ en twee voor „akkoord“ op. Het bleef met opzet onopgelost, omdat het gaat om de vraag hoeveel elke persoon bereid is uit eigen zak te betalen, en niet om een feit dat in de codebase vastligt. Het blijft opgenomen in de persoonlijke regels van elke persoon.

Wat er bij de oogst werd aangetroffen

Vijftien promoties werden goedgekeurd vanaf de eerste beoordelingspagina: 11 voor onze hoofdproductrepository (waarvan er twee ook van toepassing waren op de games-repository), drie voor de ‘shared skills’-plugin en één ter correctie van de eigen exporter van Harvest. Vanaf de tweede pagina werden er nog zeventien goedgekeurd: feiten van één auteur die de groep bereid was te delen, plus twee clusters die bij de eerste telling ten onrechte als ‘één auteur’ waren geregistreerd. Op de tweede pagina werd één item afgewezen, werden er drie in de wacht gezet voor verdere bespreking of een geschiktere plaats, en werden er drie goedgekeurd, maar waarvoor code of een skill nodig is in plaats van een regel in de documentatie. De modelvraag bleef openstaan.

De meest terugkerende themagroep had betrekking op opmerkingen. Drie auteurs, van wie er één dit vier keer had opgeschreven: opmerkingen bevatten harde feiten over de code; zij geven nooit een beschrijving van de wijziging of de geschiedenis ervan. Eén auteur merkte op dat subagenten hier doorgaans de boosdoeners zijn.

De meest algemene opmerking had betrekking op bewijs. Vier van de vijf auteurs hadden een variant geschreven van „controleer alvorens te beweren; een mislukte zoekopdracht is geen bewijs van afwezigheid.” Beweringen van recensenten zijn hypothesen, en het feit dat een bug niet kan worden gereproduceerd, bewijst niet dat deze niet kan voorkomen. Het was het dichtstbijzijnde dat het team had bij een gezamenlijke huisregel, en het was nergens opgeschreven waar iedereen er toegang toe had.

Een verwante reeks incidenten, afkomstig van twee auteurs, had betrekking op een verouderde Git-status: een lokale branch die ver achterliep op de remote, een zoekopdracht die op de verkeerde checkout werd uitgevoerd. Elk van de vijf incidenten leidde tot een overtuigende, maar onjuiste bewering die in een commitbericht of de beschrijving van een PR terechtkwam.

Het opsporen van gecorrigeerde onjuiste richtlijnen, niet alleen van ontbrekende richtlijnen. Drie bevindingen betroffen verzoeken om een NEGATIEVE STEM of BEWERKING met betrekking tot richtlijnen die wij al hadden:

• Onze shared AGENTS.mdheeft de medewerkers opgedragen om lint:fixbij het wijzigen van lint-regels de repo-brede aanpassing uit te voeren. Drie personen hadden hier afzonderlijk voor gewaarschuwd: de repo voldoet bij aanvang niet aan de lint-normen, waardoor een repo-brede aanpassing uw diff overschaduwt met niet-relevante opmaakwijzigingen.
• Een gedeelde skill waarvan wordt gezegd dat deze bij een foutgh pr edit terugvalt op de API. Er treedt echter geen fout op: er wordt een niet-kritieke melding weergegeven, de skill sluit af met exitcode 0 en laat de pull-aanvraag ongewijzigd. Een fallback die is ingesteld op een fout die nooit optreedt, wordt nooit uitgevoerd. Drie auteurs zijn hier in drie repositories op gestuit.
• In een bestaande waarschuwing in onze agentdocumentatie werd een bepaalde databasefout als „veilig“ bestempeld, omdat deze onmiddellijk een foutmelding oplevert. Drie personen waren hiermee in aanraking gekomen bij drie verschillende tabellen. In één geval kwam de fout door de controle heen, doorstond deze de CI en leidde pas tijdens de uitvoering tot een crash.

Sommige overeengekomen regels hoorden thuis in een automatische controle. De bovenstaande databasewaarschuwing is automatisch te controleren: een test die het schema doorleest, zou de gehele les beëindigen, terwijl de documentatie hierover slechts waarschuwt. “Bewerk het gegenereerde schemabestand nooit handmatig” werd als waar erkend en staat nog steeds in de wachtrij, omdat tekstuele vermelding niet de juiste manier is om dit af te dwingen. Twee andere overeengekomen punten waren al als stapsgewijze procedures opgesteld, waardoor het vaardigheden zijn geworden. Verschillende punten zijn na de stemming als tickets in plaats van als documentatie vastgelegd.

Een regel kan standaardgedrag zijn en toch moeten worden vastgelegd. Twee personen hadden onafhankelijk van elkaar opgeschreven: „Nooit committen of pushen tenzij daarom wordt gevraagd”. Eén van hen verwoordde het het treffendst: „Het aanmaken van bestanden betekent niet dat u toestemming hebt om ze te committen.” Elke medewerker zou zich al op deze manier moeten gedragen. Twee personen hebben het opgeschreven omdat het toch steeds weer gebeurde, wat het argument is om het expliciet vast te leggen.

Tijdens de oogst werd een fout in de oogst ontdekt. Elke bundel was voorzien van een versiestempel, waardoor de controle weigerde bundels te vergelijken die volgens verschillende verzamelregels waren samengesteld. Het stempel was afkomstig van de versie van de plug-in, niet van die van de exporteur. Alle vijf bundels waren samengesteld met byte-identieke scripts en voorzien van drie verschillende versies. De veiligheidscontrole zou bij een daadwerkelijke wijziging van de regels nooit in werking treden, maar wel bij elke niet-gerelateerde update van de plug-in. Die oplossing was een van de vijftien.

Hoe vaak dient u dit uit te voeren?

De eerste oogst is de meest tijdrovende: maanden aan persoonlijke aantekeningen, die in één intensieve sessie worden verwerkt. Houd daarna tijdens de reguliere teamoverleggen een vijf minuten durende snelle controle in: is er iets nieuws dat door meer dan één persoon is genoteerd?

Vijf storingsscenario’s waarmee bij het ontwerp rekening moet worden gehouden:

• Alleen-schrijven: regels worden doorgevoerd en niemand controleert of het gedrag van de agent is veranderd.
• Verouderd en zonder eigenaar: een gedeelde regel blijft bestaan nadat de code die deze beschrijft, is verwijderd.
• Gepromoot op basis van n=1: de uitgesproken mening van één persoon wordt een teamregel omdat hij of zij deze als eerste heeft opgeschreven.
• Eén document met vier soorten inhoud: vaste regels, procedures, naslagmateriaal en achtergrondinformatie, allemaal verzameld in één enkel bestand dat niemand van begin tot eind doorleest.
• Zo ver geabstraheerd dat het nutteloos is geworden: een regel die zo ver is veralgemeend ten opzichte van de gebeurtenis die aanleiding gaf tot de regel, dat deze de actor niet langer aangeeft wat hij moet doen.

Voer er één handmatig uit

U hebt geen speciaal gereedschap nodig. Onze export bestond uit een klein script, maar elke stap kan met de hand worden uitgevoerd:

1. Exporteer op vertrouwelijke wijze. Iedereen kopieert zijn of haar map met automatische gegevens (in Claude Code, ~/.claude/projects/<project>/memory/), zijn of haar en~/.claude/CLAUDE.md eventuele persoonlijke vaardigheden naar één map per persoon.
2. Controleer de inhoud voordat u deze deelt. Iedereen verwijdert alles wat niet mag worden doorgegeven: inloggegevens, klantgegevens, alles wat betrekking heeft op een met naam genoemde collega. Er wordt niets verzonden zonder dat de eigenaar het eerst heeft gelezen.
3. Groeperen op basis van betekenis. Een beoordelaar – een mens of een systeem – groepeert vermeldingen die met andere woorden hetzelfde betekenen en registreert wie elke vermelding heeft geschreven.
4. Tel het aantal unieke auteurs. Twee of meer onafhankelijke auteurs vormen een kandidaat. Voeg de apparaten van één persoon samen, laat gedeelde tekst uit de upstream buiten beschouwing en noteer welke clusters overblijven zonder uw grootste gebruiker.
5. Classificeer en stuur door. Geef elke kandidaat het label ADD, UPVOTE, DOWNVOTE of EDIT en wijs vervolgens een bestemming toe uit de bovenstaande routeringstabel.
6. Vermeld tegenstrijdigheden afzonderlijk. Los deze waar mogelijk op basis van het toepassingsgebied op; laat de rest onopgelost en vermeld dit.
7. Laat de aanwezigen stemmen. Zet de voorstellen op één pagina en de feiten van één auteur op een tweede, en neem gezamenlijk een besluit.
8. Behandel elke promotie als een afzonderlijke PR ten opzichte van de repo waarop deze betrekking heeft. Houd de onbewerkte bundels buiten de hoofdbroncode.

Veelgestelde vragen

Wat is een ‘memory harvest’?

Een ‘memory harvest’ is een teamprocedure voor AI-programmeeragenten: elke ontwikkelaar exporteert de herinneringen en persoonlijke regels van zijn of haar eigen agent; één beoordelaar groepeert de items uit alle exportbestanden, en de regels die door meerdere personen onafhankelijk van elkaar zijn geschreven, worden ondergebracht in gedeelde bestanden zoals ofCLAUDE.md AGENTS.md. Dit is de onderhoudsstap op teamniveau binnen context engineering.

Hoeveel mensen moeten er akkoord gaan voordat een regel in CLAUDE.md wordt opgenomen?

Wij maken gebruik van twee of meer onafhankelijke auteurs. Tel het aantal verschillende personen, niet het aantal bijdragen: één persoon die een regel drie keer herformuleert, of die gegevens van twee computers exporteert, geldt nog steeds als één auteur. Twee personen die dezelfde gepubliceerde tekst hebben overgenomen, zijn evenmin onafhankelijk. De drempel bepaalt wat er wordt voorgesteld; het team stemt nog steeds over elke promotie.

Wat hoort thuis in een team-CLAUDE.md en wat in het persoonlijke geheugen?

Het is een vaststaand feit dat elke sessie in die repository thuishoort in het projectCLAUDE.md, omdat deze automatisch wordt geladen. Procedures horen thuis in de sectie ‘vaardigheden’, gedetailleerde referentie-informatie in de documentatie met een verwijzing, en alles wat door een machine kan worden gecontroleerd, in een lint-regel of test. Voorkeuren met betrekking tot uw eigen tools, apparatuur of budget blijven persoonlijk.

Moeten de teamregels in CLAUDE.md of in AGENTS.md worden opgenomen?

Regels die elke AI-tool moet volgen, worden hierin opgenomenAGENTS.md; instructies die specifiek voor Claude gelden, blijven hierin staanCLAUDE.md. Claude Code kan deze AGENTS.mdrechtstreeks of via een import@AGENTS.md lezen, zodat één bestand volstaat voor alle tools die uw team gebruikt.

Wat doet u wanneer de herinneringen van twee ontwikkelaars elkaar tegenspreken?

Controleer eerst de reikwijdte: beide kunnen in verschillende repositories juist zijn, en een latere wijziging van de tool heeft dit wellicht al opgelost. Indien één van beide verouderd is, vervang deze dan in plaats van deze te overschrijven. Indien het meningsverschil betrekking heeft op een voorkeur in plaats van op een feit binnen de codebase, laat het dan onopgelost en neem het op in de persoonlijke regels van elke betrokken persoon.

Hoe vaak dient een team een ‘memory harvest’ uit te voeren?

Voer één afgebakende sessie uit om de achterstand weg te werken, en houd vervolgens tijdens een regelmatige teamsynchronisatie een korte controle van vijf minuten in om nieuwe kandidaten te selecteren. De eerste selectieronde is de duurste; daarna zou het aantal kandidaten beperkt moeten blijven.

Maak er een teambeslissing van

Bij het verzamelen van herinneringen beslist het team welke regels algemeen geldend worden; de beoordelaar doet slechts voorstellen. Het exporteren, het clusteren en het tellen kunnen allemaal worden geautomatiseerd. De stemming kan dat niet, en dat mag ook niet. Welke regels voor iedereen bindend zijn, welke persoonlijk blijven en welke meningsverschillen open blijven, is een beslissing die moet worden genomen door de mensen die ermee moeten leven. Dit is hetzelfde punt dat wij naar voren brengen in het rapport „Exists, the room doesn’t”: een geaggregeerd overzicht is pas nuttig zodra degenen die verantwoordelijk zijn voor de oplossingen gezamenlijk een besluit nemen.

Dat is een retrospective met verschillende bronnen. Toen onze AI-agenten hun eigen retrospectieve punten indienden, was het bewijsmateriaal afkomstig uit hun sessies. Deze keer was het afkomstig uit onze eigen privé-notities, en de ruimte vervulde dezelfde functie: het patroon herkennen, de juiste invalshoek kiezen en aan elk punt een verantwoordelijke toewijzen. Als uw team al regelmatig een retrospective houdt, past een ‘memory harvest’ prima als agendapunt. De volledige werkwijze vindt u in onze gids voor retrospectieven met AI-agenten.

Voert u zelf een oogst uit, of vindt u dat onze drempelwaarde onjuist is? Laat het ons weten: ai-discussion@teamretro.com.