CLAUDE.md

Wat is CLAUDE.md?

CLAUDE.md is het markdown-instructiebestand dat Claude Code, Anthropics coding-agent, automatisch leest bij het begin van elke sessie. Het draagt aanhoudende projectcontext: build- en testcommando's, codeconventies, architectuurnotities, en regels die de agent moet volgen, zodat dezelfde richtlijn op elke taak van toepassing is zonder herhaald te worden in prompts.

De belangrijkste punten

• Het is staand geheugen, automatisch geladen. Alles in CLAUDE.md vormt elke sessie in dat project, wat het het bestand met de hoogste hefboomwerking maakt in een Claude Code-workflow.
• Het is gelaagd. Claude Code voegt bestanden samen van het gebruikersniveau (~/.claude/CLAUDE.md), de projectroot, en submappen, waarbij specifiekere bestanden bredere aanvullen en verfijnen.
• Elke regel kost context. Het bestand wordt aan elke sessie vooraf toegevoegd, dus concurreert het met code en gesprek voor het contextvenster, en opgeblazen bestanden verslechteren resultaten.
• Het is Claude Codes tegenhanger van de leveranciersneutrale AGENTS.md-conventie, en teams die meerdere agents gebruiken, onderhouden vaak één bestand en verwijzen ernaar vanuit het andere.
• Instructies werken het best als korte, imperatieve, projectspecifieke regels. Generiek advies zoals "schrijf schone code" verspilt tokens; "draai make lint voordat je een taak afrondt" verandert gedrag.

Hoe het werkt

Wanneer Claude Code start in een map, verzamelt hij CLAUDE.md-bestanden van verschillende locaties: een globaal bestand in de home-directory van de gebruiker voor persoonlijke voorkeuren die overal gelden, het projectrootbestand dat meestal is ingecheckt in git en gedeeld door het team, en optionele bestanden in submappen die regels toevoegen voor hun deel van de boom. De gecombineerde inhoud landt bovenaan de context van de agent voor het eerste gebruikersbericht, functionerend als projectniveau-systeemrichtlijn. Een verwante conventie, CLAUDE.local.md of een niet-getrackt persoonlijk bestand, houdt individuele overrides die buiten versiebeheer blijven.

Teams laten het bestand op twee manieren groeien. De doelbewuste manier is het schrijven zoals een onboardingdocument voor een zeer letterlijke bijdrager: exacte commando's, naamgevingsconventies, mapgrenzen, links naar diepere documentatie. De incrementele manier is correcties vastleggen terwijl ze gebeuren; Claude Code ondersteunt snel een instructie toevoegen aan geheugen midden in een sessie, dus wordt "we gebruiken hier pnpm, geen npm" een permanente regel op het moment dat het voor het eerst wordt gezegd. Volwassen opzetten gebruiken ook imports, waarbij CLAUDE.md naar andere bestanden verwijst om gedeelde standaarden binnen te halen zonder ze te dupliceren. Wat in deze bestanden terechtkomt is redelijk voorspelbaar: een empirische studie uit 2025 van 253 CLAUDE.md-bestanden uit 242 repositories vond dat ze doorgaans ondiepe hiërarchieën volgen gedomineerd door operationele commando's, technische implementatienotities, en high-level architectuur [1].

Wat het bestand krachtig maakt is het opstapelende effect. Een correctie één keer gemaakt in chat helpt één keer. Dezelfde correctie in CLAUDE.md helpt elke sessie, voor elke engineer in het team, onbeperkt. Daarom reviewen ervaren teams het bestand in pull requests zoals elk ander stuk infrastructuur, en daarom behandelen context engineering-discussies het als de eerste hendel om aan te trekken voor uitgebreidere machinerie. Praktijkgebruik onderbouwt dit: een studie van 2.303 agent-contextbestanden over 1.925 repositories vond dat ze evolueren zoals configuratiecode, via frequente, kleine toevoegingen [2].

Voorbeeld

De monorepo van een startup heeft een regel die elke nieuwe engineer en elke agent laat struikelen: het API-package genereert zijn TypeScript-client, en de gegenereerde code met de hand bewerken breekt stilletjes de volgende build. Nadat de agent precies dat twee keer doet, voegt het team een root-CLAUDE.md toe: bewerk nooit packages/api-client/src/generated/, regenereer met pnpm codegen na schemawijzigingen, draai pnpm turbo test --filter=...[HEAD] voordat je een taak klaar verklaart, en gebruik conventional-commit-berichten. Ze voegen ook een packages/infra/CLAUDE.md toe die waarschuwt dat Terraform-bestanden door CI worden toegepast en nooit lokaal mogen worden toegepast. Agentsessies stoppen die dag met de twee duurste fouten in de repo maken.

Veelvoorkomende misvattingen

De klassieke fout is CLAUDE.md behandelen als stortplaats en het laten uitdijen tot duizenden woorden stijlfilosofie, verouderde commando's, en geplakte documentatie. Omdat het bestand in elke sessie geladen wordt, belast opblazen elke taak, en modellen volgen lange instructielijsten minder betrouwbaar dan korte. De discipline die werkt is dezelfde als voor code: houd het minimaal, houd het actueel, verwijder regels die hun tokens niet meer verdienen, en verplaats referentiemateriaal naar gelinkte documentatie die de agent op aanvraag kan lezen. Het is ook de moeite waard om verwachtingen eerlijk te houden over wat het bestand kan doen. Een ablatiestudie uit 2026 van 288 geëvalueerde runs over 17 echte repositorytaken vond dat contextbestanden zoals CLAUDE.md correctheid niet meetbaar beïnvloedden op zowel Claude Code als Codex [3]. De waarde van het bestand zit in conventies, commando's, en grenzen sturen, niet in het model moeilijkere problemen laten oplossen.

FAQ

Wat is het verschil tussen CLAUDE.md en AGENTS.md? Bereik van publiek. AGENTS.md is een cross-vendor-conventie gelezen door veel coding-agents; CLAUDE.md is Claude Codes native bestand, met extra gedrag zoals hiërarchisch samenvoegen, imports, en in-sessie-geheugenupdates. Teams die meerdere agents draaien, houden meestal één canoniek instructiebestand aan en laten het andere ernaar verwijzen.

Moet CLAUDE.md gecommit worden naar versiebeheer? Het projectniveau-bestand, ja. Het codeert teamkennis en zou moeten evolueren via review zoals elke gedeelde config. Persoonlijke voorkeuren horen thuis in het home-directory-bestand of een lokale variant die niet-getrackt blijft.

Hoe lang moet een CLAUDE.md zijn? Zo kort als mogelijk terwijl het de commando's en regels dekt die de agent daadwerkelijk nodig heeft. Veel effectieve bestanden zijn onder de honderd regels. Als het jouwe leest als documentatie in plaats van instructies, verplaats de documentatie elders en link ernaar.

Bronnen

1. arXiv. "On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code, analyse van 253 CLAUDE.md-bestanden uit 242 repositories." https://arxiv.org/abs/2509.14744. Geraadpleegd augustus 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, evolutiepatronen over 2.303 contextbestanden." https://arxiv.org/abs/2511.12884. Geraadpleegd augustus 2026.
3. arXiv. "Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories, 288 geëvalueerde runs over 17 taken." https://arxiv.org/abs/2607.27250. Geraadpleegd augustus 2026.