Ik gebruik Claude Code dagelijks sinds begin 2025, en ik kan je vertellen dat de grootste factor voor nuttige output niet prompt engineering of slimme trucjes is. Het is context. Specifiek: een goed geschreven CLAUDE.md-bestand in de root van je project. Dit ene bestand is het verschil tussen een AI-assistent die tegen je codebase vecht en één die voelt als een senior developer die al maanden in je team zit.

Als je prompts naar Claude Code gooit en generieke, verkeerde of frustrerende resultaten terugkrijgt, is deze gids voor jou. Ik leid je stap voor stap door hoe je je CLAUDE.md moet structureren, wat je erin moet zetten, wat je moet weglaten, en deel echte voorbeelden van productieprojecten die we bij Social Animal hebben opgeleverd.

Inhoudsopgave

Wat is CLAUDE.md en waarom is het belangrijk

CLAUDE.md is een markdown-bestand dat je in de root van je repository plaatst en dat Claude Code automatisch leest bij het begin van elke sessie. Beschouw het als onboardingdocumentatie voor je AI pair programmer. Wanneer een nieuwe developer je team aansluit, geef je hem niet zomaar een laptop en zeg je "verzin het zelf." Je loopt hem door de architectuur, legt de rare bits uit, wijst op de landmijnen. CLAUDE.md doet hetzelfde voor Claude.

Zonder het moet Claude Code alles afleiden uit je bestandsstructuur, package.json en welke bestanden het toevallig leest. Dat is als of je een nieuwe medewerker vraagt je hele systeem te begrijpen door willekeurige bronbestanden te lezen. Ze krijgen sommige dingen goed, maar trekken ook conclusies die iedereen tijd kosten.

Met een solide CLAUDE.md heb ik gezien dat de nauwkeurigheid van taakafhandeling sprong van ongeveer 60% naar meer dan 90% bij eerste pogingen. Dat is geen klein verbetering — het is het verschil tussen AI-ondersteunde ontwikkeling als een productiviteitsvermenigvuldiger en als frustrerende tijdsverspilling.

Hoe Claude Code je projectcontext leest

Claude Code heeft een specifieke hiërarchie voor het laden van context. Dit begrijpen is belangrijk omdat het invloed heeft op hoe je je projectgeheugen organiseert.

De context-laadvolgorde

  1. ~/.claude/CLAUDE.md — Je globale voorkeuren (toegepast op elk project)
  2. ./CLAUDE.md — Het projectniveaubestand in je repo root
  3. ./subdirectory/CLAUDE.md — Directory-specifieke overschrijvingen
  4. .claude/settings.json — Projectspecifieke tool-rechten en instellingen
  5. Session context — Wat je Claude in het huidige gesprek vertelt

Het CLAUDE.md-bestand op projectniveau is waar je het meeste tijd aan besteedt. Het globale bestand is handig voor persoonlijke voorkeuren ("Ik geef de voorkeur aan functionele componenten" of "altijd TypeScript strict mode"), maar de echte waarde zit in per-project-context.

Dit is cruciaal: Claude Code leest het CLAUDE.md bij het begin van elke sessie, maar het heeft ook beperkte contextvensterruimte. Als je CLAUDE.md 5.000 woorden brabbeldocumentatie is, verbrand je tokens die voor daadwerkelijke code-redenering zouden kunnen worden gebruikt. Wees beknopt. Wees specifiek. Elke regel moet zijn plaats verdienen.

De anatomie van een goed CLAUDE.md-bestand

Na het schrijven en verfijnen van CLAUDE.md-bestanden in tientallen projecten — Next.js-apps, Astro-sites, headless CMS-integraties, API-services — ben ik op een consistente structuur gekomen die werkt.

De ideale structuur

# Projectnaam

## Overzicht
Één paragraaf waarin je uitlegt wat dit project doet en voor wie het is.

## Tech Stack
Exacte versies en frameworks.

## Architectuur
Hoe de stukken passen.

## Belangrijkste conventies
Codeerstandaarden, naampatronen, bestandsorganisatieregels.

## Veelgebruikte commando's
Build, test, deploy en dev-commando's.

## Belangrijke context
Spullen die niet duidelijk uit de code komen.

## Bekende problemen / valkuilen
Landmijnen om te vermijden.

## Doe NIET
Expliciete dingen die de AI nooit mag doen.

Laten we elk onderdeel uitwerken.

Sectie voor sectie uitgelegd

Overzicht

Hou dit tot maximaal 2-3 zinnen. Claude heeft je productieroutekaart niet nodig — het moet het domein begrijpen zodat het contextafhankelijk passende beslissingen kan nemen.

