CLAUDE.md is een Markdown-bestand in de root van je repository dat Claude Code automatisch inleest aan het begin van elke sessie. Zie het als een onboarding-script voor je codebase: erin staat wat het model over je project moet weten, je stack, je conventies, de commando's die je draait. De inhoud wordt aan je prompt toegevoegd. Claude onthoudt je project niet tussen sessies, maar het leest dit bestand voordat het iets anders doet, en dat komt praktisch op hetzelfde neer.
Waarom je dat wilt, weet je zodra je Claude Code langer dan een dag hebt gebruikt. Je opent een nieuwe sessie, vraagt het iets te bouwen, en het begint je codebase helemaal opnieuw te verkennen. Het leest je dependencies opnieuw. Het raadt je conventies. Het doet aannames over je stack die je vervolgens moet corrigeren. Elke. Keer. Weer.
Zo maak je er een
Je kunt er direct een genereren:
/initClaude scant je codebase en genereert een CLAUDE.md op basis van wat het vindt. Een prima startpunt, maar je wilt het zeker aanscherpen.
Wat erin hoort
Een goed CLAUDE.md-bestand is kort en opinionated. Het beantwoordt de drie vragen die Claude zichzelf stelt aan het begin van elke sessie: Wat is dit project? Hoe moet ik hier code schrijven? Welke commando's heb ik nodig?
Dit is de structuur die ik aanhoud:
Stack
Vertel Claude waar het mee werkt. Framework, taalversie, ORM, CSS-aanpak. Laat het niet gokken.
- Next.js 15, App Router
- TypeScript (strict mode)
- Tailwind CSS
- Drizzle ORMVoorkeuren
Hier leg je je conventies vast. Named exports of default exports? Tabs of spaties? Server actions of API routes? Elk team heeft meningen. Schrijf ze op.
- Use two-space indentation
- Prefer named exports
- Use server actions instead of API routes where possible
- All API routes go in app/api/Commando's
Vertel Claude hoe het dingen moet draaien. Dev server, tests, linting. Ga er niet van uit dat het dat weet.
- Dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`Dat is het. Drie secties. Houd het compact. Een CLAUDE.md van drie pagina's lang schiet zijn doel voorbij: je verbrandt context-tokens aan instructies in plaats van aan daadwerkelijk werk.
De hiërarchie
Er is meer dan één plek om een CLAUDE.md te plaatsen. Het bestandssysteem volgt een hiërarchie:
Projectniveau (CLAUDE.md in de root van je repository): gedeelde context over dit specifieke project. Dit is het bestand dat je commit naar versiebeheer. Je hele team profiteert ervan.
Gebruikersniveau (CLAUDE.md in je Claude-configuratiemap): persoonlijke voorkeuren die gelden voor al je projecten. Zaken als je gewenste commentaarstijl, je editor-conventies, hoe je foutmeldingen het liefst geformatteerd ziet. Dit bestand blijft op je eigen machine.
Het projectniveau-bestand heeft voorrang voor projectspecifieke instructies, terwijl de voorkeuren op gebruikersniveau de gaten opvullen.
Drie tips die echt uitmaken
Begin zonder. De aanbeveling van Anthropic zelf, en ik ben het ermee eens: begin een nieuw project zonder CLAUDE.md en let op waar je het model constant moet bijsturen. Die correcties zijn precies wat in het bestand hoort. Zo houd je het slank en relevant, in plaats van opgeblazen met instructies die Claude toch al zou volgen.
Gebruik @-referenties. Als je project documentatie, architecture decision records of API-specs heeft, plak ze dan niet in CLAUDE.md. Verwijs ernaar:
Refer to @docs/architecture.md for the system design.
Refer to @docs/api-spec.yaml for endpoint contracts.Claude leest die bestanden wanneer het ze nodig heeft, waardoor je CLAUDE.md compact blijft terwijl het toch toegang heeft tot diepere context.
Vraag Claude om correcties op te slaan in het geheugen. Wanneer je Claude tijdens een sessie corrigeert, zoals "gebruik altijd server actions in plaats van API routes", vraag het dan expliciet om dit in het geheugen op te slaan. De volgende sessie weet Claude het al. Dit is de weg van de minste weerstand om je CLAUDE.md in de loop der tijd te laten evolueren.
Het verschil dat het maakt
Het verschil tussen een frustrerende Claude Code-sessie en een productieve is bijna altijd een contextprobleem. Claude is capabel, maar niet helderziend. Zonder CLAUDE.md is elke sessie een koude start. Met een CLAUDE.md loopt Claude naar binnen terwijl het je stack, je conventies en je commando's al kent.
Het is hetzelfde principe als waar ik het eerder over had bij de hooks-gids en Superpowers: hoe minder tijd Claude besteedt aan uitzoeken hoe je werkt, hoe meer tijd het besteedt aan daadwerkelijk werk.
Begin met je stack, je voorkeuren en je commando's. Bouw het daarna stap voor stap uit, en snoei net zo vaak als je toevoegt, want verouderd geheugen is erger dan geen geheugen. Meer is het niet.
Eén kanttekening zodra het bestand niet langer alleen van jou is: een CLAUDE.md in een gedeelde repo gedraagt zich anders dan eentje op je eigen machine, en dat geldt voor de rest van .claude/ net zo goed. Wat een repo in een team wel en niet afdwingt, heb ik apart uitgeschreven.