Je AI-codeeringsassistent opent je repo voor het eerst. Het scant bestandsstructuur, afhankelijkheden, misschien een README. Vervolgens stelt het een routerconfiguratie voor die je bestaande lay-outsysteem breekt, importeert een pakket dat je drie sprints geleden hebt afgeschaft, en schrijft tests in een stijl die je team vorig jaar heeft verlaten. De assistent is niet dom — het is blind. Claude Code, Cursor, Copilot, Cody — elke AI pair-programmer stuit op dezelfde muur: het kan je teamcontext niet uit commit-geschiedenis alleen aflezen. Een enkel CLAUDE.md-bestand in je projectroot verandert dat. Het is het verschil tussen een assistent die tegen je conventies in gaat en een die ze uitbreidt als een senior dev die al maanden met je meewerkt. Maar de meeste teams schrijven CLAUDE.md-bestanden die AI niet echt kan gebruiken.

Als je prompts naar Claude Code hebt gegooid en generieke, verkeerde of frustrerende resultaten terugkreeg, is deze gids voor jou. Ik zal je precies uitleggen hoe je je CLAUDE.md structureert, wat je erbij moet doen, wat je kunt 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 elke keer dat het een sessie start. Zie het als onboardingdocumentatie voor je AI pair programmer. Wanneer een nieuwe ontwikkelaar bij je team komt, geef je hem niet zomaar een laptop en zeg je "zorg ervoor dat je het begrijpt." Je leidt hem door de architectuur, legt de vreemde delen uit, wijst op de valkuilen. 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 een nieuwe medewerker vragen om je hele systeem te begrijpen door willekeurige bronbestanden te lezen. Ze krijgen enkele dingen goed, maar ze zullen ook aannames doen die iedereen veel tijd kosten.

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

Hoe Claude Code je projectcontext leest

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

De volgorde waarin context wordt geladen

  1. ~/.claude/CLAUDE.md — Je globale voorkeuren (toegepast op elk project)
  2. ./CLAUDE.md — Het bestand op projectniveau in je repo-root
  3. ./subdirectory/CLAUDE.md — Mapspecifieke overschrijvingen
  4. .claude/settings.json — Projectspecifieke toolrechten 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 zult besteden. Het globale bestand is goed voor persoonlijke voorkeuren ("Ik geef de voorkeur aan functionele componenten" of "altijd TypeScript strict mode"), maar de echte waarde zit in per-projectcontext.

Hier is wat cruciaal is: Claude Code leest het CLAUDE.md aan het begin van elke sessie, maar het heeft ook beperkte contextvensterruimte. Als je CLAUDE.md 5.000 woorden rommelige documentatie is, brand je tokens op die beter kunnen worden gebruikt voor eigenlijke codelogica. Wees beknopt. Wees specifiek. Elke regel moet rechtvaardigen waarom die er is.

De anatomie van een geweldig 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 bij een consistente structuur terechtgekomen die werkt.

De ideale structuur

# Projectnaam

## Overzicht
Eén alinea waarin wordt uitgelegd wat dit project doet en voor wie.

## Tech Stack
Precieze versies en frameworks.

## Architectuur
Hoe de stukken in elkaar passen.

## Belangrijkste conventies
Coderingsnormen, naamgeving patronen, bestandsorganisatieregels.

## Veel gebruikte commando's
Build, test, deploy, en dev commando's.

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

## Bekende problemen / valkuilen
Mijnen om te vermijden.

## Niet doen
Expliciete dingen die de AI nooit zou moeten doen.

Laten we elke sectie nader bekijken.

Sectie-voor-sectie ontleding

Overzicht

Houd dit op maximaal 2-3 zinnen. Claude heeft je productroutekaart niet nodig — het moet het domein begrijpen zodat het contextual passende beslissingen kan nemen.

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

Tech Stack

Wees exact. Zeg niet alleen "React" — geef de versie op, het framework, de renderstrategie. Dit voorkomt dat Claude patronen voorstelt die werken in React 18 maar breken in React 19, of Pages Router aanbeveelt wanneer 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 ofwel te weinig ofwel veel te veel schrijven. Je schrijft geen system design document. Je geeft Claude een mentaal model.

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

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

