Niveaus voor gebruiker, project en directory

Het bestand op projectniveau staat in de hoofdmap van de repository als ./CLAUDE.md (of .claude/CLAUDE.md). Omdat het in de repository staat, wordt het vastgelegd en gedeeld via versiebeheer.

Dat is precies wat je wilt voor regels waarop het hele team vertrouwt: de buildopdracht, het testframework, architectuurconventies, de mappenstructuur en alles wat een nieuwe bijdrager vanaf dag één nodig heeft.

Vuistregel: als een nieuwe kloon zonder dit bestand niet zou werken, hoort het in de CLAUDE.md op projectniveau — niet in je persoonlijke gebruikersbestand.

Een CLAUDE.md in een submap heeft een mappenbereik: het is alleen van toepassing wanneer Claude binnen die deelstructuur werkt. Zo blijven specifieke, lokale regels dicht bij de code waarop ze van toepassing zijn.

Voorbeeld: een frontend/CLAUDE.md kan conventies voor React/Tailwind bevatten die niet zinvol zijn voor de backend, terwijl services/payments/CLAUDE.md regels kan bevatten die alleen relevant zijn voor factureringscode.

Bestanden op mapniveau worden nog steeds vastgelegd (ze staan in de repository), dus ze worden gedeeld — maar hun bereik is de map, niet het hele project.

De niveaus leveren aanvullende context en sluiten elkaar niet uit. Wanneer je in een submap werkt, kan Claude het gebruikersbestand, het projectbestand en het mappenbestand samen gebruiken.

Zie het als concentrische bereiken:

• Gebruiker — grootste bereik (elk project), kleinste doelgroep (alleen jij).
• Project — de hele repository, het hele team.
• Map — één deelstructuur, het hele team.

De vraag is dus nooit alleen: "hoe specifiek is deze regel?" maar ook: "wie moet hem zien — ik of iedereen?" De doelgroep bepaalt gebruiker of project; het bereik bepaalt project of map.

Het meest voorkomende ant patroon: een regel waar iedereen van afhankelijk is in ~/.claude/CLAUDE.md zetten. Het werkt perfect voor jou — dus de leemte blijft onzichtbaar — maar omdat het gebruikersbestand nooit via VCS wordt gedeeld, missen nieuwe collega's het volledig.

Symptomen: Claude volgt de conventie op jouw machine en negeert haar op die van een collega, en niemand begrijpt waarom. De oplossing is altijd hetzelfde: verplaats gedeelde regels naar beneden, naar de CLAUDE.md op projectniveau (of mapniveau), zodat ze met de repository worden meegeleverd.

Een CLAUDE.md hoeft geen gigantisch bestand te zijn. Je kunt andere bestanden toevoegen met @path-imports, zodat elk bestand gericht en leesbaar blijft.

Een projectbestand kan bijvoorbeeld een gedeeld standaardenbestand importeren in plaats van honderden regels inline op te nemen. Zo blijft de hiërarchie eenvoudiger te onderhouden en kun je dezelfde standaarden in meerdere bestanden hergebruiken.

Een monolithische CLAUDE.md wordt bij elke taak in de context geladen — ook wanneer het grootste deel niet relevant is — en verspilt tokens. Een netter patroon voor specifieke regels bestaat uit bestanden in .claude/rules/ met YAML-frontmatter.

Elk regelbestand declareert een patroon in paths en wordt alleen geladen wanneer je overeenkomende bestanden bewerkt. Zo krijg je de precisie van regels op mapniveau en bespaar je context, omdat regels die niet overeenkomen met het huidige bestand nooit worden ingeladen.

Je hoeft deze bestanden niet handmatig in een externe editor te bewerken. In Claude Code opent en bewerkt de opdracht /memory het CLAUDE.md-geheugen, en wijzigingen blijven behouden tussen sessies.

Voor een gloednieuwe repository initialiseert /init een CLAUDE.md op projectniveau door de codebase te documenteren. Zo krijg je een zinvol startpunt dat je vervolgens kunt verfijnen.

De keuze voor welk bestand /memory schrijft, komt nog steeds neer op dezelfde beslissing: persoonlijk (gebruiker) of gedeeld (project of map).

Deze scheiding tussen gebruiker en project is niet uniek voor CLAUDE.md — het is een consistent patroon in Claude Code. Skills en opdrachten gebruiken precies dezelfde twee bereiken:

• Projectbereik — .claude/skills/ en .claude/commands/ in de repository worden gedeeld via VCS.
• Gebruikersbereik — ~/.claude/skills/ is persoonlijk.

Let op: .claude/commands/ is de oudere vorm en .claude/skills/ de huidige, maar de regel voor het bereik is identiek: repository = team, basismap = jij. Leer de scheiding één keer en je kunt haar overal toepassen.

Omdat bestanden op project- en mapniveau in versiebeheer worden vastgelegd, moet je ze behandelen als openbare code: zet er nooit geheimen in. Dezelfde discipline geldt voor een projectgebonden .mcp.json (gedeeld in VCS) tegenover het persoonlijke ~/.claude.json.

Verwijs voor tokens en sleutels naar omgevingsvariabelen — bijvoorbeeld ${GITHUB_TOKEN} — in plaats van de ruwe waarde te plakken. Het gedeelde bestand vermeldt welke variabele moet worden gebruikt; het echte geheim blijft in de omgeving, buiten de repository en buiten CLAUDE.md.

Kies het niveau door twee vragen te beantwoorden — wie en waar:

• Gebruiker (~/.claude/CLAUDE.md): persoonlijk, elk project, NIET gedeeld via VCS — nieuwe collega's missen het. Gebruik dit alleen voor persoonlijke voorkeuren.
• Project (./CLAUDE.md): gedeeld via VCS, het hele team, de hele repository. De plek voor buildopdrachten en conventies die iedereen nodig heeft.
• Map (submap CLAUDE.md): gedeeld via VCS, maar beperkt tot één deelstructuur.

Houd bestanden compact met @path-imports en laad specifieke regels indien nodig via .claude/rules/ met paths-frontmatter. Leg nooit geheimen vast — verwijs naar omgevingsvariabelen zoals ${GITHUB_TOKEN}. De grootste valkuil is teamregels in je persoonlijke gebruikersbestand zetten, waar alle anderen ze stilletjes nooit zullen zien.