CLAUDE.md maken: zo doe je het, stap voor stap (met voorbeeld)

Eerst begrijpen

Wat is CLAUDE.md en wat doet het bestand?

Elke sessie van Claude Code begint met een leeg contextvenster: Claude weet niets meer van gisteren. CLAUDE.md is een gewoon tekstbestand in Markdown (platte tekst met # voor koppen en - voor lijstjes) dat Claude aan het begin van elke sessie inleest. Je schrijft er op wat je anders elke keer opnieuw uitlegt: hoe je het project test, welke afspraken gelden en waar de valkuilen zitten.

Hoe de bestanden laden

Claude Code leest CLAUDE.md en CLAUDE.local.md in de map waarin je het start en in elke map daarboven. Ze overschrijven elkaar niet: alles wordt achter elkaar geplakt, van breed naar specifiek. Wat het dichtst bij je werkmap staat, leest Claude als laatste. Een CLAUDE.md in een submap laadt pas zodra Claude in die submap een bestand leest of wijzigt. Waarom dat ertoe doet: start je Claude in de verkeerde map, dan mist hij je projectregels.

Een richtlijn, geen slot op de deur

Claude behandelt CLAUDE.md als context, niet als afgedwongen configuratie. Hij volgt het bijna altijd, maar het blijft zijn afweging per taak. Moet iets echt altijd of nooit gebeuren, zoals nooit je .env-bestand lezen, dan hoort dat in een hook of een deny-regel in je instellingen. Dat onderscheid komt verderop terug, want het is de bron van de meeste frustratie.

Overleeft het /compact?

Ja, de CLAUDE.md in de root van je project wel. Na /compact, waarmee Claude een lang gesprek samenvat om ruimte te maken, leest Claude Code dat bestand opnieuw van schijf. Een CLAUDE.md in een submap en regels met een paths-filter laden pas weer als Claude daar opnieuw bestanden aanraakt. Wat je alleen in het gesprek hebt gezegd, kan na compaction weg zijn. Daarom: wat moet blijven, zet je in het bestand.

Voorbereiding

Wat heb je nodig voor een CLAUDE.md-bestand?

Weinig. Het bestand zelf is gratis en werkt op elk plan waarop Claude Code werkt. Zet dit klaar voordat je begint.

Werk je in VS Code of de desktop-app?

Dan werkt het hetzelfde. De desktop-app gebruikt dezelfde CLAUDE.md en CLAUDE.local.md als de terminal. In de VS Code-extensie open je ze via het commandomenu: typ / en kies onder Customize de optie Instructions (vanaf v2.1.274). Bestaat het bestand nog niet, dan maakt Claude Code het eerst aan. Nog niets geïnstalleerd? Volg Claude Code installeren of Claude Code in VS Code.

Niet voor de gewone Claude-chat

CLAUDE.md is van Claude Code. In de chat op claude.ai en in de Claude-app geef je vaste instructies via de instructies van een project of via memory. Het idee is hetzelfde, het bestand niet.

Stappenplan

CLAUDE.md maken in zeven stappen

Je laat Claude het voorwerk doen en besteedt je eigen tijd aan schrappen en aanvullen. Elke stap zegt waarom, zodat je weet wat je overslaat als je het anders doet.

Liever zonder /init?

Dat kan. Maak in de root van je project een bestand dat precies CLAUDE.md heet en plak het voorbeeld hieronder erin. Of typ /memory en kies het projectbestand: bestaat het nog niet, dan maakt Claude Code het aan en opent het in je editor. Voor een lege map zonder code is dit zelfs de betere route, want /init heeft dan niets om te analyseren.

Later iets toevoegen tijdens het werk

Zeg tegen Claude letterlijk zet dit in CLAUDE.md, gevolgd door de regel. Zeg je alleen "onthoud dit", dan slaat Claude het op in zijn automatische geheugen (auto memory), een aparte notitiemap per project op je eigen computer. Die notities deel je niet via git met je team.

Voorbeeld

CLAUDE.md voorbeeld voor een MKB-project om te kopiëren

Een voorbeeld: een installatiebedrijf met tien medewerkers laat de website onderhouden door een parttime ontwikkelaar, en de marketingmedewerker past met Claude Code zelf teksten aan. Dit is de CLAUDE.md die we voor zo'n situatie zouden opzetten. Vervang wat tussen [blokhaken] staat en schrap wat niet klopt.

Het bestand: CLAUDE.md in de root van je project

<!-- Pas de regels tussen [] aan. Dit commentaar ziet Claude niet. -->

# Project: website [bedrijfsnaam]
Website van een installatiebedrijf. Next.js met TypeScript en Tailwind. Live via [Vercel].

## Commando's
- Installeren: npm install
- Lokaal starten: npm run dev (http://localhost:3000)
- Controleren voordat je zegt dat je klaar bent: npm run lint en npx tsc --noEmit
- Bouwen: npm run build, alleen als ik erom vraag

## Werkafspraken
- Werk op een eigen branch, nooit direct op main
- Push en deploy alleen als ik dat expliciet vraag
- Raakt een wijziging meer dan 5 bestanden: laat eerst een plan zien
- Leg na elke wijziging in twee zinnen uit wat je deed en waarom

## Teksten op de site
- Nederlands, je-vorm, korte zinnen
- Prijzen altijd excl. btw, met "excl. btw" erachter
- Verzin geen klantnamen, reviews, cijfers of certificeringen

## Valkuilen
- src/legacy/ is nog live: niet verwijderen, maar ook geen patronen eruit overnemen
- Formulieren gaan via src/lib/crm.ts naar ons CRM, niet rechtstreeks per mail
- Testdata: alleen verzonnen namen en adressen op voorbeeld.nl, nooit echte klantgegevens

Waarom deze onderdelen erin staan

De commando's staan bovenaan omdat Claude zijn eigen werk alleen kan controleren als hij weet hoe. Anthropic raadt aan om in elk geval het commando op te nemen waarmee je die controle draait. De werkafspraken leggen vast wat niet in de code te zien is: wie beslist over publiceren. De tekstregels zijn er voor de marketingmedewerker, die geen code leest maar wel wil dat de site in de huisstijl blijft. De valkuilen zijn precies de dingen die Claude anders verkeerd zou doen, omdat de code ze niet verraadt. Wat er bewust niet in staat: de mappenstructuur en de lijst met packages. Die leest Claude zelf.

Waarom het HTML-commentaar bovenaan

Commentaar tussen <!-- en --> haalt Claude Code weg voordat het bestand in de context gaat. Je kunt dus notities voor collega's achterlaten zonder dat het Claude iets kost. Commentaar binnen een codeblok blijft wel staan.

En je persoonlijke bestand: ~/.claude/CLAUDE.md

# Mijn voorkeuren
- Antwoord in het Nederlands; code, variabelen en commitberichten in het Engels
- Ik ben geen ontwikkelaar: leg vaktermen in één zin uit
- Vraag eerst als een taak groter lijkt dan een half uur werk

Dit bestand geldt in al je projecten en deel je met niemand. Houd het nog korter dan het projectbestand, want het laadt overal.

Controle

Werkt het? Zo controleer je of Claude je CLAUDE.md leest

Test in twee stappen: eerst of het bestand geladen is, daarna of Claude er ook naar handelt. Doe dat in een nieuwe sessie, zodat je zeker weet dat Claude met de nieuwste versie begint.

De eerste prompt om te plakken

Welke projectinstructies heb je aan het begin van deze sessie gekregen? Noem uit welke bestanden ze komen. Geef daarna letterlijk: 1) het commando waarmee je je werk controleert, 2) wat je moet doen voordat je pusht of deployt, 3) één valkuil uit de instructies. Verzin niets: staat iets er niet in, zeg dat dan.

