CLAUDE.md: zo optimaliseer je je systeemprompt voor Claude Code

Elke keer dat je Claude Code opstart, leest het als eerste je CLAUDE.md. Dat bestand is je systeemprompt. Het is een van de kernonderdelen van de agent harness die bepaalt hoe Claude Code werkt. Toch behandelen de meeste mensen het als een to-do lijstje met losse instructies. Dat is een gemiste kans. In dit artikel laat ik zien hoe je een CLAUDE.md opbouwt als een levend document dat elke sessie beter wordt.

Wat doet een CLAUDE.md precies?

Een CLAUDE.md is het eerste bestand dat Claude Code leest wanneer je een sessie start. Het staat in de root van je project en fungeert als systeemprompt: een set instructies die bepaalt hoe Claude zich gedraagt binnen jouw specifieke context.

Maar het is meer dan een instructieset. Als je het goed opbouwt, vervult een CLAUDE.md vier functies tegelijk.

1. Kenniscompressie

In plaats van dat Claude je hele workspace door moet spitten (bestand voor bestand), comprimeert je CLAUDE.md al die kennis tot een beknopte samenvatting. Welke technologieen gebruik je? Hoe is je mappenstructuur opgezet? Welke conventies gelden er? Dat scheelt tientallen bestanden die Claude anders eerst zou moeten lezen voordat het iets zinnigs kan doen.

Stel, je werkt aan een Nuxt-project met i18n, Tailwind CSS en Cloudinary als image provider. Zonder CLAUDE.md moet Claude dat zelf uitvogelen door je nuxt.config.ts, package.json en mappenstructuur te doorzoeken. Met een goede CLAUDE.md weet het dat in drie regels:

## Stack
- **Framework**: Nuxt 4 (Vue 3)
- **Styling**: Tailwind CSS (utility classes only, geen <style> blocks)
- **Images**: Cloudinary provider via @nuxt/image

Dat is kenniscompressie. Je betaalt minder tokens en krijgt sneller relevante output. Lees hoe je hiermee concreet tokenkosten bespaart.

2. Voorkeuren

De tweede functie is het vastleggen van je voorkeuren. Hoe wil je dat Claude communiceert? Welke codeerstijl gebruik je? Welke patronen vermijd je? Dit gaat verder dan technische configuratie. Het gaat over hoe jij werkt.

Een paar voorbeelden uit de praktijk:

## Regels
- Schrijf code en comments in het Engels
- Content en documentatie in het Nederlands
- Gebruik altijd Tailwind CSS utility classes, nooit <style> blocks
- Conventional commits (feat/fix/chore/refactor/docs)
- Werk altijd op een feature branch, nooit direct op main

Zonder deze voorkeuren maakt Claude keuzes op basis van wat het "denkt" dat je wilt. Soms klopt dat. Vaak niet. Door het expliciet vast te leggen, hoef je Claude niet steeds te corrigeren. Dat bespaart je frustratie en tokens.

3. Capaciteiten

De derde functie is het beschrijven van wat Claude kan en mag doen binnen je project. Welke commando's zijn beschikbaar? Welke tools en scripts bestaan er? Dit geeft Claude een kaart van de mogelijkheden.

In onze eigen monorepo ziet dat er bijvoorbeeld zo uit:

## Essential Commands
pnpm dev                   # Start alle apps via Turborepo
pnpm build                 # Build alle apps
pnpm lint                  # Lint alle apps

## Skills
| Skill          | Beschrijving                                |
|----------------|---------------------------------------------|
| writing-guide  | SEO-geoptimaliseerde content in brand voice |
| seo-analyst    | Keyword analyse en concurrentie-onderzoek   |
| developer      | Component en composable development         |

Zonder dit overzicht weet Claude niet dat pnpm lint bestaat, of dat er een writing-guide skill beschikbaar is. Het gaat dan raden. Of het vraagt het aan jou, wat je net zo veel tijd kost als het zelf doen.

4. Faal- en succeslog

De vierde functie is misschien de meest onderschatte: je CLAUDE.md als logboek van wat werkt en wat niet werkt. Elke keer dat je een probleem oplost of een patroon ontdekt, leg je dat vast. Niet in een apart document dat niemand meer terugvindt, maar direct in je systeemprompt.

## Known Issues
1. Sitemap handler mist (nuxt.config.ts verwijst naar een route die niet bestaat)
2. routeRules staan uitgecomment (SWR caching is gedefinieerd maar niet actief)

## Troubleshooting
- Content niet zichtbaar? Check of draft niet true is en publishedAt in het verleden ligt
- SQLite errors? Vereist Node 22+. Verwijder .data/ en draai pnpm dev opnieuw

Die kennis is hard-won. Je hebt er tokens en tijd aan besteed om dat uit te zoeken. Door het vast te leggen in je CLAUDE.md, hoeft Claude (en jijzelf) dat nooit meer opnieuw te ontdekken.