## Overzicht
Dit is de marketingsite van Acme Corp, een B2B SaaS-platform voor supply chain management. De site wordt statisch gegenereerd met dynamische API-routes voor formulierverwerking en lead capture. Inhoud wordt via Sanity CMS door het marketingteam beheerd.

Tech Stack

Wees exact. Zeg niet zomaar "React" — geef de versie, het framework, de renderstrategie op. Dit voorkomt dat Claude patronen voorstelt die in React 18 werken maar in React 19 breken, of Pages Router aanbeveelt terwijl je op App Router bent.

## Tech Stack
- **Framework**: Next.js 15.1 (App Router, RSC standaard)
- **Taal**: TypeScript 5.7 (strict mode)
- **Styling**: Tailwind CSS v4 met CSS-first configuratie
- **CMS**: Sanity v3 met live preview
- **Deployment**: Vercel (Productie + Preview-omgevingen)
- **Package Manager**: pnpm 9.x
- **Node**: v22 LTS
- **Testing**: Vitest + Playwright
- **State Management**: Zustand (minimaal, alleen voor client-side UI-state)

Architectuur

Dit is waar de meeste mensen te weinig of veel te veel schrijven. Je schrijft geen system design doc. Je geeft Claude een mentaal model.

## Architectuur
- `app/` — Next.js App Router pagina's en layouts
- `app/api/` — API-routes (formulierinzendingen, webhooks)
- `components/` — Gedeelde UI-componenten (atomic design: atoms/, molecules/, organisms/)
- `lib/` — Utiliteitsfuncties, API-clients, typedefinities
- `lib/sanity/` — Sanity-client, queries (GROQ), en type generatie
- `content/` — MDX-bestanden voor blogposts (samen met frontmatter)
- `public/` — Statische assets (gebruik next/image voor alle afbeeldingen)

Gegevensstroom: Sanity CMS → GROQ-queries in lib/sanity/queries.ts → Server Components → Client Components (alleen wanneer interactiviteit nodig is)

Alle pagina's worden statisch gegenereerd bij build, behalve /blog/[slug]/preview die draft mode gebruikt.

Belangrijkste conventies

Dit onderdeel bespaart de meeste tijd. Zonder het volgt Claude algemene best practices die misschien conflicteren met de keuzes van je team.

## Belangrijkste conventies
- Componenten heten PascalCase, één component per bestand
- Gebruik named exports, nooit default exports (behalve pages/layouts)
- Alle data fetching gebeurt in Server Components — nooit useEffect voor data fetching
- API-responstypes leven in lib/types/ en worden auto-gegenereerd uit Sanity schema
- Gebruik `cn()` utility (lib/utils.ts) voor voorwaardelijke class merging, niet template literals
- Error boundaries verpakken elke grote paginasectie, niet de hele pagina
- Alle formulierverwerking gebruikt react-hook-form + zod validatieschema's
- Commit-berichten volgen Conventional Commits (feat:, fix:, chore:)

Veelgebruikte commando's

Dit lijkt basaal, maar Claude Code voert deze commando's daadwerkelijk uit. Als het de juiste niet kent, gist het, en het raadt vaak fout.

## Veelgebruikte commando's
- `pnpm dev` — Start development server (poort 3000)
- `pnpm build` — Productie build
- `pnpm lint` — ESLint + Prettier controle
- `pnpm test` — Voer Vitest unit tests uit
- `pnpm test:e2e` — Voer Playwright E2E-tests uit
- `pnpm sanity:typegen` — Regenereer Sanity-types na schema-wijzigingen
- `pnpm db:migrate` — Voer Drizzle ORM-migraties uit

Belangrijke context

Dit is voor spullen die Claude niet kan achterhalen door je code te lezen. Bedrijfslogica, externe beperkingen, dingen die een menselijke reviewer 30 minuten nodig heeft om uit te leggen.

## Belangrijke context
- We gebruiken ISR (revalidate: 3600) voor alle CMS-pagina's. Gebruik nooit `force-dynamic` tenzij absoluut noodzakelijk.
- De Sanity webhook op /api/revalidate handelt on-demand revalidering af — voeg geen handmatige revalidatielogica toe.
- Afbeeldingsoptimalisatie gaat via Sanity's CDN (cdn.sanity.io), niet next/image voor CMS-inhoud.
- Auth wordt afgehandeld door Clerk — bouw nooit aangepaste auth-flows.
- Het /api/leads endpoint heeft rate limiting via Upstash Redis. Verwijder de rate limit middleware niet.