Waar je op let

Noemt Claude je bestanden en citeert hij de commando's en de regel over pushen goed, dan is je CLAUDE.md geladen. Bij de echte taak hoort hij uit zichzelf je lint- of testcommando te draaien. Doet hij dat niet, dan staat het commando er waarschijnlijk te vaag in. De regel "verzin niets" staat in de prompt omdat een taalmodel anders een plausibel antwoord kan geven op basis van wat het in je code ziet.

Nog strenger: laat Claude je bestand keuren

Vanaf v2.1.283 typ je /doctor prompt-audit. Claude zoekt dan naar verouderde instructies, verwijzingen naar bestanden of commando's die niet bestaan en regels die elkaar tegenspreken. Je krijgt een rapport met voorstellen; er verandert niets tot jij zegt dat het mag. Gewoon /doctor stelt ook inkortingen voor van dingen die Claude zelf uit de code kan afleiden.

Wat erin hoort

Wat zet je in een CLAUDE.md-bestand, en wat niet?

De vuistregel van Anthropic: schrijf alleen op wat Claude niet vindt door je code te lezen, of wat hij anders elke sessie opnieuw moet uitzoeken. Twee vragen helpen: kan hij het vinden door de code te lezen, en zou hij ook echt gaan kijken? Twee keer ja: laat het weg.

