Een goede CLAUDE.md schrijven voor Claude Code
In het kort
CLAUDE.md is een Markdown-bestand met vaste instructies dat Claude Code aan het begin van elke sessie leest. Zet het in de hoofdmap van je project, of in ~/.claude/CLAUDE.md voor al je projecten. Houd het onder de 200 regels, schrijf controleerbare regels zoals "Draai npm test voor elke commit" en zet stappenplannen in skills. Met /init maakt Claude Code een eerste versie voor je.
Wat doet CLAUDE.md?
Elke sessie van Claude Code begint met een leeg contextvenster. CLAUDE.md is de plek waar je opschrijft wat je anders steeds opnieuw uitlegt: hoe je project in elkaar zit, welke commando's je gebruikt en welke regels gelden. Claude Code leest het bestand aan het begin van elke sessie.
Claude behandelt CLAUDE.md als context. Het volgt de instructies zo goed mogelijk, maar het is geen harde blokkade. Moet iets altijd gebeuren of juist nooit, gebruik dan een hook.
Waar zet je het bestand?
| Bereik | Locatie | Voor wie |
|---|---|---|
| Project | ./CLAUDE.md of ./.claude/CLAUDE.md | Je team, gedeeld via git |
| Persoonlijk | ~/.claude/CLAUDE.md | Jij, in al je projecten |
| Lokaal | ./CLAUDE.local.md | Jij, alleen in dit project (zet het in .gitignore) |
| Organisatie | Beheerd door IT | Alle gebruikers op een machine |
Claude Code laadt de bestanden in je huidige map en in alle mappen erboven, en voegt ze samen. Ze overschrijven elkaar niet. Bestanden in submappen laden pas wanneer Claude Code daar bestanden leest.
Begin met /init
Typ /init in een sessie. Claude Code bekijkt je project en schrijft een eerste CLAUDE.md met build-commando's, testinstructies en conventies die het vindt. Bestaat het bestand al, dan stelt Claude Code verbeteringen voor. Vul daarna aan met wat Claude Code zelf niet kan ontdekken.
Wat hoort erin?
Voeg iets toe als:
- Claude Code dezelfde fout voor de tweede keer maakt.
- je dezelfde correctie typt als in de vorige sessie.
- een nieuwe collega dezelfde uitleg nodig zou hebben.
Houd het bij feiten die in elke sessie gelden: build-commando's, conventies, de opbouw van je project en vaste regels.
Schrijf regels die je kunt controleren
| Vaag | Controleerbaar |
|---|---|
| Formatteer de code netjes | Gebruik 2 spaties inspringing |
| Test je wijzigingen | Draai npm test voor elke commit |
| Houd bestanden georganiseerd | API-handlers staan in src/api/handlers/ |
Hoe lang mag het zijn?
Anthropic adviseert minder dan 200 regels per CLAUDE.md. Langere bestanden kosten meer context en worden minder goed gevolgd. Zet regels onder kopjes en haal tegenstrijdige instructies weg: bij twee tegenstrijdige regels kiest Claude er willekeurig één. Met /doctor prompt-audit laat je Claude Code zoeken naar verouderde of tegenstrijdige instructies.
Wanneer een skill of rule beter past
Is iets een stappenplan, of geldt het alleen voor een deel van je project? Zet het dan in een skill, of in een bestand in .claude/rules/ met een paths-veld. Die laden pas wanneer ze nodig zijn. Hoe je een skill maakt, lees je in Claude Code skills maken.
Andere bestanden importeren
Met @pad/naar/bestand importeer je een ander bestand, bijvoorbeeld @README of @docs/git-instructions.md. Dat helpt bij de structuur, maar bespaart geen context: geïmporteerde bestanden laden ook bij de start.
Controleren of het werkt
Met /context zie je welke CLAUDE.md-bestanden geladen zijn. Met /memory open en bewerk je ze.
Laat iemand meekijken
Een CLAUDE.md wordt beter naarmate je hem gebruikt. Wil je dat iemand met je meekijkt naar je CLAUDE.md en de rest van je setup, plan dan een 1-op-1 Claude Code-coachsessie met Tarik.
Veelgestelde vragen
Wat is het verschil tussen CLAUDE.md en auto memory?
CLAUDE.md schrijf je zelf, met instructies en regels. Auto memory zijn notities die Claude Code zelf bijhoudt op basis van je correcties. Beide worden aan het begin van elke sessie geladen.
Leest Claude Code ook AGENTS.md?
Ja, vanaf versie 2.1.277. Standaard leest het AGENTS.md alleen als er geen CLAUDE.md in je project of de mappen erboven staat.