Een CLAUDE.md-bestand schrijven in 2026: een praktische gids

Een CLAUDE.md-bestand is een gewoon Markdown-bestand dat Claude Code aan het begin van elke sessie automatisch inleest, waarmee je het model blijvende instructies meegeeft die het niet uit je code kan afleiden: buildcommando's, conventies, architectuur en de "doe altijd X"-regels die je beu bent om steeds te herhalen. Zet het in de root van je project, houd het onder de ~200 regels en vul het met specifieke, verifieerbare instructies in plaats van een uitgestort wiki. Deze gids behandelt waar het bestand hoort te staan, wat erin thuishoort, hoe je bestaande documentatie importeert en hergebruikt, en hoe je het genereert en opschoont met Claude Code's eigen commando's.

Het loont om vooraf precies te zijn, want de meeste artikelen halen twee dingen door elkaar die Claude Code juist gescheiden houdt: de CLAUDE.md die jij schrijft, en het automatische geheugen dat Claude voor zichzelf schrijft. We behandelen beide, en waarom het bestand dat je met de hand schrijft nog altijd het meest impactvolle onderdeel van de setup is.

Wat is een CLAUDE.md-bestand?

Een CLAUDE.md-bestand is de instructielaag voor Claude Code. Bij het starten van een sessie laadt Claude Code het in het contextvenster en levert het als een bericht dat Claude leest voordat het je code aanraakt. De documentatie van Anthropic omschrijft het als de plek om "op te schrijven wat je anders opnieuw zou moeten uitleggen" — de techstack, hoe je tests draait, naamgevingsconventies en architecturale keuzes die een nieuwe teamgenoot nodig zou hebben. Het is Markdown, dus koppen en opsommingen zijn alle structuur die je nodig hebt.

Eén nuance waar de documentatie expliciet over is: CLAUDE.md is context, geen afgedwongen configuratie. Claude leest het en probeert het op te volgen, maar er is geen harde garantie, zeker niet bij vage of tegenstrijdige regels. Alles wat op een vast punt moet gebeuren — "draai de linter vóór elke commit" — hoort in een hook thuis, niet in een regel proza. Dat onderscheid bepaalt alles wat hieronder volgt.

Waar je je CLAUDE.md-bestand plaatst

CLAUDE.md kan op verschillende plekken staan, en Claude Code laadt ze in volgorde van het breedst naar het meest specifiek, waarbij het ze allemaal aan elkaar plakt in plaats van te overschrijven. Een projectinstructie komt in de context na een gebruikersinstructie, dus het meer specifieke bestand wordt als laatste gelezen.

Bereik	Locatie	Doel	Gedeeld met
Beheerd beleid	/etc/claude-code/CLAUDE.md (Linux/WSL); /Library/Application Support/ClaudeCode/CLAUDE.md (macOS); C:\Program Files\ClaudeCode\CLAUDE.md (Windows)	Organisatiebrede standaarden die IT uitrolt	Iedereen op de machine
Gebruiker	~/.claude/CLAUDE.md	Je persoonlijke voorkeuren over al je projecten heen	Alleen jij
Project	./CLAUDE.md of ./.claude/CLAUDE.md	Team-gedeelde projectregels	Je team, via git
Lokaal	./CLAUDE.local.md	Privénotities per project (zet het in je gitignore)	Alleen jij, dit project

Claude Code leest CLAUDE.md uit je werkmap en uit elke map daarboven, dus in een monorepo gelden zowel een root-bestand als een bestand op pakketniveau. Bestanden in submappen onder jou worden op aanvraag geladen, alleen wanneer Claude daar bestanden leest. Draai /context in een sessie en controleer de lijst Memory files om te bevestigen wat er daadwerkelijk is geladen — dit is de snelste manier om "Claude negeert mijn CLAUDE.md" te debuggen, wat vrijwel altijd een bestand is dat niet op een geladen locatie staat.

Wat je in een CLAUDE.md-bestand zet (en wat je weglaat)