Onder de 200 regels, concreet en zonder tegenspraak

De richtlijn is minder dan 200 regels per bestand. Langere bestanden kosten meer context en Claude volgt ze minder trouw. Schrijf regels die je kunt controleren: "Gebruik 2 spaties inspringing" in plaats van "Formatteer netjes", "API-handlers staan in src/api/handlers/" in plaats van "Houd het georganiseerd". Groepeer onder kopjes met korte opsommingen. En spreken twee regels elkaar tegen, ook verspreid over bestanden, dan kiest Claude er willekeurig een.

Hoofdletters en IMPORTANT helpen niet

Blijft Claude een regel missen, dan is extra nadruk zelden de oplossing. Volgens Anthropic is het bestand dan te lang geworden, waardoor de regel ondersneeuwt, of is het een regel zonder uitzonderingen. Die laatste hoort in een hook. Het omgekeerde geldt ook: heb je hooks voor dingen die eigenlijk voorkeuren zijn, schrap ze en laat Claude kiezen.

Regels per map met .claude/rules/

Maak in je project een map .claude/rules/ met losse bestanden per onderwerp, zoals testing.md of teksten.md. Zonder filter laden ze altijd. Met bovenaan een paths-blok laden ze alleen als Claude met passende bestanden werkt. Bijvoorbeeld .claude/rules/api.md:

---
paths:
- "src/api/**/*.ts"
---
- Valideer elke request met de schema's in src/api/schemas/
- Elk nieuw endpoint krijgt een regel in openapi.yaml

Persoonlijke regels voor al je projecten zet je in ~/.claude/rules/.

Andere bestanden importeren met @

Met @pad/naar/bestand haal je een ander bestand binnen, bijvoorbeeld @README of @docs/huisstijl.md. Paden zijn relatief aan het bestand waarin de import staat, en imports mogen maximaal vier lagen diep. Let op: een import maakt je CLAUDE.md overzichtelijker, maar niet goedkoper, want het geïmporteerde bestand laadt volledig mee. Wil je een pad noemen zonder het te importeren, zet het dan tussen backticks. Wijst een import buiten je projectmap, dan vraagt Claude Code eenmalig om toestemming.

Andere tools

CLAUDE.md en AGENTS.md: werken met Cursor, Codex of Copilot ernaast

AGENTS.md is het instructiebestand dat andere coding agents gebruiken, zoals OpenAI Codex en Cursor. Sinds v2.1.277 leest Claude Code het zelf, zonder import of instelling. Welk bestand Claude leest hangt af van wat er in je repository staat.

Ons advies voor een gemengd team

Werkt een deel van je team met Cursor of Codex, houd dan AGENTS.md als het ene gedeelde bestand en zet ernaast een CLAUDE.md die begint met de regel @AGENTS.md, met daaronder alleen wat specifiek voor Claude is. Waarom: dan werkt het ook in sessies die AGENTS.md niet direct kunnen lezen, en heb je straks niet twee bestanden die uit elkaar groeien. Een symlink (ln -s AGENTS.md CLAUDE.md) kan ook, maar niet als iemand op Windows werkt: daar vraagt een symlink beheerdersrechten en checkt git hem uit als een tekstbestand van één regel.

Kiezen welke bestanden laden

Typ /config en zet Project instructions op een van de vier waarden: claude-md-or-agents-md (de standaard), claude-md-and-agents-md (allebei, CLAUDE.md eerst), claude-md (alleen CLAUDE.md) of managed-only (alleen de organisatie-instructies). Let op een valkuil: ook een CLAUDE.local.md telt als CLAUDE.md. Maak je er een aan in een project dat op AGENTS.md draait, dan leest Claude je AGENTS.md niet meer, tenzij je de tweede waarde kiest.

Overstappen van een andere tool

/init leest bestaande Cursor-regels (.cursor/rules/ en .cursorrules) en Copilot-instructies (.github/copilot-instructions.md) mee en neemt de bruikbare delen over. Met /import haal je de configuratie van Codex, Gemini CLI of Cursor op je computer binnen, inclusief instructiebestanden, MCP-servers en skills. Gebruik /import --dry-run om eerst te zien wat er zou veranderen.

Problemen

Claude negeert je CLAUDE.md? Meldingen, oorzaken en oplossingen

Begin altijd met /context: staat je bestand niet onder Memory files, dan ligt het aan het laden. Staat het er wel, dan ligt het aan hoe de regel geschreven is.

Botst je regel met wat Claude Code zelf doet?

