CLAUDE.md: het bestand waarmee Claude Code je project leert kennen

Claude Code begint elke sessie met een leeg werkgeheugen. Wat jullie gisteren in het gesprek afspraken over de toon van je teksten of over het commando om je site live te zetten, zit daar vandaag niet meer in. Daarvoor is CLAUDE.md: een tekstbestand in je projectmap dat Claude Code bij het begin van elke sessie vanzelf leest. Zie het als het overdrachtsbriefje dat je voor een invaller klaarlegt. Wat erop staat, hoeft niemand te raden. Wat er niet op staat, moet de invaller zelf uitzoeken, en dat gaat soms goed en soms niet.

Wat CLAUDE.md is

Het bestand heet letterlijk CLAUDE.md, met hoofdletters, en staat in de hoofdmap van je project. De .md staat voor Markdown: platte tekst waarin een regel met een hekje (#) ervoor een kop is en een regel met een streepje ervoor een opsomming. Je kunt het met elke teksteditor openen en lezen.

Claude Code leest het bij de start en houdt het de hele sessie bij de hand. Wordt een lang gesprek automatisch samengevat, dan leest hij het bestand opnieuw in, terwijl afspraken die alleen in het gesprek stonden dan kunnen wegvallen. Er bestaan meer plekken voor zo’n bestand. Een CLAUDE.md in de map ~/.claude/ in je thuismap geldt voor al je projecten, handig voor persoonlijke voorkeuren zoals de taal waarin je antwoord wilt. Of Claude je bestand gelezen heeft, zie je met /context: onder Memory files hoort het te staan. Alle details staan in de uitleg van Anthropic over geheugen.

Wat erin hoort

De adviezen van Anthropic geven een bruikbare toets: zet erin wat Claude niet zelf kan raden en wat in elke sessie geldt. Voor een website of een klein platform zijn dat meestal de commando’s waarmee je bouwt en publiceert en je vaste afspraken over tekst en beeld. Zet er ook in wat Claude nooit mag doen. Een vaste vorm is er niet, zolang het kort en leesbaar blijft.

Een voorbeeld. Pieter heeft een keramiekatelier in Deventer en een eenvoudige site met zijn werk en zijn workshops. Zijn CLAUDE.md is ongeveer zo:

# Atelier Pieter

Site van een keramiekatelier in Deventer: werk, workshops, contact.
Statische HTML en CSS. De meeste bezoekers kijken op hun telefoon.

## Publiceren
- Live zetten: sudo publish atelierpieter.nl ~/sites/atelierpieter.nl
- Alleen publiceren als ik daar in dit gesprek om vraag.

## Schrijven
- Nederlands, je-vorm, korte zinnen.
- Prijzen altijd inclusief btw, met het woord euro erachter.
- Workshopdata staan in workshops.txt. Verzin geen data.

## Beeld
- Alleen foto's uit de map beeld, verkleind tot 1600 pixels breed.

## Werkwijze
- Leg elke werkende stap vast met git, met een omschrijving van één regel.
- Lees of wijzig .env nooit.

Het publicatiecommando is een hulpcommando op de servers die ik bij retrAIt inricht. Op jouw server staat daar het commando dat jij gebruikt. Het punt is dat Claude het niet hoeft te raden.

Wat er niet in hoort, is net zo belangrijk. Wat Claude zelf uit je bestanden kan afleiden, hoef je niet op te schrijven. Laat ook uitgebreide achtergrondverhalen weg, en alles wat snel verandert, zoals je takenlijst. En algemene wijsheden als “schrijf goede teksten” voegen niets toe, want daar doet Claude toch al zijn best voor.

Kort en na te gaan

Anthropic adviseert om een CLAUDE.md onder de tweehonderd regels te houden. Voor een website kom je meestal met een paar dozijn regels toe. Elke regel extra maakt het moeilijker om de belangrijke eruit te pikken; volgens Anthropic gaat Claude bij een te lang bestand een deel van je regels negeren. Stel bij elke regel de vraag die Anthropic voorstelt: maakt Claude zonder deze regel een fout? Zo niet, haal hem weg.

Schrijf regels die je kunt nagaan. “Schrijf in de je-vorm” kun je controleren, “schrijf vriendelijk” niet. Let ook op tegenstrijdigheden. Staat er op de ene plek “korte zinnen” en op een andere “uitgebreide uitleg bij elke workshop”, dan kan Claude er willekeurig een kiezen. Blijft Claude één bepaalde regel overslaan, dan mag je die ene regel benadrukken met een woord als BELANGRIJK. Doe je dat bij tien regels, dan valt er geen enkele meer op.

Een eerste versie met /init

Het commando /init geeft je een begin. Claude onderzoekt dan je project en zet wat hij vindt in een eerste CLAUDE.md, zoals de manier waarop je project is opgebouwd. Bestaat het bestand al, dan doet hij voorstellen om het te verbeteren in plaats van het te overschrijven. Wat Claude niet uit de bestanden kan halen, zoals je afspraken over toon en wat nooit mag, vul je daarna zelf aan.

Staat er nog bijna niets in je map, dan valt er voor /init weinig te vinden. Laat Claude je dan eerst interviewen over je project, en laat hem een voorstel doen dat je leest voordat het wordt opgeslagen.

Bijwerken gaat in gewone taal. Anthropic noemt onder meer deze momenten: Claude maakt dezelfde fout voor de tweede keer, of je merkt dat je een uitleg typt die je vorige week ook al gaf. Zeg dan bijvoorbeeld: “Zet in CLAUDE.md dat prijzen altijd inclusief btw zijn.” Wil je het bestand zelf openen, typ dan /memory en kies het. Spreek ook af dat Claude na elke werkende stap een commit maakt, zodat je altijd terug kunt; hoe dat werkt, staat in Terugdraaien met git.

Een afspraak, geen slot

Een regel in CLAUDE.md is een verzoek aan Claude, geen harde grens. Anthropic noemt het bestand nadrukkelijk context en geen afgedwongen instelling. Meestal is dat genoeg. Moet iets echt nooit gebeuren, zoals het openen van je .env of live zetten zonder jouw akkoord, leg dat dan vast in de instellingen van Claude Code, met een regel die het verbiedt of die altijd om toestemming laat vragen. Hoe dat werkt, staat in Plan mode, auto mode en toestemming.

Claude Code heeft daarnaast een automatisch geheugen (in het Engels auto memory): notities die Claude zelf bijhoudt. Vraag je hem iets te onthouden, bijvoorbeeld dat je teksten zonder Engelse woorden wilt, dan komt het daar terecht. Het verschil is wie schrijft: CLAUDE.md schrijf jij, de notities schrijft Claude. Moet iets een vaste regel worden, vraag dan expliciet om het in CLAUDE.md te zetten. In de app op claude.ai werkt geheugen weer anders; daarover gaat Claude onthoudt niets, tenzij je het een plek geeft.

Geen geheimen in CLAUDE.md

De inhoud van CLAUDE.md wordt bij elke sessie naar Claude gestuurd, en dus naar de servers van Anthropic. Leg je je project vast met git, dan staat het bestand ook in die geschiedenis, en het zit in je back-ups. Zet er daarom geen wachtwoorden, API-sleutels of gegevens van klanten in. Een API-sleutel is het wachtwoord waarmee je programma bij een andere dienst inlogt, zoals een betaaldienst. Zulke sleutels horen in een apart bestand, meestal .env, dat niet in git komt en dat Claude niet hoeft te openen. Meer daarover in Wachtwoorden en API-sleutels in je code.

Let ook op wat er online komt. Zet je je site live door de hele projectmap naar de webserver te kopiëren, dan staat CLAUDE.md misschien gewoon op internet, met al je afspraken erin. Controleer dat door het adres van je site te openen met /CLAUDE.md erachter. Je hoort een foutmelding te krijgen.

Begin vandaag met een CLAUDE.md van tien regels, met in elk geval het commando waarmee je publiceert en de afspraken die je nu steeds opnieuw typt. Kijk met /context of het bestand geladen is, en vul het aan zodra Claude een fout voor de tweede keer maakt. In de leerlijn Claude Code van het online programma oefen je dit met je eigen project.