CLAUDE.md inrichten: kort, concreet en actueel
Tachmy Dilmy, eCommerce AI Club
Uit de sessie: Training AI Literacy Gevorderd
Tachmy Dilmy legt in de training AI Literacy Gevorderd uit hoe je CLAUDE.md inricht, het bestand dat Claude Code aan het begin van elke sessie leest. Hij laat zien hoe je met /init begint en geeft vijf tips voor de inhoud. Voor iedereen die merkt dat Claude telkens opnieuw moet horen hoe je werkt.
Voor wie: Je Claude Code gebruikt en steeds opnieuw moet uitleggen hoe je werkt, welke tools je kiest of hoe er getest moet worden.
Waarom dit ertoe doet
Elke sessie in Claude Code begint met een leeg geheugen. Zonder vaste instructies weet Claude niet welke database je gebruikt, hoe je test of wat het project moet opleveren, en kiest hij zelf. Een CLAUDE.md lost dat op, mits je hem goed schrijft. De documentatie van Claude Code adviseert minder dan 200 regels per bestand, omdat langere bestanden meer context kosten en minder goed worden opgevolgd. Tachmy's slide met 5 tips geeft dezelfde grens. Hij merkte zelf dat het aantal keren dat hij iets moest terugsturen flink daalde toen hij één regel toevoegde: test alles in de browser voordat je oplevert. Hij noemt daar geen cijfer bij. Voor een team betekent een gedeelde CLAUDE.md dat iedereen dezelfde afspraken meekrijgt, zonder ze elke keer te typen.
Belangrijkste inzichten
- CLAUDE.md wordt bij elke sessie ingelezen; zonder dat bestand weet Claude niet wie je bent of hoe je werkt.
- Het commando /init maakt in één keer een eerste CLAUDE.md op basis van de bestanden in je werkmap.
- Houd het onder de 200 regels; zowel Tachmy's slide als de documentatie van Claude Code noemen die grens.
- Beschrijf WHAT, WHY en HOW, bijvoorbeeld dat je SQLite gebruikt en dat elke oplevering in de browser getest moet worden.
- Review het bestand regelmatig; volgens Tachmy is een CLAUDE.md na een jaar verouderd.
Wat CLAUDE.md is
CLAUDE.md is een tekstbestand met instructies dat Claude Code aan het begin van elke sessie inlaadt. Tachmy noemt het het hoofdbestand of het 'project brain'. Je zet erin hoe je werkt, welke techstack je gebruikt, welke regels gelden en welke domeinkennis Claude nodig heeft. De documentatie zegt erbij dat Claude het bestand als context behandelt en niet als harde configuratie. Wil je een actie altijd blokkeren, dan heb je een hook nodig. Hoe specifieker en korter de instructies, hoe consequenter Claude ze volgt. Je kunt het bestand per project gebruiken, maar ook voor al je projecten tegelijk.
Beginnen met /init
De eerste keer typ je in Claude Code het commando /init. Claude bekijkt dan je werkmap en schrijft een eerste CLAUDE.md met onder meer build-commando's, testinstructies en afspraken die hij in de code tegenkomt. Volgens de documentatie stelt /init verbeteringen voor als er al een CLAUDE.md bestaat, in plaats van die te overschrijven. Daarna vul je zelf aan wat Claude niet uit de bestanden kan halen. Tachmy geeft een voorbeeld: zijn team gebruikt SQLite als database. SQLite heeft geen apart serverproces en bewaart de hele database in één bestand, dus er hoeft geen server te draaien. Zet je dat in CLAUDE.md, dan kiest Claude niet zelf uit honderden andere databases.
Vijf tips voor de inhoud
De slide geeft 5 tips. Houd het kort, onder de 200 regels. Beschrijf WHAT: je stack en projectstructuur. Beschrijf WHY: het doel van de codebase. Beschrijf HOW: hoe je bouwt, hoe tests draaien en hoe Claude zijn eigen wijzigingen controleert. Gebruik CLAUDE.md alleen voor regels die altijd gelden en zet domeinkennis in Skills, die Claude alleen laadt als ze relevant zijn. Tachmy's eigen HOW-regel sluit aan op de clip over Playwright: maak bij elke oplevering unit tests en controleer in een browser of het werkt zoals gevraagd. Volgens hem kwam hij daardoor veel minder vaak in een pingpongspel met een oplevering die niet werkte.
Onderhoud en waar het in de training stond
Tachmy's laatste tip: een CLAUDE.md van vandaag is over een jaar verouderd, omdat de techniek verandert en je werk ook. Review het bestand dus nadat je het hebt gemaakt, en daarna regelmatig. De documentatie geeft dezelfde reden: tegenstrijdige instructies laten Claude willekeurig kiezen, dus haal verouderde regels weg. Vlak voor de clip vertelt Tachmy dat het contextvenster van Claude inmiddels 1 miljoen tokens groot is en dat hij een week eerder voor het eerst door zijn tokens heen was. Een korte CLAUDE.md scheelt ook daarin, omdat het bestand bij elke sessie meetelt. Aan het eind van de training vraagt hij iedereen om nog dezelfde dag met /init te beginnen.
Probeer dit deze week
- Open je project in Claude Code, typ /init en lees de CLAUDE.md die eruit komt regel voor regel na.
- Voeg één HOW-regel toe: 'Schrijf tests voor elke wijziging en controleer het resultaat in de browser voordat je klaar meldt.'
- Zet een terugkerende afspraak in je agenda om elke 3 maanden je CLAUDE.md te reviewen en verouderde regels te schrappen.
Begrippen
- CLAUDE.md
- Een tekstbestand met vaste instructies dat Claude Code aan het begin van elke sessie leest, zoals je werkwijze, techstack en regels.
- /init
- Een commando in Claude Code dat je project bekijkt en automatisch een eerste CLAUDE.md schrijft.
- Techstack
- De combinatie van programmeertalen, frameworks, databases en tools waarmee een project gebouwd is.
- SQLite
- Een database die zonder aparte server werkt en alle gegevens in één bestand bewaart.
- Skills
- Losse instructiepakketten in Claude Code die alleen worden geladen als ze nodig zijn, handig voor domeinkennis die niet in elke sessie hoeft.
Verdiep je in de gids
Transcriptie
Uitgeschreven uit de audio van dit fragment. Stopwoorden en herhalingen zijn weggelaten. Waar [onverstaanbaar] staat, is de opname niet te verstaan.
Wat Jop ook aangaf rondom het gebruik van het geheugen van Claude, is dat je eigenlijk een soort van één hoofdbestand, wat dan CLAUDE.md heet. In dat bestand geef je eigenlijk aan wat jouw werkwijze is. Welke techstack jij graag wil gebruiken. Stel je voor dat Claude op een gegeven moment een database wil hebben. Er zijn honderd en één soorten, misschien wel duizenden soorten databases die je wil gebruiken. Wat wij bijvoorbeeld doen is een hele simpele database gebruiken. Wat dan SQLite heet. Dat is een SQL database. En die werkt gewoon vanuit een bestand. En die kan je dan aanroepen. Dan loop je dus niet een aparte server voor aan te zwengelen. Dus dat soort werkwijzes, techstacks, regels hoe je omgaat. Die plaats je in je CLAUDE.md. En de eerste keer dat je het doet. Kan je opstarten. En dan zeg je eigenlijk met slash i-n-i-t. Initialize. Dan maakt hij eigenlijk een soort van eerste CLAUDE.md bestand op basis van bestanden die hij vindt in jouw werkmap, of het gedrag wat je hiervoor hebt vertoond. En zonder CLAUDE.md gaat hij dus eigenlijk altijd van scratch beginnen. Weet je eigenlijk niet wie je bent, wat je doet, et cetera. Maar als je hem erbij hebt, dan weet hij ook steeds beter wat je wil. En zorgt er ook voor dat iedere prompt die je dan ook uitvoert, dat het op de manier gaat zoals jij dat ook graag zou willen. Een aantal tips ervoor: zorg ervoor dat die gewoon heel kort blijft. Maak het niet te lang, want hoe langer je ook weer maakt, des te slechtst is ze opgevolgd worden. Het is eigenlijk net als de normale prompting ook weer. En ook hier is weer wat, why en how gewoon heel belangrijk. Geef aan wat je stack is en hoe die structuur eruit ziet. Wat wil je ermee bereiken? Sowieso met je codebase die je nu aan het maken bent. En geef ook instructies hoe die dus dingen moet doen. Dus in het voorbeeld wat ik net gaf van een browser als toegang geven, Met Playwright. Zorg er dan voor dat als je dus in mijn CLAUDE.md staat. Als je iets gemaakt hebt. Maak er altijd unit tests voor. En zorg er ook voor dat je het via een browser ook dubbelcheckt. Of het ook echt opgeleverd is zoals ik het gevraagd heb. En dat heeft mij gewoon. Ja, sinds die mogelijkheid er is. Is het aantal gesprekken gepingponged met iets dat hij oplevert. Wat niet goed werkt. Is veel meer, is echt drastisch verminderd. Het laatste is ook nog, let goed op dat je vandaag maak je een CLAUDE.md bestand, maar een jaar later is die echt alweer verouderd, doordat techniek weer sneller gaat, doordat jouw werkzaamheden anders zijn geworden. Dus kijk er ook weer naar terug, dus review dat bestand ook nadat je hem gemaakt hebt.
Spreker: Tachmy Dilmy, eCommerce AI Club
Bronnen
Meer over AI Implementatie
Duur 1:09Walmart: meer omzet, minder mensen
Tachmy Dilmy, eCommerce AI Club
Walmart draait 600 miljard omzet, met steeds minder mensen
Duur 0:57YourSurprise: vier AI-doelen voor het hele bedrijf
Arne Timmerman, YourSurprise
Vier bedrijfsbrede AI-doelen, zo pakt YourSurprise het aan
Duur 1:40Context Window: van 2K naar 2 miljoen tokens
Jop van Hooft, eCommerce AI Club
Van enkele pagina's naar 10 boeken tegelijk in je AI-model, en dat verandert alles