Naar de inhoud
Mia Automation
NLEN Inloggen Zet Mia aan het werkBeginnen

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.

Claude in de praktijkBijgewerkt op 6 min lezen

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.

Schema: bij de start laadt Claude Code de CLAUDE.md van de organisatie, van jezelf en van het project. Een taak over een factuur haalt daarna docs/facturen.md erbij, een planningstaak docs/planning.md
Wat altijd meekomt en wat alleen als de taak erom vraagt. Zo werkte het in onze proef.
Volgens de documentatie van Claude Code, gecontroleerd op 11 november 2026.
BestandWaarVoor wie
Projectregels./CLAUDE.md of ./.claude/CLAUDE.mdIedereen 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.mdAlleen voor jezelf, in elk project
Regels van de organisatieWindows: C:\Program Files\ClaudeCode\CLAUDE.md, macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdIedereen op die computer; gaat vóór de rest

Een CLAUDE.md maken in vijf stappen

  1. 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
    /init
  2. Schrijf 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.

  3. 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.’

  4. 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.

  5. 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.

markdown
# 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.

TaakZonder deze CLAUDE.mdMet deze CLAUDE.md
Gemiddeld factuurbedrag per klant (3 keer)1 van 3 keer met float gerekend3 van 3 keer met Decimal en ROUND_HALF_UP
Factuurregel met btw en vervaldatum (2 keer)Niet getest2 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 getest2 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 getestdocs/planning.md gelezen en de klus geweigerd: buitenwerk alleen van april tot en met oktober
Links het CLAUDE.md-bestand uit de proef met de regel over docs/planning.md gemarkeerd, rechts het planningsvoorstel waarin Claude Code schrijft dat de klus in november niet kan omdat buitenwerk alleen van april tot en met oktober gebeurt (opent op ware grootte)
Onze CLAUDE.md naast wat Claude Code maakte van een planningsvraag. Het las de planningsregels door de gemarkeerde regel en zette de klus door naar april.

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 zietWaarschijnlijke oorzaakWat je doet
Een regel wordt soms genegeerdHet bestand is te lang of de regel is vaagOnder de 200 regels blijven; de regel concreet maken, met voorbeeld
Claude Code kiest willekeurig tussen twee regelsTwee regels spreken elkaar tegen, bijvoorbeeld in een submapEén regel laten staan en zeggen welke hij vervangt
Iets wat echt niet mag, gebeurt tochCLAUDE.md is context, geen slotGebruik een hook: een stukje code dat de actie vooraf weigert
Je AGENTS.md wordt niet gelezenEr staat ook een CLAUDE.md in de map of erbovenZet @AGENTS.md in je CLAUDE.md, dan leest hij beide
Een import met @ laadt nietEr staat een spatie in het padZet 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