Claude Code heeft eigen ingebouwde instructies voor commits en pull requests. Leg je in CLAUDE.md eigen regels vast voor commitberichten, dan kunnen die botsen. Zet de ingebouwde git-instructies uit met de instelling includeGitInstructions en stel de eigen tekst onder commits in met attribution.

Ons oordeel

Ons oordeel: wanneer een CLAUDE.md loont en wanneer niet

Een CLAUDE.md is een kleine investering: twintig minuten werk, en daarna profiteert elke sessie. Maar het is een briefing, geen handboek en geen beveiliging.

Wel doen

In elk project waar je vaker dan een paar keer met Claude Code werkt, en altijd zodra een tweede persoon meewerkt. Ook als je niet programmeert: wie Claude Code gebruikt voor teksten, rapportages of een map met offertes, heeft net zo goed afspraken die Claude niet uit de bestanden haalt, zoals je-vorm of u-vorm en welke map het origineel is.

Niet doen, of iets anders gebruiken

Voor een eenmalige klus loont een eigen CLAUDE.md niet; zet je wensen dan gewoon in de prompt. Voor een stappenplan dat je af en toe nodig hebt, gebruik je een skill. En voor alles wat zonder uitzondering moet, zoals een map die nooit gewijzigd mag worden, gebruik je een hook of een deny-regel. CLAUDE.md is daar te zacht voor.

De fout die we beginners het vaakst zien maken

Te veel erin zetten. De output van /init blijft ongelezen staan, er komt een huisstijlgids van twintig pagina's bij via een import, en na een maand staan er regels in die elkaar tegenspreken. Claude volgt dan juist minder van wat er staat. Onze aanpak in trainingen: begin met hooguit dertig regels, en voeg alleen iets toe als Claude dezelfde fout voor de tweede keer maakt. Dat is ook precies wanneer Anthropic zegt dat je iets moet toevoegen.

AVG en gevoelige gegevens

Je CLAUDE.md gaat bij elke sessie mee als context naar het model, en de projectversie staat in git bij iedereen die de repository heeft. Zet er dus geen wachtwoorden, API-keys, klantnamen of andere persoonsgegevens in, ook niet als voorbeeld. Wil je dat Claude bepaalde bestanden niet leest, regel dat dan met een deny-regel zoals Read(./.env) in je instellingen. Meer over wat er met je code gebeurt staat op Claude Code en privacy.

Voor IT-beheer in een Microsoft 365-omgeving

Rolt je organisatie Claude Code uit, dan kan IT een managed CLAUDE.md op elke computer zetten via MDM (bij veel Microsoft 365-bedrijven is dat Intune) of Group Policy, of de inhoud in managed settings zetten met de sleutel claudeMd. Gebruikers kunnen dat bestand niet uitsluiten. Gebruik het voor gedragsafspraken zoals een herinnering aan je dataclassificatie, en dwing harde grenzen af met managed settings zoals permissions.deny. Staat je code in Azure DevOps in plaats van GitHub: een CLAUDE.md is een gewoon bestand en werkt met elke git-remote.

Samen met je team opzetten

Het lastigste aan een gedeelde CLAUDE.md is niet het bestand maar de afspraken erachter: wie mag regels toevoegen, wat hoort in een hook en wat in een skill. In de Claude Code Masterclass zetten we dat met je team op aan de hand van jullie eigen repository.

Wat nu?

Wat nu? Vervolgstappen na je eerste CLAUDE.md

Staat je CLAUDE.md, dan zijn dit de logische volgende stappen. Kies er één die bij je volgende klus past.

Regels afdwingen in plaats van vragen

Zijn er regels die Claude echt nooit mag overslaan, zoals de formatter na elke wijziging of nooit in de migratiemap schrijven? Volg de tutorial Claude Code hooks. Wil je dat Claude eerst een plan laat zien voor grote wijzigingen, lees dan plan mode.

Procedures in skills

Groeit een stuk van je CLAUDE.md uit tot een stappenplan, verplaats het dan naar een skill. Hoe dat werkt staat op Claude Skills en in Claude skills voor je team.

Naslag over alle varianten

De volledige laadvolgorde, auto memory en de instellingen eromheen staan in de commands-gids en bij geheugen in Claude Code. De korte definitie staat in het woordenboek bij CLAUDE.md en AGENTS.md.

Meer tutorials

Je project op GitHub zetten en Claude pull requests laten maken: Claude Code en GitHub. Claude Code met je andere systemen verbinden: een MCP-server toevoegen. Een complete set agents, skills en hooks in één keer: Everything Claude Code.