Wat is CLAUDE.md? Simpele uitleg & toelichting waarom belangrijk

Als je Claude Code regelmatig hetzelfde uitlegt dan gaat een CLAUDE.md bestand enorm waardevol voor je zijn. Denk bijvoorbeeld aan uitleggen dat de app die je maakt op poort 3000 moet starten, dat de teksten Nederlands moeten zijn en dat de data altijd eerst geïmporteerd moet worden.

In deze blog leer je wat een CLAUDE.md bestand is, waarom het belangrijk is, en hoe je het genereert en test.

Waarom is CLAUDE.md belangrijk?

Claude Code onthoudt niets tussen sessies. Start je een nieuw gesprek, dan begint hij leeg. Hij weet niet hoe je project in elkaar zit, hoe je de applicatie start of welke afspraken jullie in eerdere chats hebben gemaakt.

Een CLAUDE.md is een tekstbestand in je projectmap dat automatisch wordt meegestuurd bij elke sessie. Alles wat erin staat, weet Claude vanaf de eerste prompt.

Het bestand is Markdown (een eenvoudige opmaaktaal waarmee je platte tekst kunt voorzien van structuur en stijl), dus je kunt het openen en aanpassen zoals elk ander tekstbestand.

Een eerste versie CLAUDE.md genereren met /init

Je hoeft het bestand niet zelf te schrijven. Het commando /init laat Claude je project doorlezen en er een samenvatting van maken:

/init

Wat je terugkrijgt is een beschrijving van je codebase: welke bestanden er zijn, welke technieken gebruikt worden, hoe de mappen zijn ingedeeld.

Lees dat resultaat kritisch, want de gegenereerde versie kan onderdelen missen die jij in de praktijk juist fijn vindt. Twee voorbeeldzaken die je zou kunnen controleren:

• Staat erin met welk commando de applicatie start?
• Staat erin hoe je de data importeert / de database vult?

Mis je iets, dan vul je het aan anders blijf je zaken dubbel uitleggen.

Wat hoort er in een CLAUDE.md bestand?

Een CLAUDE.md werkt het best als hij vier soorten informatie bevat.

1. Hoe je het project start. Het commando om de app te draaien, op welke poort, en wat er vooraf moet gebeuren.

2. Afspraken over stijl en taal. Nederlandse teksten, een bepaalde huisstijl, hoe knoppen eruit moeten zien.

3. Werkafspraken. Bijvoorbeeld: voer na elke afgeronde feature de tests uit, of deploy alleen op verzoek en nooit uit jezelf.

4. Wat je over jezelf wilt melden. Een regel als "ik heb beperkte technische kennis, vermijd technische vragen aan mij" verandert de antwoorden die je krijgt aanzienlijk.

Een simpel voorbeeld CLAUDE.md:

### Ontwikkelinstructies

- Gebruik Nederlandse teksten
- Start de applicatie altijd op poort 3000
- Voer na elke afgeronde feature `uv run pytest` uit
- Deploy alleen als ik daar expliciet om vraag
- Ik heb beperkte technische kennis, vermijd technische vragen aan mij

Dit is ook een voorbeeld uit een project van mij waarmee ik aankomende trainingsdata automatisch toevoeg in onze Data Science Partners nieuwsbrief. Je ziet hoe kort en duidelijk zo'n Claude.md bestand is.

Hoe lang mag een CLAUDE.md zijn?

Kort. Dat is contra-intuïtief, want als het bestand toch automatisch meegaat, waarom zou je er niet alles in zetten?

Omdat het meeschuift in je context window. Hoe meer tekst er in het gesprek zit, hoe groter de kans dat een instructie verdund raakt en genegeerd wordt.

Is een instructie te groot voor CLAUDE.md, dan kun je er beter een skill van maken. Dat is ook een tekstbestand met instructies, maar het wordt alleen gelezen op het moment dat het nodig is. Denk aan een uitgebreid stappenplan voor het maken van een grafiek, of een checklist voor een beveiligingscontrole.

Je kunt dit onthouden: CLAUDE.md is voor wat altijd geldt, een skill is voor wat soms geldt.

Controleren of CLAUDE.md werkt

Je kunt controleren of je CLAUDE.md goed is.

Dit doe je door een compleet nieuwe sessie te starten met /clear, zodat Claude niets weet van wat jullie eerder hebben besproken. Geef vervolgens een korte opdracht waarvan je weet dat er instructies in CLAUDE.md staan. In ons voorbeeld kan dat zijn:

Ben ik een technisch persoon? Stel je mij wel eens technische vragen?

Als het goed is weet Claude uit het CLAUDE.md bestand dat je niet technisch bent en dus geen technische vragen wilt krijgen.

Mocht een antwoord nog niet helemaal goed zijn dan kun je altijd de CLAUDE.md aanscherpen.

Voor elke terugkerende taak kun je uiteindelijk testen of het in 1x werkt in een lege sessie.

CLAUDE.md ook voor jezelf een handig naslagwerk

De praktische winst is duidelijk: tijdswinst en minder tokenverbruik. Maar zelf vind ik een andere winst ook erg fijn.

Een CLAUDE.md dwingt je om op te schrijven hoe je project werkt. Dat is documentatie die je normaal niet maakt, omdat je het zelf weet. Maar we genereren tegenwoordig zo veel code dat het heel fijn is om zo'n duidelijk beschrijvend bestandje te hebben als je na drie maanden terugkomt in een project.

Wil je zien waar dit bestand in de praktijk terechtkomt en hoe je wijzigingen volgt, dan kun je bijvoorbeeld werken met Claude Code in VS Code. En wist je dat je Claude Code ook voor niet-technisch werk kunt gebruiken? Lees bijvoorbeeld eens content schrijven met Claude Code.

Wil jij dit ook leren?

In onze Vibe Coding Training leer je in twee dagen websites en apps bouwen met AI, zonder programmeerervaring. Wil je specifiek met Claude werken? Bekijk dan de Claude Code Training. En voor een complete basis in AI zonder programmeren is er de 5-daagse AI Opleiding.