De beste CLAUDE.md is een korte lijst met concrete, controleerbare feiten. Neem build- en testcommando's op, de indeling van het project, conventies die afwijken van de standaardinstellingen van je tools, en de fouten die je meer dan eens hebt moeten corrigeren. Schrijf "Draai npm test vóór het committen" en "API-handlers staan in src/api/handlers/", niet "test je wijzigingen" of "houd je bestanden georganiseerd" — specificiteit is waar Claude daadwerkelijk naar kan handelen.

Wat je weglaat is minstens zo belangrijk. Laat het model niet het werk van een linter doen; als je ESLint of Prettier hebt, laat die dan de stijl afdwingen en houd het uit het bestand. Sla alles over wat Claude rechtstreeks uit de codebase kan lezen — mappenstructuren, afhankelijkhedenlijsten en architectuuroverzichten zijn precies wat de /doctor-check van Claude Code zal voorstellen om weg te snoeien. Taakspecifieke procedures met meerdere stappen horen thuis in een Claude Code-skill die op aanvraag laadt, en alles wat padspecifiek is ("alle API-endpoints hebben inputvalidatie nodig") hoort in een .claude/rules/-bestand dat is afgebakend met een paths:-glob, zodat het alleen in de context komt wanneer Claude overeenkomende bestanden aanraakt. Een goede vuistregel: als een item niet in elke sessie nuttig is, hoort het niet in CLAUDE.md.

Houd het kort: CLAUDE.md is een tokenbudget, geen wiki

Omdat CLAUDE.md bij elke beurt wordt geladen, kost elke regel context. Het doel dat Anthropic noemt is minder dan 200 regels per bestand; langere bestanden verbruiken meer context en verminderen meetbaar hoe nauwgezet Claude ze opvolgt (een bestand groter dan 4 MiB wordt volledig overgeslagen). Het context-engineeringteam bij HumanLayer gaat nog verder en houdt hun eigen bestand onder de 60 regels, en verwijst naar het praktische plafond dat frontier-modellen betrouwbaar slechts zo'n ~150–200 instructies opvolgen — en de systeemprompt van Claude Code zelf verbruikt er al zo'n 50 voordat je één woord hebt geschreven.

Het mentale model dat helpt: behandel CLAUDE.md als RAM, en skills, rules en referentiedocumentatie als schijf. Je laadt niet de hele harde schijf bij het opstarten. Zet de altijd-geldende regels in CLAUDE.md en verwijs naar alles wat situationeel is met een link of een import. Kruipt het bestand voorbij de 200 regels, dan is dat het signaal om te splitsen, niet om te blijven scrollen.

Importeer andere bestanden en hergebruik je AGENTS.md

CLAUDE.md kan andere bestanden binnenhalen met de syntaxis @pad/naar/bestand. Imports vouwen zich bij het starten uit in de context, paden mogen relatief of absoluut zijn, en ze kunnen tot vier niveaus diep genest worden. Zet een pad tussen backticks wanneer je het wilt noemen zonder het te importeren.

Het nuttigste geval is interoperabiliteit. Claude Code leest CLAUDE.md, niet AGENTS.md — dus als je repo al de cross-tool AGENTS.md-standaard gebruikt, dupliceer die dan niet. Maak een CLAUDE.md die het importeert en voeg eronder eventuele Claude-specifieke notities toe:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Een symlink (ln -s AGENTS.md CLAUDE.md) werkt ook als je geen Claude-specifieke toevoegingen nodig hebt. Eén kanttekening: een import die buiten je werkmap uitkomt, activeert een eenmalig goedkeuringsvenster, een bewuste beveiliging tegen bestanden die anderen naar een gedeelde repo committen.

Genereren en onderhouden met /init, /memory en /doctor

Je hoeft niet met een leeg bestand te beginnen. Draai /init en Claude analyseert de codebase en schrijft een startversie van CLAUDE.md met de buildcommando's, teststappen en conventies die het ontdekt; bestaat er al één, dan stelt het verbeteringen voor in plaats van te overschrijven. Het leest zelfs bestaande Cursor- en Copilot-regelbestanden en verwerkt de relevante delen erin. Behandel de uitvoer als een concept — de echte waarde zit in de handvol instructies die Claude niet kon afleiden, die je er achteraf aan toevoegt.

