Als je Claude Code langer dan een dag hebt gebruikt, heb je de frustratie ervaren. 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.
De oplossing is beschamend simpel: een Markdown-bestand genaamd CLAUDE.md.
Wat het doet
Het CLAUDE.md bestand geeft Claude Code blijvend geheugen over je project. Je plaatst het in de root van je repository en Claude leest het automatisch aan het begin van elke sessie. Zie het als een onboarding-script voor je codebase.
Technisch gezien wordt de inhoud van CLAUDE.md aan je prompt toegevoegd. Claude "onthoudt" je project niet tussen sessies, maar het leest dit bestand voordat het iets anders doet, wat praktisch hetzelfde effect heeft.
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 codeer je je conventies. 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 geformateerd 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. Volgende sessie weet het het. 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 hooks 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. Meer is het niet.