CLAUDE.md uitgelegd: leer Claude Code je project één keer kennen

Elke nieuwe Claude Code-sessie begint met een leeg hoofd. Je vertelt dat het pnpm moet gebruiken, geen npm. Je vertelt waar de tests staan. Je vertelt dat het de gegenereerde map met rust moet laten. Morgen vertel je dat allemaal opnieuw.

Het is een gewoon tekstbestand in Markdown. Claude Code leest het aan het begin van elke sessie, dus wat erin staat is al bekend vóór je eerste prompt. Deze gids laat zien waar het bestand komt, hoe je er een schrijft die Claude volgt en wat je erbuiten houdt.

Wat CLAUDE.md is, en wat niet

Elke Claude Code-sessie begint met een vers contextvenster. Twee mechanismen nemen kennis mee van de ene sessie naar de volgende:

Beide worden als context geladen. Dat woord is belangrijk: Claude leest CLAUDE.md en probeert het te volgen, maar het is geen instelling die wordt afgedwongen. Een vage of tegenstrijdige regel kan genegeerd worden. Daar komen we terug in het onderdeel over problemen oplossen, want het bepaalt hoe je het bestand moet schrijven.

Waar het bestand komt

Er zijn vier plekken, en ze stapelen. Claude laadt ze van de breedste naar de meest specifieke reikwijdte, dus wat dichter bij je project ligt wordt als laatste gelezen.

De twee die je gebruikt zijn het projectbestand en het gebruikersbestand.

• Projectbestand. Zet CLAUDE.md in de hoofdmap van je project, of in een map .claude in de hoofdmap. Commit het, zodat iedereen die aan het project werkt dezelfde instructies krijgt. Schrijf op wat voor iedereen geldt: buildcommando's, conventies, projectopzet.
• Gebruikersbestand. ~/.claude/CLAUDE.md gaat met je mee naar elk project. Gebruik het voor persoonlijke gewoonten, zoals hoe je uitleg graag geformuleerd ziet.
• Lokaal bestand. CLAUDE.local.md is voor notities die van jou zijn en bij één project horen, zoals een sandbox-URL. Zet het in je .gitignore zodat het niet wordt gecommit.

Claude kijkt ook in de map waarvandaan je startte en in elke map daarboven. Start je in foo/bar/, dan laadt het foo/bar/CLAUDE.md en foo/CLAUDE.md. Bestanden in mappen onder je laden later, op aanvraag, de eerste keer dat Claude een bestand in die submap leest of bewerkt.

Begin met /init

De eerste versie hoef je niet met de hand te schrijven. Draai in een sessie:

> /initJe codebase wordt geanalyseerd...CLAUDE.md aangemaakt met buildcommando's, testinstructies en conventies die het vond.

Claude Code leest je project en schrijft een CLAUDE.md met de build- en testcommando's en conventies die het ontdekt. Bestaat er al een CLAUDE.md, dan stelt /init verbeteringen voor in plaats van te overschrijven. Zie het resultaat als een eerste concept. Jouw taak is toe te voegen wat Claude niet zelf had kunnen uitzoeken.

Om te controleren of het bestand is geladen, draai je /context in een sessie en kijk je onder Memory files.

Wat in het bestand hoort

Een goede toets, voordat je een regel schrijft, bestaat uit twee vragen:

Zijn beide antwoorden ja, laat de regel dan weg. Wat overblijft is informatie die nooit in de code stond, of die echt tijd kost om opnieuw te ontdekken:

Voeg een regel toe als Claude dezelfde fout voor de tweede keer maakt, als een codereview iets vindt dat het had moeten weten, of als je dezelfde correctie typt als de vorige sessie. Dat is het signaal dat het feit in het bestand hoort.

Een voorbeeld om te kopiëren

Hier is een kort projectbestand. Let op hoe elke regel iets is wat je kunt controleren, en hoe weinig de architectuur beschrijft.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

Dat zijn 15 regels, en elke regel verdient zijn plek.

Zo schrijf je regels die Claude volgt

Omdat CLAUDE.md context is en geen configuratie, bepaalt de formulering of een regel gevolgd wordt. Schrijf instructies die concreet genoeg zijn om te controleren.

Houd het bestand daarna in model:

• Kort. Mik op minder dan 200 regels per bestand. Langere bestanden gebruiken meer context en Claude volgt ze minder betrouwbaar.
• Georganiseerd. Groepeer verwante regels onder Markdown-koppen en opsommingen. Claude volgt structuur beter dan dichte alinea's.
• Consistent. Spreken twee regels elkaar tegen, dan kiest Claude misschien lukraak. Lees je bestanden af en toe door, ook die in submappen, en verwijder wat verouderd is.

Wil je dat Claude je instructiebestanden controleert op verouderde of tegenstrijdige regels, draai dan /doctor prompt-audit. Het meldt bevindingen en stelt wijzigingen voor, maar verandert niets tot jij erom vraagt. Het vereist Claude Code 2.1.283 of nieuwer.

Andere bestanden importeren

CLAUDE.md kan andere bestanden binnenhalen met een @ voor het pad. Het geïmporteerde bestand wordt geladen naast de CLAUDE.md die het noemt.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

Relatieve paden worden opgelost vanaf het bestand dat de import bevat. Imports kunnen zelf weer bestanden importeren, tot vier niveaus diep. De @ wordt alleen gelezen buiten codefragmenten, dus zet een pad tussen backticks als je het wilt noemen zonder het te importeren.