Vanaf daar toont /memory elk geheugenbestand over alle bereiken heen en opent het, en /doctor stelt snoeiwerk voor een ingecheckte CLAUDE.md voor, waarbij het afleidbare inhoud weghaalt maar de valkuilen en onderbouwing behoudt. Wanneer je Claude vertelt "voeg dit toe aan CLAUDE.md", bewerkt het het bestand rechtstreeks. En omdat het bestand gewoon Markdown in versiebeheer is, gaan wijzigingen door code review zoals elk ander onderdeel van de repo — en zo blijft de CLAUDE.md die onze eigen publicatiepijplijn hier bij TechRiseUps aanstuurt in de loop van de tijd eerlijk.

CLAUDE.md versus automatisch geheugen

Recente versies van Claude Code voegden een tweede, automatisch geheugensysteem toe, en dat is makkelijk te verwarren met CLAUDE.md. De scheiding is helder: jij schrijft CLAUDE.md (instructies en regels); Claude schrijft het automatische geheugen (dingen die het waarneemt over je voorkeuren en correcties). Het automatische geheugen staat in ~/.claude/projects/<project>/memory/, met een MEMORY.md-index waarvan de eerste 200 regels (of 25KB) elke sessie laden en onderwerpbestanden die op aanvraag laden.

Houd ze in hun eigen baan. CLAUDE.md is jouw eisen; het automatische geheugen is wat Claude heeft geleerd over hoe je werkt. Claude slaat bewust niets op wat je CLAUDE.md al vermeldt, dus een strakke CLAUDE.md maakt ook het automatische geheugen schoner. Je kunt het allemaal bekijken, bewerken of verwijderen via /memory — het is allemaal gewone Markdown.

Veelgestelde vragen

Wat moet ik in mijn CLAUDE.md-bestand zetten? Build- en testcommando's, projectstructuur, conventies die afwijken van de standaard, en de correcties die je jezelf steeds ziet herhalen. Houd elk item specifiek en verifieerbaar. Laat codestijl weg (gebruik een linter), taakspecifieke procedures (gebruik skills) en alles wat Claude uit de code kan lezen.

Hoe schrijf ik het perfecte CLAUDE.md-bestand? Een perfecte bestaat niet, maar het betrouwbare patroon is kort en specifiek: onder de 200 regels, concrete instructies, gegroepeerd onder Markdown-koppen, met situationele details weggeschoven naar imports, rules of skills. Begin met /init, snoei daarna met /doctor en verfijn naarmate Claude fouten maakt.

Kan Claude het CLAUDE.md-bestand voor mij aanmaken? Ja. Met /init genereer je een startversie van CLAUDE.md op basis van je codebase, en je kunt Claude op elk moment vragen om items toe te voegen of te bewerken. Het uiteindelijke bestand blijft van jou — maak de regels die het niet zelf kon ontdekken met de hand.

Hoe verschilt CLAUDE.md van AGENTS.md? AGENTS.md is een cross-tool open standaard; CLAUDE.md is het bestand dat Claude Code daadwerkelijk laadt. Claude Code leest AGENTS.md niet rechtstreeks, dus als je er één onderhoudt, importeer die dan in CLAUDE.md met @AGENTS.md of symlink de twee, in plaats van dubbele bestanden bij te houden.

Waarom negeert Claude mijn CLAUDE.md? Meestal staat het bestand niet op een geladen locatie — draai /context en controleer Memory files. Is het wel geladen maar dwaalt Claude toch af, maak de instructie dan specifieker, verwijder tegenstrijdigheden, en verplaats alles wat altijd moet draaien naar een hook in plaats van op proza te vertrouwen.

Sources

• Claude Code docs — How Claude remembers your project: officiële referentie voor CLAUDE.md-locaties, laadvolgorde, imports, groottelimieten, /init, /memory en automatisch geheugen.
• HumanLayer — Writing a good CLAUDE.md: context-engineeringrichtlijnen over lengte, progressive disclosure en het plafond van ~150–200 instructies.