CLAUDE.md is een eenvoudig markdown-bestand in de root van uw project. Claude leest het automatisch elke sessie. Projectniveau: ./CLAUDE.md. Globaal (alle projecten): ~/.claude/CLAUDE.md. Project overschrijft globaal: het globale bestand bevat uw standaardinstellingen, het projectbestand bevat de specifieke kenmerken van deze repo.
Zie het als het onboarding-document dat u geeft aan een zeer bekwame aannemer die niets van uw project weet. Zonder dit begint elke sessie met Claude die uw stack, uw naamgevingsconventies en uw eerdere beslissingen raadt. Gissingen worden code, code wordt bugs. CLAUDE.md kortsluit die keten. Een bestand verslaat een slimme prompt omdat het werkt, of u het nu onthoudt of niet.
Vijf secties die hun nut bewijzen. Drie tot zes opsommingstekens per sectie:
1. Stack: frameworks, DB, authenticatie, e-mail, met versies. "Next.js 16, Postgres op Neon, Resend voor e-mail, Stripe voor betalingen, Supabase voor authenticatie."
2. Routes: waar dingen zich bevinden. "App in /app, serveracties in /actions, API onder /app/api/v2, gedeelde componenten in /components/ui."
3. Conventies: regels die voor u duidelijk zijn, onzichtbaar voor Claude. "Geld in centen (int), datums UTC, bestandsnamen kebab-case, ID's als UUID v4."
4. Beveiligingsregels: dingen die nooit mogen gebeuren. "Log nooit API-sleutels. Parameteriseer alle SQL. Rate-limit alle openbare eindpunten."
5. Doe Dit Niet: valkuilen waar u al in bent getrapt. "Voeg geen afhankelijkheden toe zonder te vragen. Voer geen migraties uit van lokaal naar productie."
Een uitgewerkte sjabloon. Vervang door uw echte projectdetails:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth met Google OAuth
## Routes
- App in /app, actions in /actions, API onder /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)Let op de specificiteit. "10/min per IP" is uitvoerbaar. "Gebruik rate limiting" is dat niet.
De duurste fout: vage regels die specifiek klinken.
Zwak: "Ga voorzichtig om met geld." Claude zal met geld omgaan op de manier die het het beste acht, wat mogelijk niet overeenkomt met uw systeem.
Sterk: "Alle geldbedragen zijn gehele centen. Nooit floats. Geef nooit ruwe centen weer; deel door 100 en formatteer met een valutasymbool." Opslagtype, verwerkingsregel, weergave regel. Geen dubbelzinnigheid.
De tweede fout: aspiraties schrijven in plaats van beperkingen. "We hechten waarde aan schone, leesbare code" is een aspiratie. "Bestanden van meer dan 200 regels worden opgesplitst in modules" is een beperking. Aspiraties vereisen beoordelingsvermogen; beperkingen produceren consistent gedrag. Vul uw CLAUDE.md met beperkingen.
CLAUDE.md is een levend document. Drie signalen dat het moet worden bijgewerkt:
U plakt dezelfde context voor de tweede keer in een prompt. Als u het opnieuw zegt, hoort het in CLAUDE.md.
Claude maakt een fout die een regel zou hebben voorkomen. De fout is de regel. Schrijf het voor de volgende sessie.
U legt een conventie uit aan een collega. Als het de moeite waard was om hardop te zeggen, is het de moeite waard om automatisch te laden.
Lengtediscipline: drie tot zes opsommingstekens per sectie; na acht, splits de sectie. Een CLAUDE.md die te lang is om te scannen, werkt niet meer omdat de belangrijke regels begraven raken. Zes regels die de juiste zes zijn, verslaan zestig regels opvulling.
Schalen voorbij ongeveer 300 regels: splits in onderwerpsbestanden met @filename includes:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdElk onderwerpsbestand blijft gefocust; de root blijft kort.
Commit CLAUDE.md naar versiebeheer. Regels worden controleerbaar in PR's, en een nieuwe teamgenoot kloont de repo met Claude al geconfigureerd. Voeg elke 'Doe Dit Niet'-regel toe in dezelfde commit als de bugfix die het heeft geleerd. Eén waarschuwing: generaliseer machine-specifieke paden voordat u commit.
Wat hoort in CLAUDE.md versus een prompt? Blast radius. Als een regel een klasse van fouten voorkomt die een uur of meer kost om te repareren, dan hoort het in CLAUDE.md. Sessie-specifieke instructies blijven in prompts.
Maak uw eerste CLAUDE.md in tien minuten. Geef Claude deze prompt:
"Ik ben Claude Code aan het instellen voor een project met deze stack: [stack]. Belangrijke conventies die iemand nieuw niet zou weten: [conventions]. Beveiligingsregels die nooit mogen worden geschonden: [rules]. Dingen die eerder bugs veroorzaakten: [traps]. Stel een CLAUDE.md op met vijf secties: Stack, Routes, Conventions, Security Rules, Don't Do This."
De eerste versie geeft u 80 procent. Verfijn het met wat Claude miste; de resterende 20 procent is wat specifiek is voor uw werkelijke ervaring met het project.
CLAUDE.md in de projectroot laadt uw stack, routes, conventies, beveiligingsregels en valkuilen in elke sessie. Globaal bestand voor projectoverschrijdende standaardinstellingen, projectbestand voor overschrijvingen. Beperkingen, geen aspiraties. Zes juiste regels verslaan zestig. Werk het bij wanneer Claude een fout maakt die een geschreven regel zou hebben voorkomen.