Iedereen die voor het eerst Claude Code installeert, krijgt binnen een week dezelfde frustratie. De AI is enorm capabel, maar hij snapt jouw project niet. Hij kiest de verkeerde framework-conventies. Hij gebruikt patronen uit een andere taal. Hij verzint variabelnamen die je nooit zou gebruiken.
De oplossing is één bestand: CLAUDE.md. Het is geen magie. Het is gewoon de plek waar je Claude Code letterlijk vertelt hoe jouw project werkt, welke conventies je gebruikt, en wat je verwacht.
Deze gids is voor wie net begonnen is. Geen architectenpraat, geen advanced patterns. Wel: wat zet je erin, wat laat je weg, en de drie fouten die ik bij iedere beginner zie.
Wat is CLAUDE.md eigenlijk?
CLAUDE.md is een markdown-bestand in de root van je project. Claude Code leest dat bestand automatisch bij iedere sessie en injecteert de inhoud als context. Alles wat erin staat, weet de AI, zonder dat je het opnieuw moet uitleggen.
Vergelijk het met een onboarding-document voor een nieuwe collega. Een goede onboarding zorgt dat iemand binnen een dag productief is. Een slechte zorgt dat dezelfde vragen elke week terugkomen.
Hetzelfde geldt voor Claude. Met een goede CLAUDE.md voert hij in één keer de juiste actie uit. Zonder krijg je iedere sessie een andere interpretatie van wat jij eigenlijk wilde.
Waar zet je het bestand?
Drie locaties, in volgorde van scope:
1. Project-niveau, CLAUDE.md in de root van je project. Geldt alleen voor dat project. Gaat mee in git, dus je hele team profiteert.
2. Persoonlijk per project, .claude/CLAUDE.md in dezelfde root. Geldt alleen voor jou (gitignore'd). Voor persoonlijke voorkeuren die niet voor het hele team gelden.
3. Globaal, ~/.claude/CLAUDE.md in je home-directory. Geldt voor alle projecten op jouw machine. Voor jouw persoonlijke werkstijl.
Voor de meeste beginners is project-niveau het enige wat je nodig hebt. Begin daar.
Wat moet er minimaal in?
Niet te veel. Een goede CLAUDE.md is kort en specifiek, geen tutorial-boek. Vier secties die altijd nuttig zijn:
1. Wat is dit project?
Twee zinnen. Wat doet het, voor wie, en in welke taal/framework.
# Project Context
Dit is een Next.js 14 e-commerce site voor lokale wijnhandel. Backend: Supabase (PostgreSQL).
Frontend: Tailwind CSS + shadcn/ui components. Nederlands als hoofdtaal.2. Mapstructuur
Welke map doet wat. Claude leest de structuur zelf, maar weet niet wat de bedoeling is.
## Mapstructuur
- `app/`, Next.js routes (App Router)
- `components/`, herbruikbare UI components (gebruik shadcn/ui patronen)
- `lib/`, utilities, Supabase client, types
- `tests/`, Vitest unit tests (NOOIT inline naast source)3. Conventies die je echt belangrijk vindt
Niet alle conventies. De drie tot vijf die je vaak moet corrigeren.
## Conventies
- Gebruik `async/await`, NOOIT `.then()` chains
- Server components by default, alleen `"use client"` als state of events nodig zijn
- Errors loggen via `lib/logger.ts`, NOOIT `console.error` in productie
- Database queries via Supabase client in `lib/db/`, niet in components direct4. Wat NIET te doen
Soms duidelijker dan wat wel te doen. Verboden patronen.
## Verboden
- Geen `_v2` of `_new` filenames bij refactors, edit het origineel
- Geen TODO comments achterlaten, implementatie compleet of niet
- Geen mock data in productie code, alleen in `tests/fixtures/`
- Geen nieuwe dependencies zonder overlegDat is genoeg om te beginnen. Je breidt later uit als je merkt dat je dezelfde correctie elke week geeft.
De drie fouten die ik bij beginners zie
Fout 1: Te veel tegelijk willen vertellen
De eerste CLAUDE.md van veel beginners wordt 800 regels lang. Architectuur-uitleg, complete framework-handleidingen, persoonlijke filosofie over clean code.
Dat werkt niet. Claude moet die 800 regels iedere sessie verwerken, dat kost tokens en context-ruimte. Bovendien: hoe meer je vertelt, hoe minder Claude weegt wat echt belangrijk is.
Regel: als je CLAUDE.md langer is dan 200 regels, snijd. Veel meer dan dat is bijna altijd duplicatie van wat al in de code zelf zichtbaar is.
Fout 2: Vertellen wat al duidelijk is uit de code
# Slecht
- Dit project gebruikt React
- We hebben Tailwind CSS geïnstalleerd
- De source code staat in src/Claude leest package.json. Hij ziet tailwind.config.js. Hij ziet de mapstructuur. Dat hoef je niet te vertellen.
Regel: schrijf alleen op wat je niet uit de code kunt afleiden. Conventies, beslissingen, en context.
Fout 3: Vergeten te updaten
CLAUDE.md schrijven is geen eenmalige actie. Iedere keer dat je een correctie geeft die voor iedere toekomstige sessie zou moeten gelden, leg die vast.
Een goede workflow is: één keer per week kijk je naar je sessies. Welke correcties heb je vaak gegeven? Die gaan in CLAUDE.md.
Als je dat niet doet, blijft Claude dezelfde fouten maken, niet omdat hij dom is, maar omdat jij hem niet hebt geüpdatet.
Voorbeeld: een complete (kleine) CLAUDE.md
Hier is een werkbaar voorbeeld voor een fictief Next.js project. ~50 regels. Dat is genoeg.
# Wijnhandel Online, Project Context
Next.js 14 (App Router) e-commerce voor lokale wijnhandel. Supabase backend. Tailwind + shadcn/ui.
Nederlandse hoofdtaal. Gericht op MKB-niveau, niet enterprise.
## Mapstructuur
- `app/`, Next.js routes
- `components/`, UI components, shadcn/ui patroon
- `lib/db/`, Supabase queries
- `lib/utils/`, pure utilities
- `tests/`, Vitest tests, NOOIT naast source
## Conventies
- `async/await`, geen `.then()` chains
- Server components default, `"use client"` alleen waar nodig
- Errors via `lib/logger.ts`, geen `console.error`
- Database access via `lib/db/`, nooit direct in components
- Component naming: PascalCase voor React components, kebab-case voor file names
## Stijl
- Nederlandstalige variabelnamen waar het de leesbaarheid helpt
(bijv. `wijn` ipv `wine` in domain code, maar `userId` in technische context)
- Korte functies (< 30 regels) of opsplitsen
- Geen abbreviations in publieke API ("getCustomer", niet "getCust")
## Verboden
- Geen `_v2` filenames, edit origineel
- Geen TODO comments, implementeer of laat weg
- Geen mock data buiten `tests/fixtures/`
- Geen nieuwe dependencies zonder overlegDat is het. Geen 800 regels. Geen architectuurdiagram. Wel: precies de informatie die Claude nodig heeft om in jouw project nuttig te zijn.
Voor power-users: split je CLAUDE.md via @import
Zodra je CLAUDE.md over de 100 regels gaat, wordt hij onhandig. Je kunt 'm in dat geval opsplitsen door er andere bestanden in te laten linken via de @import syntax. Mijn globale ~/.claude/CLAUDE.md is bijvoorbeeld maar ~10 regels:
@~/.claude/profile.md
## Implementation Standards
- No TODO comments, complete all implementations
- No mock objects or stub implementations
- Reports in claudedocs/, tests in tests/, scripts in scripts/De @import-regel laadt automatisch profile.md met mijn identiteit, portfolio, en cross-project voorkeuren. Dat zorgt dat Claude in elk project weet wie ik ben, zonder dat ik het hoef te herhalen.
De volledige walkthrough van die gelaagde architectuur, met globale identiteit plus project-context plus per-project memory, staat in mijn complete-setup blog van 30 mei. Voor nu: focus op je project-niveau CLAUDE.md. De gelaagde aanpak is nuttig pas wanneer je meerdere projecten parallel hebt lopen.
Wat doe je hierna?
Drie dingen, op volgorde:
- Maak je
CLAUDE.md, nu, in je actieve project. Begin met het voorbeeld hierboven, pas het aan. 30 minuten werk. - Test het. Vraag Claude in een nieuwe sessie iets te doen wat eerder fout ging. Als het nu klopt: het werkt. Als niet: scherp
CLAUDE.mdaan. - Lees de vervolgblog over rules.md, de stap waarbij je je codeerstandaarden afdwingt op een dieper niveau dan
CLAUDE.mdaankan.
Volgende week ga ik dieper op rules.md, daarna hooks, state management, en context engineering. Allemaal voor AI peers en hobbyisten, niet voor enterprise architects.
Veelgestelde vragen
Samenvatting
CLAUDE.md is geen magisch bestand, het is gewoon de plek waar je een AI-assistent vertelt hoe jouw project werkt. Houd het kort, specifiek, en update het wekelijks. Vermijd het verleiden om alles op te schrijven; de meeste informatie staat al in de code.
Doe het deze week. Het is letterlijk 30 minuten werk en bespaart je over een maand uren aan repetitieve correcties.
Lees ook: De 10 Claude Code features die elke developer in 2026 zou moeten gebruiken, de complete roadmap voor wie net begint.
Voor teams die hun complete Claude Code setup willen professionaliseren: ik help er bij op AI-architectuur.
Vragen over Claude Code, AI-projecten, of wil je je eigen setup bespreken? Volg me op LinkedIn, daar deel ik wekelijks build-in-public updates over hoe ik mijn eigen AI-systeem inricht.
Bronnen
- Claude Code Documentation, CLAUDE.md
- Claude Code Configuratie: CLAUDE.md, rules en skills
- Claude Code rules en memory setup