Hoe werken globale en lokale CLAUDE.md bestanden samen?

Claude Code leest niet een, maar potentieel drie niveaus van configuratie:

1. Globaal (~/.claude/CLAUDE.md). Geldt voor al je projecten. Hier zet je persoonlijke voorkeuren die overal gelden: je taal, je commitstijl, je communicatievoorkeuren.
2. Project-root (CLAUDE.md in je project). De hoofdconfiguratie per project. Hier staat je stack, mappenstructuur, conventies en commando's.
3. Submappen (CLAUDE.md in een submap). Voor specifieke delen van je project die eigen regels hebben. In een monorepo kun je bijvoorbeeld een apart CLAUDE.md hebben voor je website-app en een ander voor je API.

Claude leest ze in die volgorde en combineert ze. De meest specifieke instructie wint. Dat betekent dat je in je globale bestand kunt zetten dat je altijd conventional commits gebruikt, terwijl je in een specifiek project kunt aangeven dat die conventie daar niet geldt.

Een concreet voorbeeld uit onze monorepo:

growcode-monorepo/
├── CLAUDE.md                    # Monorepo-brede regels
├── apps/
│   └── website/
│       ├── CLAUDE.md            # Website-specifieke stack en patronen
│       └── content/
│           └── CLAUDE.md        # Contentrichtlijnen en frontmatter schema

Het root-bestand beschrijft de monorepo-structuur en gedeelde commando's. Het website-bestand gaat dieper in op Nuxt, i18n en de data-fetching patronen. Het content-bestand beschrijft het frontmatter-schema en de schrijfregels. Zo krijgt Claude op elk niveau precies de context die het nodig heeft, zonder dat je alles in een bestand propt.

Wat is de plan-instantiate-learn loop?

Dit is waar een CLAUDE.md van een statisch document verandert in een systeem dat zichzelf verbetert. De loop bestaat uit drie stappen:

Plan. Je begint met een duidelijk plan voor je CLAUDE.md. Wat moet Claude weten over je project? Welke regels gelden er? Welke fouten heb je eerder gezien? Je schrijft een eerste versie op basis van wat je nu weet.

Instantiate. Je gaat werken met Claude Code en je CLAUDE.md wordt actief gebruikt. Claude leest het, volgt de instructies en produceert output. Hier zie je wat werkt en wat niet. Misschien genereert Claude steeds <style> blocks terwijl je Tailwind wilt. Of het vergeet om op een feature branch te werken.

Learn. Na elke sessie (of zelfs tijdens de sessie) update je je CLAUDE.md met wat je hebt geleerd. De <style> block fout? Voeg een expliciete regel toe. De vergeten feature branch? Maak het een vetgedrukte instructie. Je CLAUDE.md groeit mee met je project.

Dit is geen eenmalig proces. Het is een continue cyclus. Na tien sessies is je CLAUDE.md fundamenteel anders dan na de eerste. Het bevat de lessen uit tien sessies foutcorrectie, ontdekte patronen en opgebouwde context. Dat is de kern: je CLAUDE.md is een levend document.

Stel, je bent een bouwer die werkt aan een marketingplatform. Na drie sessies met Claude Code heb je ontdekt dat:

• Claude standaard CSS modules gebruikt in plaats van Tailwind
• Het Nederlandse content soms in het Engels schrijft
• Het direct op main commit in plaats van feature branches

Die drie inzichten worden drie regels in je CLAUDE.md. Bij sessie vier zijn die problemen verleden tijd. Bij sessie tien heb je twintig van dit soort regels. Je CLAUDE.md is een verzameling van alles wat je Claude hebt moeten leren, zodat je het nooit meer opnieuw hoeft uit te leggen.

Hoe gebruik je /init en /compact om je CLAUDE.md actueel te houden?

Claude Code heeft twee ingebouwde commando's die direct helpen bij het onderhouden van je systeemprompt.

/init voor nieuwe projecten

Wanneer je /init uitvoert in een project zonder CLAUDE.md, analyseert Claude je codebase en genereert een eerste versie. Het detecteert je framework, package manager, mappenstructuur en bestaande configuratie. Dat is je startpunt.

Het resultaat is nooit perfect. Claude mist nuances die alleen jij kent: je voorkeuren, je teamafspraken, de bugs die je al hebt opgelost. Maar het geeft je een solide basis om mee te werken. Veel beter dan een leeg bestand.

/compact voor kennisbehoud

Tijdens lange sessies bouw je context op. Claude leert dingen over je project die niet in je CLAUDE.md staan. Het commando /compact comprimeert die opgebouwde context tot een samenvatting. Die samenvatting kun je gebruiken om je CLAUDE.md bij te werken.

Het patroon is: werk een sessie lang met Claude, voer /compact uit aan het eind, en verwerk de relevante inzichten in je CLAUDE.md. Zo gaat geen kennis verloren tussen sessies.

Hoe ziet een goed gestructureerde CLAUDE.md eruit?

