CLAUDE.md: het briefje dat Claude Code elke keer eerst leest.

CLAUDE.md is een gewoon tekstbestand in de map van je project. Claude Code leest het aan het begin van elk gesprek. Je zet erin wat Claude altijd moet weten: hoe je werkt, wat nooit mag en hoe je je werk nakijkt. Zo leg je niet elke avond hetzelfde uit. Met /init schrijft Claude zelf een eerste versie.

Ik ben stukadoor en geen programmeur. Mijn eigen CLAUDE.md is vijf regels tekst, met drie vaste werkregels erin. Die leest Claude in elk gesprek dat ik met Claude Code voer. Hoe ik verder bouw, lees je op de pagina over mij.

Wat is een CLAUDE.md?

Elk gesprek met Claude Code begint met een leeg hoofd. Alleen wat in je bestanden staat, en de notities die Claude zelf bijhoudt, gaat mee. Dat is handig, want oude rommel sleept niet mee. Maar zonder zo’n bestand zou je elke keer opnieuw moeten vertellen hoe je werkt.

Daar is CLAUDE.md voor. Zie het als het briefje dat je op de bouwplaats achterlaat voor wie morgen begint: waar de sleutel ligt, wat niet aangeraakt mag worden, wanneer het werk af is. Claude leest dat briefje aan het begin van elk gesprek, nog voor je eerste vraag.

Eén nieuw woord: context. Dat is alles wat Claude op dat moment weet. Wat in CLAUDE.md staat, hoort vanaf de eerste minuut bij die context. Wat Claude Code verder is en kan, staat in wat is Claude Code.

Eerlijk antwoord over wat het níet is: een slot. Anthropic schrijft zelf dat Claude het bestand als context leest en niet als een vaste instelling. Meestal houdt hij zich eraan, maar het is geen hek. Wil je dat iets echt nooit gebeurt, dan noemt de handleiding daarvoor een hook: een stukje code dat een actie tegenhoudt.

Mijn eigen ervaring is nuchterder: in de praktijk doet Claude wat erin staat. Ik stuur hem af en toe een klein beetje bij en kijk zijn werk na. Daar heb ik ook skills voor gemaakt, zoals het vangnet.

Waar staat de CLAUDE.md file?

Er zijn drie plekken die je als beginner moet kennen. Je kunt er één gebruiken of alle drie.

Het teken ~ staat voor je eigen thuismap op de Mac. De map .claude begint met een punt, en daarom zie je hem in de Finder niet meteen. Druk op Cmd + Shift + punt om verborgen mappen te tonen.

Claude legt de bestanden achter elkaar, hij vervangt er geen. Start je Claude Code in een map, dan leest hij de CLAUDE.md van die map en van alle mappen erboven. Een CLAUDE.md in een submap komt pas mee als Claude daar een bestand opent. Wat het dichtst bij je startmap staat, leest hij als laatste.

Een CLAUDE.md maken met /init

Je hoeft niet met een leeg bestand te beginnen. Typ in Claude Code:

> /init

Claude bekijkt dan je project en schrijft een eerste CLAUDE.md: hoe je het start, hoe je test, welke afspraken hij ziet. Staat er al een CLAUDE.md, dan stelt /init verbeteringen voor en overschrijft hij niets. Lees die eerste versie altijd na. Claude ziet je bestanden, maar niet wat jij belangrijk vindt.

Een regel erbij zetten kan ook gewoon in gewone taal: “zet dit in CLAUDE.md”. Met /memory zie je welke bestanden er zijn en open je ze om zelf te typen. Het commando /init staat ook in een filmpje van acht seconden op de Claude Code-pagina.

Eerlijk: wat hier over /init staat, heb ik nagelopen in de handleiding van Anthropic op 6 oktober 2026. Ik heb het niet opnieuw nagedaan in de versie bovenaan deze pagina.

Een CLAUDE.md voorbeeld: de mijne

Dit is het bestand dat bij mij in ~/.claude/ staat. Het geldt dus voor elk project. Ik laat per regel de kop en het begin zien:

# Tims vaste werkregels (alle projecten)1. Eerst rood, dan groen. Schrijf de controle (test, proef, check) vóór de fix en laat hem eerst aantoonbaar falen; …2. Nooit deployen met rood. Geen deploy om de poort heen …3. Eén fase per vers gesprek. Meerdaags werk staat in een fasekaart in de repo, met bovenaan een startzin …