Alle pagina's worden statisch gegenereerd op build-tijd behalve /blog/[slug]/preview die concept mode gebruikt.

Belangrijkste conventies

Deze sectie bespaart de meeste tijd. Zonder deze zal Claude algemene best practices volgen die in conflict kunnen zijn met je teamkeuzes.

## Belangrijkste conventies
- Componenten worden genoemd in PascalCase, één component per bestand
- Benoemde exports gebruiken, nooit default exports (behalve pages/layouts)
- Alle dataopenum gebeurt in Server Components — gebruik useEffect nooit voor dataopenum
- API-antwoordtypes wonen in lib/types/ en worden automatisch gegenereerd uit Sanity-schema
- Gebruik `cn()` hulpprogramma (lib/utils.ts) voor voorwaardelijk class samenvoegen, 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:)

Veel gebruikte commando's

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

## Veel gebruikte commando's
- `pnpm dev` — Start development server (poort 3000)
- `pnpm build` — Productiebuild
- `pnpm lint` — ESLint + Prettier controleren
- `pnpm test` — Voer Vitest unit tests uit
- `pnpm test:e2e` — Voer Playwright E2E tests uit
- `pnpm sanity:typegen` — Regenereer Sanity types na schemawijzigingen
- `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 verwerkt revalidatie op aanvraag — voeg geen handmatige revalidatielogica toe.
- Afbeeldingsoptimalisatie gaat via Sanity's CDN (cdn.sanity.io), niet next/image voor CMS-content.
- Auth wordt afgehandeld door Clerk — bouw nooit aangepaste auth-flows.
- Het /api/leads eindpunt heeft snelheidsbeperkingen via Upstash Redis. Verwijder de snelheidslimitering middleware niet.

Bekende valkuilen

Elk project heeft vreemde dingen. 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` richtlijn niet in module CSS-bestanden — gebruik inline classes in plaats daarvan
- De vercel.json herschrijft voor /docs/* proxy naar onze Mintlify docs-site. Wijzig deze niet zonder dit met het team te controleren.
- Omgevingsvariabelen met het voorvoegsel NEXT_PUBLIC_ zijn de enige die beschikbaar zijn aan client-zijde. Stel nooit API-geheimen op deze manier bloot.

De sectie "Niet doen"

Dit is mogelijk de meest belangrijke sectie. Negatieve instructies zijn ongelooflijk effectief bij AI-modellen.

## Niet doen
- Installeer geen nieuwe afhankelijkheden zonder eerst te vragen
- Gebruik geen `any` type — zoek of maak passende types
- Maak geen nieuwe API-routes voor dingen die in Server Components kunnen gebeuren
- Wijzig de Sanity-schemabestanden niet zonder het migratieplan te bevestigen
- Gebruik `"use client"` niet tenzij de component echt browser-API's of event handlers nodig heeft
- Schrijf geen CSS-bestanden — alles is Tailwind-hulpprogrammaklassen
- Harde code geen strings die uit de CMS zouden moeten komen

Echte CLAUDE.md voorbeelden

Voorbeeld: Next.js marketingsite

Dit is een versimpelde versie van een CLAUDE.md dat we gebruiken op clientprojecten, vooral bij het bouwen van Next.js-sites met backends van headless CMS.

# Acme Marketingsite

## Overzicht
Marketingwebsite voor Acme (acme.com). Gebouwd met Next.js 15, gestileerd met Tailwind v4, content 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 dataopenum 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 benoemde exports (behalve page.tsx/layout.tsx)
- Componenten: PascalCase, één per bestand
- cn() voor class samenvoegen
- Zod-schema's voor alle formuliervalidatie
- Geen useEffect voor dataopenum. Nooit.

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

## Niet doen
- Voeg niet "use client" toe zonder verantwoording
- Installeer pakketten niet zonder te vragen
- Gebruik geen default exports voor componenten
- Wijzig sanity/schema/ bestanden niet zonder migratie te bevestigen
- Gebruik geen 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 content met aangepaste componenten.

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

## Architectuur
src/content/ — MDX artikelen met Zod-gevalideerde frontmatter
src/components/ — Astro componenten (nul JS) en React eilanden (interactief)
src/layouts/ — Basis lay-outs
src/pages/ — Bestandsgebaseerde routing

## Belangrijkste regels
- Standaard ingesteld op Astro componenten (.astro). Gebruik React alleen voor eilanden die interactiviteit nodig hebben.
- client:visible voor interactieve componenten onder de fold
- client:idle voor niet-kritieke interactieve componenten
- Gebruik client:load nooit tenzij absoluut noodzakelijk
- Alle afbeeldingen gebruiken Astro's Image component met juiste breedte/hoogte
- RSS-feed genereert automatisch uit content collection — bouw geen handmatige feed logica

## Niet doen
- Voeg React componenten niet toe als een Astro component zou werken
- Gebruik de client:load richtlijn niet
- Sla afbeeldingsdimensies niet over (veroorzaakt CLS)
- Wijzig het content collection schema niet zonder bestaande frontmatter bij te werken

Veelvoorkomende fouten die je AI-context ruïneren

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

Fout Waarom het pijn doet Oplossing
Te lang (2000+ woorden) Verbrandt context window tokens, belangrijke info gaat verloren Houd onder 800 woorden. Link naar externe docs voor deep dives.
Te vaag ("we gebruiken React") Claude vult gaten in met aannames Wees specifiek: versies, patronen, exacte tools
Geen negatieve instructies Claude doet "redelijke" dingen die je conventies breken Neem altijd een "Niet doen" sectie op
Copy-paste README.md README's zijn voor mensen, niet voor AI context Schrijf CLAUDE.md vanaf nul met AI-specifieke framing
Gevoelige data opnemen API-sleutels, geheimen in contextbestanden Zet nooit geheimen in CLAUDE.md. Verwijs naar .env.example in plaats daarvan
Nooit bijwerken Project evolueert, contextbestand niet Bekijk CLAUDE.md elke sprint of grote refactoring
Tegenstrijdige instructies "Gebruik server components" + voorbeelden met useEffect fetching Laat één persoon het bestand bezitten, controleer op consistentie

CLAUDE.md versus andere AI-contextbestanden

Claude Code is niet het enige AI-gereedschap dat projectcontextbestanden leest. Hier is hoe het landschap eruit ziet in 2026:

Bestand Gereedschap Auto-Read Bereik
CLAUDE.md Claude Code Ja, bij sessiestart Projectwijd
.cursorrules Cursor Ja, bij bestand openen Projectwijd
.github/copilot-instructions.md GitHub Copilot Ja, in Copilot Chat Repo-wijd
.windsurfrules Windsurf (Codeium) Ja Projectwijd
AGENTS.md OpenAI Codex CLI Ja Projectwijd
.ai/context.md Aangepaste conventie Nee (handmatige referentie) Varieert

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

Als je team meerdere AI-gereedschappen gebruikt (en veel doen dat in 2026), overweeg dan het onderhouden van één enkele bron van waarheid en het genereren van toolspecifieke bestanden ervan. 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, kunt u CLAUDE.md bestanden in submappen plaatsen. Claude Code leest de meest specifieke voor de map 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 behandelt gedeelde architectuur en conventies. Elk genest bestand voegt specificiteiten toe voor dat pakket.

Dynamische context met /compact

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

  1. Start met CLAUDE.md automatisch geladen
  2. Werk aan een functie
  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 version control (het moet worden doorgevoerd). Maar individuele ontwikkelaars gebruiken ook ~/.claude/CLAUDE.md voor persoonlijke voorkeuren:

# Persoonlijke voorkeuren
- Ik geef de voorkeur aan uitgebreide variabelnamen boven afkortingen
- Toon me de redenering voordat je code schrijft
- Wanneer u wijzigingen voorstelt, toon dan het volledige bestandsverschil
- Ik gebruik VS Code met Vim-sleutelverbindingen (stel IDE-specifieke snelkoppelingen niet voor)

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

Impact meten

Hoe weet je dat je CLAUDE.md werkt? Hier zijn metreken die we intern bijhouden:

  • Nauwkeurigheid eerste poging: Hoe vaak is Claude's eerste reactie nul correcties nodig? Een goed CLAUDE.md haalt dit boven de 80%.
  • Conventievergrijpingen: Tel hoe vaak Claude je coderingsnormen breekt. Zou naar nul moeten gaan.
  • Contextargumenten: Als Claude steeds vraagt "wat framework is dit?" of "zou ik de App Router moeten gebruiken?", mist je CLAUDE.md informatie.
  • Ongedaan maak frequentie: Hoe vaak je Claude's wijzigingen moet verwerpen of ongedaan moet maken. Lager is beter.

Een team bij een midden-groot startup rapporteerde het inkorten van hun gemiddelde AI-ondersteunde taaktijd van 12 minuten tot 4 minuten na het investeren van een uur in hun CLAUDE.md. Dat is een 3x verbetering van één bestand.

Veelgestelde vragen

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

Hoe lang zou een CLAUDE.md-bestand moeten zijn? Mikke voor 300-800 woorden. Kortere bestanden missen kritieke context, maar alles meer dan 1.000 woorden begint contextvensterruimte op te eten — ruimte die beter kan worden gebruikt voor eigenlijke codelogica. Wees beknopt en specifiek. Elke zin moet rechtvaardigen waarom die er is. Als je meer diepte nodig hebt, link naar externe documentatie in plaats van het in te bedden.

Moet ik CLAUDE.md naar version control committen? Absoluut. CLAUDE.md moet als elke ander projectdocumentatie behandeld worden — versioned, beoordeeld, en up-to-date gehouden. Je hele team profiteert van consistent AI-gedrag. Persoonlijke voorkeuren gaan in plaats daarvan in ~/.claude/CLAUDE.md, wat lokaal op de machine van elke ontwikkelaar blijft.

Hoe verschilt CLAUDE.md van .cursorrules? De content is bijna identiek — beide bieden projectcontext aan een AI-coderinggereedschap. Het verschil is welk gereedschap ze leest. CLAUDE.md is voor Claude Code (Anthropic's CLI-gereedschap), terwijl .cursorrules voor Cursor IDE is. Als je beide gereedschappen gebruikt, onderhoud één enkele bron van waarheid en kopieer het naar beide bestanden, pas aan voor toolspecifieke opmaak.

Wat is het belangrijkste onderdeel van een CLAUDE.md? De sectie "Niet doen". Negatieve instructies zijn onevenredig effectief bij AI-modellen. Tegen Claude zeggen wat je kunt vermijden — gebruik geen any types, voeg "use client" niet onnodig toe, installeer geen nieuwe pakketten zonder te vragen — voorkomt de meest voorkomende en frustrerende fouten. Een goede banlijst bespaart meer tijd dan pagina's met positieve instructies.

Kan ik CLAUDE.md voor niet-codeprojecten gebruiken? Ja. CLAUDE.md werkt voor elk project waar je interactie hebt met Claude Code. Ik heb doeltreffende voor documentatie repo's, infrastructure-as-code projecten, en zelfs gegevensanalysepijpleidingen 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? Beoordeeldat het bij elke grote refactoring en minstens eenmaal per sprint. Als je een frameworkversie upgrade, een sleutelbijlage wijzigt, of een nieuwe conventie aanneemt, werk het bestand onmiddellijk bij. Verouderde context is erger dan geen context omdat deze 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 gelezen door Claude Code, het CLI-gebaseerde coderinggereedschap. Als je Claude via de webinterface of API gebruikt, moet je de context handmatig plakken of de Projects-functie gebruiken om het als kennisbestand aan te hechten. Het automatische laden van Claude Code is wat het bestand zo krachtig maakt — nul wrijving, elke sessie.