Na honderden uren werken met Claude Code in onze eigen projecten, is dit de structuur die voor ons het beste werkt:

1. Projectomschrijving (2-3 regels). Wat is dit project? Welk probleem lost het op? Dit geeft Claude direct de juiste mentale context.

2. Mappenstructuur. Een beknopt overzicht van de belangrijkste mappen. Geen listing van elk bestand, maar genoeg om te navigeren.

3. Essential commands. De commando's die Claude nodig heeft: dev server starten, builden, linten, tests draaien. Niks meer, niks minder.

4. Stack en architectuur. Welke technologieen, welke patronen, welke harde regels. Dit is waar kenniscompressie het meeste werk doet.

5. Universele regels. De do's en don'ts die overal gelden. Taal, commitstijl, styling, branchstrategie.

6. Known issues en troubleshooting. Je faal- en succeslog. Wat werkt niet, wat zijn de workarounds, waar liggen de valkuilen.

Een veelgemaakte fout is om je CLAUDE.md te lang te maken. Als het document meer dan 500 regels telt, wordt het contraproductief. Claude moet het bij elke sessie lezen, en hoe langer het is, hoe meer tokens dat kost en hoe groter de kans dat het details mist. Wees bondig. Gebruik verwijzingen naar andere bestanden voor gedetailleerde documentatie.

Het is hetzelfde principe als een goede YAML frontmatter: gestructureerde metadata die machines (en mensen) helpt om snel de kern te begrijpen.

Hoe verschilt een CLAUDE.md van Claude Skills en Agents?

Een CLAUDE.md is je projectbrede systeemprompt. Het geldt voor alles wat Claude doet binnen je project. Claude Skills en Agents zijn daarentegen gericht op specifieke taken.

Een skill is een herbruikbare instructieset voor een bepaalde taak (content schrijven, SEO-analyse, code review). Een agent is een autonome uitvoerder die skills combineert om een workflow af te ronden. Je CLAUDE.md vormt de basis waarop skills en agents draaien. Het is de gedeelde context die ze allemaal lezen.

In de praktijk werkt het zo: je CLAUDE.md beschrijft je project, je stack en je regels. Je claude skills beschrijven hoe specifieke taken moeten worden uitgevoerd. En je agents combineren die skills tot complete workflows. Drie lagen, elk met hun eigen verantwoordelijkheid.

Als je merkt dat je in je CLAUDE.md steeds meer taakspecifieke instructies toevoegt (hoe content moet worden geschreven, welke SEO-regels gelden), is dat een signaal om die kennis te verplaatsen naar een skill. Je CLAUDE.md blijft dan schoon en gefocust op projectbrede context.

Wat zijn de meest gemaakte fouten bij het opzetten van een CLAUDE.md?

Na veel experimenteren met onze eigen CLAUDE.md en die van andere projecten, zie ik steeds dezelfde fouten terugkomen.

Te vaag. Regels als "schrijf goede code" of "volg best practices" zijn waardeloos. Claude interpreteert ze naar eigen inzicht. Wees specifiek: "Gebruik altijd TypeScript strict mode, geen any types" is een regel waar Claude iets mee kan.

Te lang. Een CLAUDE.md van duizend regels is geen systeemprompt meer, maar een boek. Claude leest het wel, maar de kans dat het alles onthoudt is klein. Houd het onder de 300-500 regels en verwijs naar andere bestanden voor details.

Nooit bijgewerkt. De eerste versie is zelden de beste. Als je na twintig sessies nog steeds dezelfde CLAUDE.md gebruikt, mis je alle lessen die je onderweg hebt geleerd.

Alleen positieve instructies. Vertellen wat Claude wel moet doen is belangrijk. Maar vertellen wat het niet moet doen is minstens zo waardevol. "Geen <style> blocks" is effectiever dan "gebruik Tailwind CSS", omdat het expliciet een foutpatroon blokkeert.

Geen structuur. Een CLAUDE.md zonder koppen, zonder secties, zonder logische opbouw is moeilijk te scannen. Voor Claude net zo goed als voor jou. Gebruik duidelijke H2-koppen en houd secties kort.

Conclusie

Een CLAUDE.md is meer dan een configuratiebestand. Het is een systeem dat kenniscompressie, voorkeuren, capaciteiten en geleerde lessen combineert tot een document dat elke sessie beter wordt. De plan-instantiate-learn loop zorgt ervoor dat je investering in tijd en tokens zich steeds opnieuw terugbetaalt.

Begin met /init om een eerste versie te genereren. Werk ermee. Ontdek wat werkt en wat niet. En update je CLAUDE.md na elke sessie. Over tien sessies heb je een systeemprompt die Claude verandert van een generalist naar een specialist die jouw project door en door kent.

Het belangrijkste inzicht: je CLAUDE.md is geen document dat je een keer schrijft en dan vergeet. Het is het meest waardevolle bestand in je project, omdat het alles bevat wat je Claude ooit hebt moeten leren.