Drie regels, en ze gaan alle drie over hoe ik werk, niet over code. Eerst een controle die faalt, dan pas de reparatie. Niets online zetten zolang er iets rood staat. En groot werk in stukken, elk stuk in een vers gesprek.

Mijn grotere projecten hebben daarnaast een eigen CLAUDE.md. Die van deze site heeft 62 regels en ik noem hem het contract. De volgorde is bewust: bovenaan staat dat ik beslis, dan dat elke bewering een bron heeft, dan hoe ik klink. Daarnaast staan er drie regelbestanden in .claude/rules/. Twee daarvan, zoals de regels voor de kleuren, laadt Claude pas als hij aan zulke bestanden werkt. Het derde, met wat hij nooit mag aanraken, laadt altijd.

De les die ik eruit haal: één bestand met wat altijd geldt, en per project een bestand met wat daar geldt.

Wat zet je erin, en wat niet?

Een goede vraag om jezelf te stellen: wat leg ik nu elke keer opnieuw uit? Dat hoort erin.

Geheimen horen in een koppeling of in een apart bestand dat je nooit deelt, nooit in CLAUDE.md. Hoe je een dienst met een sleutel koppelt, lees je bij Claude Code MCP.

CLAUDE.md best practices: kort en na te kijken

Dit zijn de regels uit de handleiding van Anthropic, plus wat ik er zelf aan heb toegevoegd.

• Onder de 200 regels. Een te lang bestand kost ruimte in het gesprek, en Claude volgt het slechter.
• Schrijf het zo dat je het kunt controleren. “Draai npm test voor je iets afrondt” werkt. “Test je werk” niet: wanneer is dat gelukt?
• Geen regels die botsen. Zeggen twee regels iets anders, dan kan Claude er zomaar één kiezen. Lees je bestand af en toe na.
• Maakt Claude dezelfde fout een tweede keer? Dan komt er een regel bij. Zo groeit het bestand met je werk mee.
• Zet het waarom erbij. Dat is mijn eigen gewoonte, niet uit de handleiding. In het CLAUDE-voorbeeld van mijn gratis vangnet staat onder elke regel een regel “Waarom”.
• Gewoon in het Nederlands. Ook dat is mijn eigen ervaring: de handleiding noemt geen verplichte taal. Commando’s en bestandsnamen schrijf je wel letterlijk.

Een lang bestand opdelen kan met @pad/naar/bestand: dan haalt CLAUDE.md een tweede bestand erbij. Let op, ook dat tweede bestand laadt meteen bij de start. Ruimte bespaar je er dus niet mee, alleen overzicht.

CLAUDE.md, AGENTS.md en skills: wat is het verschil?

Drie soorten bestanden met instructies, en ze worden vaak door elkaar gehaald.

AGENTS.md is het bestand dat andere bouwhulpen lezen. Claude Code leest het sinds versie 2.1.277 ook, maar alleen als er in je map of erboven geen CLAUDE.md of CLAUDE.local.md staat. Heb je allebei, dan telt alleen CLAUDE.md, tenzij je AGENTS.md vanuit je CLAUDE.md laat inlezen.

Een skill is een werkwijze die Claude alleen pakt als de klus erom vraagt. Mijn vuistregel: CLAUDE.md is voor wat altijd geldt, een skill voor wat soms geldt. Voorbeelden van skills die ik gratis deel staan bij Claude skills.

Leest Claude mijn CLAUDE.md wel?

Twijfel je of Claude je bestand ziet? Typ in Claude Code /context. Daar staat een lijst met de bestanden die bij de start zijn geladen. Staat je CLAUDE.md er niet tussen, dan kan Claude hem ook niet zien. Een CLAUDE.md in een submap staat daar pas als Claude in die submap aan het werk is geweest.

Een tweede proef: begin een vers gesprek en vraag “wat zijn mijn vaste regels?”. Noemt Claude ze, dan werkt het. En wordt een gesprek te lang en vat Claude het samen met /compact, dan leest hij de CLAUDE.md in je projectmap daarna opnieuw van schijf. Wat je alleen in het gesprek zei, is dan wel weg. Daarom zet je een afspraak die moet blijven in het bestand.

Wil je mijn drie regels in je eigen project? Het CLAUDE-voorbeeld zit in de gratis skill Het vangnet, op de pagina met mijn skills. Meer uitleg in gewone taal staat op de Claude Code-pagina met alle artikelen.