Een CLAUDE.md-bestand schrijven dat Claude Code ook volgt
Een CLAUDE.md is een tekstbestand in je projectmap dat Claude Code aan het begin van elke sessie leest. Je zet er de regels in die je anders steeds opnieuw moet uitleggen. In onze proef maakte één regel het verschil: zonder CLAUDE.md rekende Claude Code in één van drie pogingen met onnauwkeurige kommagetallen, met de regel drie van drie keer goed. Hieronder bouwen we zo'n bestand op in vijf stappen, met het sjabloon dat we testten.
Zelf getest op 11 november 2026.
Wat Claude Code wanneer leest
Claude Code leest meerdere CLAUDE.md-bestanden en plakt ze achter elkaar: eerst die van je organisatie (als je IT-beheer er een neerzet), dan je eigen bestand en dan dat van het project. Bestanden in submappen en losse achtergrondbestanden komen pas mee als het werk daar komt. Dat scheelt ruimte in het geheugen van het model, het contextvenster: hoeveel tekst het tegelijk kan overzien.
| Bestand | Waar | Voor wie |
|---|---|---|
| Projectregels | ./CLAUDE.md of ./.claude/CLAUDE.md | Iedereen in het project, mee in versiebeheer |
| Eigen projectregels | ./CLAUDE.local.md (zet hem in .gitignore) | Alleen voor jezelf, in dit project |
| Eigen regels voor alles | ~/.claude/CLAUDE.md | Alleen voor jezelf, in elk project |
| Regels van de organisatie | Windows: C:\Program Files\ClaudeCode\CLAUDE.md, macOS: /Library/Application Support/ClaudeCode/CLAUDE.md | Iedereen op die computer; gaat vóór de rest |
Een CLAUDE.md maken in vijf stappen
Laat Claude Code een eerste versie maken
Start Claude Code in je projectmap en typ
/init. Het bekijkt je bestanden en schrijft een CLAUDE.md met de commando's en de opbouw van het project. Bij ons duurde dat 8 seconden en kwamen er 19 regels uit, in het Engels. Het zag zelf dat de code met Decimal rekent, maar niet waarom. Die reden moet je er zelf in zetten.text/initSchrijf elke harde regel met datum en aanleiding
Een losse regel als ‘gebruik altijd Decimal’ wordt na een paar weken verkeerd toegepast, omdat niemand meer weet waarom hij er staat. Schrijf er de datum, de aanleiding en de controle bij. Dan kan Claude Code de regel ook toepassen op een geval dat je niet voorzag, zoals een gemiddelde of een percentage.
Zet achtergrond in losse bestanden, met een trigger
Alles in CLAUDE.md kost in elke sessie ruimte, ook als het niet over dat onderwerp gaat. Zet daarom alleen de harde regels in het bestand zelf. Achtergrond per onderwerp gaat in een eigen bestand, met één zin die zegt wanneer Claude Code dat moet lezen: ‘Gaat de taak over facturen, btw of betalingstermijnen? Lees dan eerst docs/facturen.md.’
Leg vast hoe Claude Code rapporteert
Je ziet niet wat Claude Code allemaal heeft gedaan, alleen het eindverslag. Vraag daarom een vaste vorm: eerst of het klaar is, dan wat er anders is, dan hoe het is gecontroleerd en wat er nog openstaat.
Test het bestand met een echte taak
Geef dezelfde taak een keer met en een keer zonder je regel, in een nieuwe sessie. Volgt Claude Code de regel niet, maak hem dan concreter of zet hem hoger in het bestand. Houd het bestand onder de 200 regels; dat raadt de documentatie aan.
Het sjabloon dat we testten
Dit is de CLAUDE.md uit onze proef, voor de administratie van een verzonnen schildersbedrijf. Vervang de regels door die van je eigen project en houd de vorm aan.
# Instructies voor dit project
Dit is de administratie van een klein schildersbedrijf. Scripts in Python 3, alleen de standaardbibliotheek.
## Harde regels
### Geldbedragen (2026-03-04, harde regel)
Aanleiding: een afronding met float gaf een factuur die 1 cent afweek van de boekhouding.
Regel: reken met bedragen altijd in Decimal, ook bij gemiddelden en percentages. Rond pas af bij tonen: 2 decimalen, ROUND_HALF_UP.
Afgedwongen door: tests/test_geld.py.
### Klantgegevens (2026-05-12, harde regel)
Aanleiding: een testbestand met echte klantnamen stond bijna online.
Regel: gebruik in voorbeelden en tests alleen verzonnen namen. Schrijf nooit iets naar de map export/.
Afgedwongen door: controle vóór elke commit.
## Lees eerst, als de taak erom vraagt
- Gaat de taak over facturen, btw of betalingstermijnen? Lees dan eerst docs/facturen.md.
- Gaat de taak over planning of offertes? Lees dan eerst docs/planning.md.
## Hoe je rapporteert
1. Eerste regel: klaar, of niet klaar en waarom.
2. Wat er nu anders is, in gewone taal.
3. Hoe je het gecontroleerd hebt.
4. Wat er nog openstaat.CLAUDE.md-sjabloon, getest met Claude Code 2.1.321 op 11 november 2026.
Zo hebben we het getest
We gaven Claude Code 2.1.321 op Ubuntu telkens een nieuwe sessie zonder andere instellingen, en keken in het logboek welke bestanden het opende.
| Taak | Zonder deze CLAUDE.md | Met deze CLAUDE.md |
|---|---|---|
| Gemiddeld factuurbedrag per klant (3 keer) | 1 van 3 keer met float gerekend | 3 van 3 keer met Decimal en ROUND_HALF_UP |
| Factuurregel met btw en vervaldatum (2 keer) | Niet getest | 2 van 2 keer eerst docs/facturen.md gelezen; termijn van 14 dagen en de keuze 21% of 9% btw stonden in het script |
| Facturen per klant tellen (2 keer) | Niet getest | 2 van 2 keer toch docs/facturen.md gelezen, omdat het woord ‘facturen’ in de taak stond. Niet nodig, wel onschuldig |
| Buitenklus volgende week plannen (1 keer) | Niet getest | docs/planning.md gelezen en de klus geweigerd: buitenwerk alleen van april tot en met oktober |
(opent op ware grootte)Wat we ervan leren: een trigger kijkt naar woorden in de taak, niet naar wat er echt nodig is. Een telopdracht over ‘facturen’ haalde het factuurbestand ook op. Bij een paar korte achtergrondbestanden is dat geen probleem. Heb je er veel en zijn ze lang, maak de trigger dan preciezer.
Als Claude Code je CLAUDE.md niet volgt
| Wat je ziet | Waarschijnlijke oorzaak | Wat je doet |
|---|---|---|
| Een regel wordt soms genegeerd | Het bestand is te lang of de regel is vaag | Onder de 200 regels blijven; de regel concreet maken, met voorbeeld |
| Claude Code kiest willekeurig tussen twee regels | Twee regels spreken elkaar tegen, bijvoorbeeld in een submap | Eén regel laten staan en zeggen welke hij vervangt |
| Iets wat echt niet mag, gebeurt toch | CLAUDE.md is context, geen slot | Gebruik een hook: een stukje code dat de actie vooraf weigert |
| Je AGENTS.md wordt niet gelezen | Er staat ook een CLAUDE.md in de map of erboven | Zet @AGENTS.md in je CLAUDE.md, dan leest hij beide |
Een import met @ laadt niet | Er staat een spatie in het pad | Zet een backslash voor elke spatie, of hernoem de map |
CLAUDE.md of AGENTS.md?
AGENTS.md is hetzelfde idee, maar dan als afspraak tussen meerdere coding agents. Claude Code leest een AGENTS.md alleen als er geen CLAUDE.md in de map of erboven staat. Werk je met meer dan één agent, zet je regels dan in AGENTS.md en maak een CLAUDE.md met alleen de regel @AGENTS.md. Zo schrijf je je regels één keer en lezen alle agents dezelfde tekst. Wij werken zo met Claude Code en Codex naast elkaar.
Vragen
Waar zet ik het CLAUDE.md-bestand?
In de hoofdmap van je project, naast je andere bestanden. Regels die voor al je projecten gelden, zet je in ~/.claude/CLAUDE.md in je gebruikersmap.
Hoe lang mag een CLAUDE.md zijn?
De documentatie raadt minder dan 200 regels per bestand aan. Langere bestanden kosten meer ruimte en worden slechter gevolgd. Zet achtergrond in losse bestanden die alleen laden als de taak erom vraagt.
Is CLAUDE.md hetzelfde als een systeemprompt?
Het lijkt erop: Claude Code leest het vóór je eerste opdracht. Maar het is een tekstbestand dat je zelf schrijft en in versiebeheer zet, en Claude Code behandelt het als context, niet als regel die het nooit mag breken.
Moet ik /init gebruiken?
Het is een goed begin voor de commando's en de opbouw van je project. De redenen achter je regels kan /init niet weten; die vul je zelf aan.
Bronnen
- Claude Code: How Claude remembers your project (CLAUDE.md, AGENTS.md, imports) gecontroleerd op
- AGENTS.md: open formaat voor instructies aan coding agents gecontroleerd op
Meer over claude in de praktijk
- Wat is Claude Code? Uitleg met vijf taken die we het zelf lieten doenClaude Code leest je bestanden, past ze aan en voert opdrachten uit. Wij gaven het vijf kantoorklussen: dit deed het, dit kost het en hier schoot het tekort.
- Wat is vibe coding? Wij bouwden een klantenlijst zonder één regel code te lezenVibe coding is software laten bouwen door een AI, zonder de code te lezen. Wij bouwden zo een klantenlijst, testten hem en zagen waar het ophoudt.
- Claude Code gebruiken: een handleiding met één echt projectjeHoe je Claude Code gebruikt, uitgelegd met één echt projectje: plannen, bouwen, nakijken en vastleggen. Met alle opdrachten woord voor woord en de uitkomst.
- Claude Code installeren op WindowsClaude Code op Windows installeren met één commando in PowerShell. Met de stap die de installer overslaat, de keuze voor WSL en de bekende foutmeldingen.
Ook handig
- AI-nieuws deze week: wat er van 2 tot 10 november 2026 veranderde in de tools die je gebruiktAI-nieuws van 2 tot 10 november 2026 voor ondernemers: nieuwe Claude-modellen, updates van Codex, Gemini CLI en n8n, en wat je ermee doet.
- Claude Code kosten: abonnement, limieten en wat een klus kostClaude Code zit in Pro ($20), Max en Ultra. Wij maten vijf klussen drie keer: gemiddeld $0,28 per klus met Opus en $0,09 met Sonnet. Met rekenvoorbeeld.
- Claude Code changelog in gewone taal: wat er van 2 tot 10 november 2026 veranderdeDe Claude Code-changelog van 2 tot 10 november 2026 in gewone taal: wat je gebruikt, wat breekt en onze eigen test. Laatste versie: 2.1.322.