Bekende valkuilen

Elk project heeft raar spul. Zet het hier zodat Claude er niet over struikelt.

## Bekende valkuilen
- Sanity's portable text renderer heeft een bug met geneste lijsten in v3.2. We gebruiken een aangepaste serializer in components/portable-text/list-fix.tsx
- Tailwind v4 ondersteunt de `@apply`-directief niet in module CSS-bestanden — gebruik in plaats daarvan inline classes
- De vercel.json rewrites voor /docs/* proxyen naar onze Mintlify docs site. Wijzig deze niet zonder het team in te lichten.
- Omgevingsvariabelen voorafgegaan door NEXT_PUBLIC_ zijn de enigen die client-side beschikbaar zijn. Geef API-geheimen nooit op deze manier bloot.

De sectie "Doe NIET"

Dit is qua stelling het meest belangrijke onderdeel. Negatieve instructies zijn ongelooflijk effectief bij AI-modellen.

## Doe NIET
- Installeer geen nieuwe dependencies zonder te vragen
- Gebruik geen `any` type — vind of maak juiste types
- Maak geen nieuwe API-routes voor dingen die in Server Components kunnen
- Wijzig niet de Sanity schema-bestanden zonder het migratieplan te bevestigen
- Gebruik geen `"use client"` tenzij de component echt browser-API's of event handlers nodig heeft
- Schrijf geen CSS-bestanden — alles is Tailwind utility classes
- Hardcode geen strings die uit het CMS moeten komen

Echte CLAUDE.md-voorbeelden

Voorbeeld: Next.js Marketing Site

Dit is een vereenvoudigde versie van een CLAUDE.md die we gebruiken op klantprojecten, vooral bij het bouwen van Next.js sites met headless CMS backends.

# Acme Marketing Site

## Overzicht
Marketingwebsite voor Acme (acme.com). Gebouwd met Next.js 15, opgemaakt met Tailwind v4, inhoud van Sanity CMS. Doel: sub-2s LCP op alle pagina's.

## Tech Stack
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## Architectuur
App Router met RSC. Alle data fetching in server components via GROQ-queries in lib/sanity/queries.ts. Client components alleen voor interactieve elementen (modals, formulieren, carousels).

Pagina's: / (home), /about, /pricing, /blog, /blog/[slug], /contact

## Conventies
- Alleen named exports (behalve page.tsx/layout.tsx)
- Componenten: PascalCase, één per bestand
- cn() voor class merging
- Zod schemas voor alle formuliervalidatie
- Geen useEffect voor data fetching. Ooit.

## Commando's
pnpm dev | pnpm build | pnpm lint | pnpm test

## Doe NIET
- Voeg "use client" toe zonder rechtvaardiging
- Installeer packages zonder te vragen
- Gebruik default exports voor componenten
- Wijzig sanity/schema/ bestanden zonder migratie te bevestigen
- Gebruik any type

Voorbeeld: Astro Content Site

Voor Astro-projecten ziet het CLAUDE.md er iets anders uit omdat het architectuurparadigma anders is.

# Tech Blog — Astro

## Overzicht
Developer blog met 500+ artikelen. Static-first, nul JS standaard. MDX voor inhoud met aangepaste componenten.

## Tech Stack
Astro 5.x | MDX | Tailwind v4 | Deployment naar Cloudflare Pages | Content Collections v2

## Architectuur
src/content/ — MDX-artikelen met Zod-gevalideerde frontmatter
src/components/ — Astro componenten (nul JS) en React islands (interactief)
src/layouts/ — Base layouts
src/pages/ — File-based routing

## Belangrijkste regels
- Geef voorkeur aan Astro-componenten (.astro). Gebruik React alleen voor islands die interactiviteit nodig hebben.
- client:visible voor under-fold interactieve componenten
- client:idle voor niet-kritieke interactieve componenten
- Gebruik nooit client:load tenzij absoluut noodzakelijk
- Alle afbeeldingen gebruiken Astro's Image-component met juiste width/height
- RSS feed wordt auto-gegenereerd van content collection — bouw geen handmatige feed-logica

## Doe NIET
- Voeg React componenten toe wanneer een Astro-component zou werken
- Gebruik client:load directief
- Sla afbeeldingsdimensies over (veroorzaakt CLS)
- Wijzig het content collection schema zonder bestaande frontmatter bij te werken

Veelvoorkomende fouten die je AI-context verpesten

Ik heb veel CLAUDE.md-bestanden onder ogen gehad op dit moment. Hier zijn de patronen die consistent tot slechte resultaten leiden.

Fout Waarom het schadelijk is Oplossing
Te lang (2000+ woorden) Verbrand context window tokens, belangrijke info gaat verloren Hou het onder de 800 woorden. Link naar externe docs voor diepe duiken.
Te vaag ("we gebruiken React") Claude vult gaten met aannames Wees specifiek: versies, patronen, exacte tools
Geen negatieve instructies Claude doet "redelijke" dingen die je conventies breken Voeg altijd een "Doe NIET" sectie toe
Copy-paste README.md READMEs zijn voor mensen, niet AI-context Schrijf CLAUDE.md helemaal opnieuw met AI-specifieke framing
Gevoelige gegevens erin API-sleutels, geheimen in contextbestanden Zet nooit geheimen in CLAUDE.md. Verwijs naar .env.example
Nooit bijwerken Project evolueert, contextbestand niet Beoordeel CLAUDE.md elke sprint of grote refactor
Tegenstrijdige instructies "Gebruik server components" + voorbeelden met useEffect fetching Laat één persoon eigenaar zijn van het bestand, controleer op consistentie

CLAUDE.md versus andere AI-contextbestanden

Claude Code is niet het enige AI-hulpmiddel dat projectcontextbestanden leest. Dit is hoe het landschap er in 2025 uitziet:

Bestand Hulpmiddel Auto-lezen Bereik
CLAUDE.md Claude Code Ja, bij sessiestart Projectbreed
.cursorrules Cursor Ja, bij bestandsopening Projectbreed
.github/copilot-instructions.md GitHub Copilot Ja, in Copilot Chat Repo-breed
.windsurfrules Windsurf (Codeium) Ja Projectbreed
AGENTS.md OpenAI Codex CLI Ja Projectbreed
.ai/context.md Aangepaste conventie Nee (handmatige referentie) Varieert

Het goede nieuws: de meeste inhoud is overdraagbaar. Als je een solide CLAUDE.md schrijft, duurt het omzetten naar .cursorrules of copilot-instructions.md ongeveer 5 minuten. De structuur en informatie zijn hetzelfde — alleen de bestandsnaam en kleine opmaakdifferentties.

Als je team meerdere AI-hulpmiddelen gebruikt (en veel doen dat in 2025), overweeg dan om één enkel bron van waarheid te onderhouden en de toolspecifieke bestanden ervan te genereren. Een eenvoudig build-script kan je master contextbestand naar alle juiste locaties kopiëren.

Geavanceerde patronen voor grote projecten

Geneste CLAUDE.md-bestanden

Voor monorepo's of grote codebases kun je CLAUDE.md-bestanden in subdirectories plaatsen. Claude Code leest de meest specifieke voor de directory waarin je werkt.

project/
├── CLAUDE.md              # Globale projectcontext
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web app specifieke context
│   └── api/
│       └── CLAUDE.md      # API specifieke context
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Design system context

Het root CLAUDE.md dekt gedeelde architectuur en conventies. Elk genest bestand voegt specifieke details toe voor dat package.

Dynamische context met /compact

Het /compact commando van Claude Code vat het huidige gesprek samen en geeft contextruimte vrij. Voor lange sessies heb ik een patroon gevonden dat goed werkt:

  1. Start met CLAUDE.md automatisch geladen
  2. Werk aan een feature
  3. Voer /compact uit wanneer context zwaar wordt
  4. Ga door — Claude behoudt de CLAUDE.md-context plus een gecomprimeerde samenvatting

Team-gedeeld versus persoonlijke context

We houden CLAUDE.md in versiebeheer (het hoort ge-commit te worden). Maar individuele developers gebruiken ook ~/.claude/CLAUDE.md voor persoonlijke voorkeuren:

# Persoonlijke voorkeuren
- Ik geef voorkeur aan uitgebreide variabelennamen boven afkortingen
- Laat me de redenering zien voordat je code schrijft
- Toon me bij het suggereren van wijzigingen de volledige bestandsdiff
- Ik gebruik VS Code met Vim-toetsbindingen (stel geen IDE-specifieke snelkoppelingen voor)

Deze scheiding houdt het teambestand schoon en gericht op projectfeiten, terwijl individuen hun ervaring kunnen aanpassen.

De impact meten

Hoe weet je dat je CLAUDE.md werkt? Dit zijn metriek die we intern bijhouden:

  • Nauwkeurigheid bij eerste poging: Hoe vaak heeft Claude's eerste response nul correcties nodig? Een goed CLAUDE.md haalt dit boven de 80%.
  • Conventie-overtredingen: Tel hoe vaak Claude je codeerstandaarden schendt. Dit zou naar nul moeten gaan.
  • Context vragen: Als Claude steeds "welk framework is dit?" of "moet ik de App Router gebruiken?" vraagt, mist je CLAUDE.md informatie.
  • Undo frequentie: Hoe vaak moet je Claude's wijzigingen afwijzen of terugdraaien. Lager is beter.

Eén team bij een mid-size startup rapporteerde hun gemiddelde AI-ondersteunde taakverwerkingstijd te reduceren van 12 minuten naar 4 minuten na een uur in hun CLAUDE.md te investeren. Dat is een 3x verbetering van één bestand.

Als je een project met ons bouwt, includeren we een aangepast CLAUDE.md als onderdeel van elke projectoverdracht. Het is zo belangrijk voor voortdurende ontwikkelingsnelheid.

Veelgestelde vragen

Wat is CLAUDE.md en waar zet je het? CLAUDE.md is een markdown-bestand dat je in de root van je projectrepository plaatst. Claude Code leest het automatisch bij het begin van elke sessie om je projectarchitectuur, conventies, tech stack en beperkingen te begrijpen. Beschouw het als een onboardingdocument speciaal geschreven voor je AI-codeassistent.

Hoe lang moet een CLAUDE.md-bestand zijn? Streef naar 300-800 woorden. Kortere bestanden missen kritieke context, maar alles boven de 1.000 woorden begint je contextvenster op te eten — ruimte die beter voor daadwerkelijke code-redenering zou kunnen worden gebruikt. Wees beknopt en specifiek. Elke zin moet haar plaats verdienen. Als je meer diepgang nodig hebt, link naar externe documentatie in plaats van het in te sluiten.

Moet ik CLAUDE.md in versiebeheer committen? Absoluut. CLAUDE.md moet als welke ander projectdocumentatie worden behandeld — versiebeheerd, beoordeeld, en up-to-date gehouden. Je hele team profiteert van consistent AI-gedrag. Persoonlijke voorkeuren gaan naar ~/.claude/CLAUDE.md in plaats daarvan, wat op elke developer's machine locaal blijft.

Hoe verschilt CLAUDE.md van .cursorrules? De inhoud is bijna identiek — beide verstrekken projectcontext aan een AI-codering hulpmiddel. Het verschil is welk hulpmiddel ze leest. CLAUDE.md is voor Claude Code (Anthropic's CLI-hulpmiddel), terwijl .cursorrules voor Cursor IDE is. Als je beide hulpmiddelen gebruikt, onderhoud je één bron van waarheid en kopieer het naar beide bestanden, aanpassend voor hulpmiddel-specifieke opmaak.

Wat is het belangrijkste onderdeel van een CLAUDE.md? De "Doe NIET" sectie. Negatieve instructies zijn buitensporig effectief bij AI-modellen. Claude vertellen wat je moet vermijden — gebruik geen any types, voeg geen "use client" onnodig toe, installeer geen nieuwe packages zonder te vragen — voorkomt de meest voorkomende en frustrerende fouten. Een goed banlitenlijst bespaard meer tijd dan bladzijden positieve instructies.

Kan ik CLAUDE.md voor niet-code-projecten gebruiken? Ja. CLAUDE.md werkt voor elk project waarin je met Claude Code interacteert. Ik heb effectieve voor documentatie-repo's, infrastructure-as-code projecten, en zelfs data analysis pipelines gezien. Het principe is hetzelfde: geef Claude de context die het nodig heeft om goede beslissingen over je specifieke project te maken.

Hoe vaak moet ik mijn CLAUDE.md bijwerken? Beoordeel het bij elke grote refactor en minstens eenmaal per sprint. Als je een frameworkversie upgrade, een sleuteldependency verandert, of een nieuwe conventie aanneemt, werk het bestand onmiddellijk bij. Verouderde context is slechter dan geen context omdat het de AI actief misleidt. Sommige teams voegen een CLAUDE.md-beoordeling toe aan hun PR-checklist voor infrastructuurwijzigingen.

Werkt CLAUDE.md met Claude op het web (claude.ai)? Nee. CLAUDE.md wordt specifiek door Claude Code, het CLI-gebaseerde codering hulpmiddel, gelezen. Als je Claude via de webinterface of API gebruikt, zou je de context handmatig moeten plakken of de Projects-functie gebruiken om het als kennisbestand bij te voegen. Het automatisch laden van Claude Code is wat het bestand zo krachtig maakt — nul wrijving, elke sessie.