Imports zijn goed voor de organisatie, maar ze verkleinen de context niet: geïmporteerde bestanden worden nog steeds volledig geladen. Voor persoonlijke instructies die je in meerdere kopieën van dezelfde repository wilt, importeer je een bestand uit je homemap, zoals @~/.claude/my-project-instructions.md. De eerste keer dat een project een bestand van buiten de werkmap importeert, vraagt Claude Code om je goedkeuring.

Als één bestand te lang wordt

Op een gegeven moment groeit het bestand voorbij wat elke sessie nodig heeft. Je hebt vier gereedschappen, elk voor een andere klus.

Regels voor bepaalde bestanden

Zet per onderwerp één Markdown-bestand in .claude/rules/, zoals testing.md of api-design.md. Wil je dat een regel alleen voor bepaalde bestanden geldt, voeg dan bovenaan een veld paths toe:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Use the standard error response format

Een regel zonder paths laadt elke sessie. Een afgebakende regel laadt als Claude een passend bestand leest of bewerkt, zodat de instructies de rest van de tijd uit de weg blijven.

Is een blok in CLAUDE.md een procedure met meerdere stappen, zoals het voorbereiden van een release, verplaats het dan naar een skill. Skills laden alleen als ze worden gebruikt.

Auto memory: de notities die Claude voor zichzelf bijhoudt

Naast het bestand dat jij schrijft kan Claude Code zelf notities bijhouden. Auto memory staat standaard aan in lokale sessies. Terwijl Claude werkt, bewaart het vier soorten notities: over jou (rol en voorkeuren), feedback (correcties en aanpakken die je bevestigde), het project (beslissingen en deadlines die niet in de code staan) en verwijzingen (waar je dingen buiten het project vindt).

Het bewaart niet wat het uit de code kan lezen, of wat je CLAUDE.md al zegt. In de sessie zie je berichten als "Saved 2 memories". De notities zijn gewone Markdown onder ~/.claude/projects/, en de eerste 200 regels of 25 KB van het indexbestand worden aan het begin van elke sessie geladen.

Draai /memory om alle instructiebestanden en de auto memory-map te zien, om ze in je editor te openen en om auto memory aan of uit te zetten. Zeg je tegen Claude "always use pnpm, not npm", dan bewaart het dat in auto memory. Wil je iets juist in CLAUDE.md, zeg dat dan: "add this to CLAUDE.md".

In Claude Tutorial

Opschrijven wat je anders zou herhalen

Dezelfde correctie omzetten in een vaste instructie is een gewoonte die loont bij elk soort werk met Claude, niet alleen bij code, en de app leert je die stap voor stap.

Binnenkort

Download in deApp Store

DOWNLOAD VIAGoogle Play

Als Claude het niet volgt

Loop deze punten op volgorde door. Ze lossen de meeste gevallen op.

Twee extra gevallen zijn goed om te kennen. Na een /compact wordt de CLAUDE.md in de hoofdmap van je project opnieuw van schijf gelezen, dus die blijft behouden. Een instructie die je alleen in de conversatie gaf, blijft niet behouden, dus zet die in het bestand. En als een CLAUDE.md in een submap erg lang is (meer dan ongeveer 40.000 tekens in een kleiner contextvenster), krijgt Claude alleen het begin, dus houd die kort.

Veelgestelde vragen

Waar zet ik CLAUDE.md?

In de hoofdmap van je project (./CLAUDE.md) of in ./.claude/CLAUDE.md. Zet persoonlijke voorkeuren voor alle projecten in ~/.claude/CLAUDE.md. Gebruik ./CLAUDE.local.md, toegevoegd aan .gitignore, voor privénotities over één project.

Hoe lang mag een CLAUDE.md zijn?

Mik op minder dan 200 regels. Zit je erboven, dan toont Claude Code een waarschuwing bij het opstarten en in /status. Verplaats gebiedsspecifieke delen naar afgebakende regels en schrap wat Claude uit de code kan lezen.

Is CLAUDE.md hetzelfde als een systeemprompt?

Nee. CLAUDE.md wordt geleverd als bericht na de systeemprompt. Claude probeert het te volgen, maar strikte naleving is niet gegarandeerd. Gebruik voor instructies die altijd moeten gelden een hook of een toestemmingsregel.

Moet ik CLAUDE.md in git committen?

Ja voor het projectbestand, zodat het hele team het deelt en het met elke correctie beter wordt. Nee voor CLAUDE.local.md, dat is persoonlijk.

Leest Claude CLAUDE.md in submappen?

Ja, op aanvraag. Het laadt het bestand van een submap de eerste keer dat Claude een bestand in die map leest of bewerkt, en toont een regel Loaded met het pad.

Wat is het verschil tussen CLAUDE.md en een skill?

CLAUDE.md is voor feiten die elke sessie nodig zijn. Een skill is een procedure of draaiboek dat alleen laadt als het wordt aangeroepen of relevant is, en dus de rest van de tijd geen ruimte inneemt.

Je CLAUDE.md-checklist

Verder lezen

• Claude Code voor beginners: installeren, inloggen en je eerste taak als je nog geen sessie hebt gestart.
• Claude Code: gewoonten voor betere resultaten voor prompts, controles en contextbeheer.
• Claude Code: permission modes en Plan-modus uitgelegd om te bepalen wat Claude zonder te vragen mag doen.
• Claude Projects: context die blijft hangen voor hetzelfde idee in de Claude-app: vaste instructies die bij een project blijven.