CLAUDE.md

Technische definitie

CLAUDE.md is een Markdown-bestand dat automatisch in de systeemprompt van Claude Code wordt geladen. Het werkt op meerdere niveaus: een persoonlijk bestand in ~/.claude/CLAUDE.md (voor al je projecten), een projectbestand in ./CLAUDE.md (gedeeld via git), en lokale overrides in ./CLAUDE.local.md (persoonlijk, niet gecommit). Claude Code loopt bij het opstarten vanaf de werkdirectory omhoog naar de root en laadt elk CLAUDE.md-bestand dat het tegenkomt: ideaal voor monorepos. Daarnaast ondersteunt het @import-syntax en modulaire regels via .claude/rules/.

Hoe het werkt

Use cases

• Projectstandaarden afdwingen

  Een development team legt in CLAUDE.md vast: "Gebruik TypeScript strict mode, Tailwind voor styling, en schrijf tests met Vitest." Claude Code volgt deze afspraken automatisch bij elke code-wijziging: geen handmatige review nodig voor basisstandaarden.

• Buildcommando's centraliseren

  In CLAUDE.md staan de commando's voor development, testing en deployment. Claude Code weet dan precies hoe het de app moet draaien, testen en bouwen zonder dat je het elke keer vertelt.

• Architectuurbeslissingen documenteren

  Leg vast waarom bepaalde keuzes zijn gemaakt: "We gebruiken Server Components voor SEO, Client Components alleen voor interactiviteit." Claude Code respecteert deze architectuur bij het schrijven van nieuwe code.

• Team-breed AI-workflows standaardiseren

  Als iedereen in het team hetzelfde CLAUDE.md deelt via git, werkt Claude Code voor iedereen consistent. Geen individuele afspraken meer: één bron van waarheid. In AI als Teamsport leer je hoe je dit organiseert.

Voorbeelden

• Minimaal CLAUDE.md-bestand

  Een effectief CLAUDE.md hoeft niet lang te zijn. De kern: welke taal en frameworks je gebruikt, de belangrijkste commando's (npm run dev, npm run build, npm test), en een paar codestandaarden. Met die informatie presteert Claude Code al significant beter dan zonder.

• Monorepo met meerdere CLAUDE.md-bestanden

  In een monorepo met een frontend en backend map zet je een algemeen CLAUDE.md in de root ("TypeScript overal, ESLint configuratie") en specifieke bestanden per map ("frontend: React met Tailwind" en "backend: Node.js met Prisma"). Claude Code laadt automatisch beide niveaus.

• Persoonlijk vs. gedeeld

  In ~/.claude/CLAUDE.md zet je persoonlijke voorkeuren: "Schrijf commit messages in het Nederlands" of "Gebruik altijd bun in plaats van npm." In het project-CLAUDE.md staan teamafspraken. CLAUDE.local.md is voor jouw lokale overrides die niet in git komen.

Veelgemaakte fouten

• "Ik schrijf alles wat ik weet in CLAUDE.md"

  Hoe langer het bestand, hoe minder effectief. Claude moet alles verwerken binnen het context window. Houd het onder 200 regels per bestand (Anthropic's officiële richtlijn). Specificiteit is belangrijker dan volledigheid: schrijf alleen wat Claude daadwerkelijk nodig heeft.

• "Ik maak het bestand één keer en raak het niet meer aan"

  Je project verandert, en je CLAUDE.md moet meeveranderen. Gebruik /init om een startversie te genereren, maar review en update het regelmatig. Een verouderd CLAUDE.md levert verouderde code op.

• "Iedereen in het team heeft zijn eigen versie"

  Zonder gedeeld CLAUDE.md in git werkt Claude voor iedereen anders. Leg teamafspraken vast in ./CLAUDE.md (gedeeld). Persoonlijke voorkeuren gaan in ~/.claude/CLAUDE.md of .CLAUDE.local.md. Zo combineer je consistentie met flexibiliteit.

Veelgestelde vragen

• Wat is CLAUDE.md?

  CLAUDE.md is een Markdown-bestand in de root van je project dat Claude Code automatisch leest bij elke sessie. Het werkt als een vaste briefing: welke technologieën je gebruikt, hoe je codebase is gestructureerd en welke afspraken het team hanteert. Werk je met meerdere AI-tools naast Claude Code, gebruik dan AGENTS.md, de open standaard die ook door Cursor en Codex wordt gelezen.
• Hoe maak ik een CLAUDE.md voor mijn project?

  De snelste manier: open Claude Code in je project en typ /init. Claude analyseert je codebase en genereert een startversie. Pas het aan met je specifieke conventies en commando's. Je kunt het ook handmatig schrijven: begin met frameworks, buildcommando's en codestandaarden.
• Wordt CLAUDE.md gedeeld met mijn team?

  Ja, als je het commit naar git. ./CLAUDE.md is bedoeld om te delen. Voor persoonlijke voorkeuren gebruik je ~/.claude/CLAUDE.md (al je projecten) of ./CLAUDE.local.md (dit project, wordt automatisch ge-gitignored).
• Hoe lang moet een CLAUDE.md zijn?

  Zo kort mogelijk, maar zo specifiek als nodig. Anthropic's officiële richtlijn is minder dan 200 regels per bestand (code.claude.com/docs/en/memory): een langer bestand kost meer context en Claude volgt de instructies minder consistent. Schrijf geen algemene informatie die Claude al weet: focus op projectspecifieke afspraken, commando's en architectuurbeslissingen. Groeit het bestand toch groter, splits instructies dan met .claude/rules/.
• Kan ik meerdere CLAUDE.md-bestanden hebben?

  Ja. Claude Code loopt vanaf je werkdirectory omhoog en laadt elk CLAUDE.md-bestand dat het tegenkomt. In een monorepo kun je een algemeen bestand in de root hebben en specifieke bestanden per submap. Ze worden gecombineerd, met de meest specifieke als prioriteit.
• Wat is het verschil tussen CLAUDE.md en auto memory?

  CLAUDE.md schrijf jij zelf: vaste instructies en regels die bij elke sessie worden geladen. Auto memory schrijft Claude Code zelf, op basis van correcties en voorkeuren die je tijdens een sessie geeft, en wordt per repository gedeeld tussen worktrees (tot de eerste 200 regels of 25KB per sessie geladen). Gebruik CLAUDE.md voor codestandaarden en architectuur, en laat auto memory de terugkerende correcties opvangen die je anders elke sessie opnieuw zou moeten geven (Anthropic: How Claude remembers your project).

Gerelateerde termen

• Claude Code
• Prompt Engineering
• AI Agent
• Subagents
• Context Window
• LLM
• Claude
• AGENTS.md