CLAUDE.md mastery: wat wel en niet werkt

CLAUDE.md is een Markdown bestand dat Claude leest aan het begin van elke sessie. Het bevat project-specifieke instructies die je anders elke keer zou moeten herhalen.

Klinkt simpel. Maar ik zie het constant misgaan. Te veel erin, te weinig erin, verkeerde dingen erin. Het resultaat: Claude negeert je instructies of verspilt context aan irrelevante informatie.

In deze blog: wat wel en niet werkt, gebaseerd op Anthropic's best practices en mijn eigen ervaring.

Het probleem met te veel

CLAUDE.md wordt bij elke interactie geladen. Elke regel kost tokens. Bij elke vraag, elke tool call, elke response.

Te lange CLAUDE.md files zorgen ervoor dat Claude je instructies negeert. De belangrijke regels verdwijnen in de ruis. Je hebt een regel "gebruik altijd strict types" maar Claude doet het niet. Niet omdat het weigert, maar omdat het de regel niet meer ziet tussen alle andere content.

De vuistregel: voor elke regel, vraag jezelf af "zou Claude fouten maken als dit er niet stond?" Zo niet, schrap het.

Wat erin hoort

Drie categorieën, volgens Anthropic's guide:

1. WAT: je stack en structuur

Claude weet niets over je project bij de start van een sessie. Geef een kaart:

## Stack
- PHP 8.5, Laravel 12, Livewire 4
- Filament v5 voor admin panels
- Pest voor testing
- Tailwind CSS v4

## Structuur
- `app/` - Laravel applicatie
- `resources/views/` - Blade views
- `.docs/` - Project documentatie

2. WAAROM: het doel

Wat doet dit project? Waarom bestaat het?

## Project
SaaS platform voor QHSE management. Multi-tenant,
elke organisatie heeft eigen omgeving.

3. HOE: werkwijze

Hoe moet Claude werken in dit project?

## Regels
- Lees `.docs/README.md` voor conventies
- Conventies zijn HARDE REGELS, nooit afwijken
- Run `./vendor/bin/pint --dirty` na code changes
- NOOIT `DB::` gebruiken, altijd Eloquent

Wat er NIET in hoort

Code style guidelines

Nooit een LLM sturen om een linter's werk te doen. Linters zijn sneller, goedkoper, en betrouwbaarder. Gebruik hooks om Pint of Prettier automatisch te draaien, niet instructies om "gebruik 4 spaces indentation".

Tutorials en uitleg

CLAUDE.md is geen documentatie. Het is een instructieset. "Laravel's service container werkt door..." hoort hier niet. Claude kent Laravel. Wat het niet kent zijn jouw specifieke conventies.

Domeinkennis die niet altijd relevant is

Als je alleen bij Livewire werk bepaalde regels nodig hebt, zet die in een skill, niet in CLAUDE.md. Skills laden on-demand, CLAUDE.md altijd.

Lange lijsten met voorbeelden

Een paar voorbeelden kunnen helpen. Twintig voorbeelden vervuilen je context. Zet uitgebreide voorbeelden in aparte files die Claude kan lezen wanneer nodig.

De hiërarchie

CLAUDE.md kan op meerdere plekken staan:

Claude combineert deze automatisch. Globaal + project + subdirectory.

Pointers, niet content

Een krachtig pattern: CLAUDE.md bevat pointers, niet content.

## Documentatie
Project documentatie staat in `.docs/`.
- Lees `.docs/README.md` voor overzicht
- Lees alleen specifieke docs wanneer relevant voor de taak
- Conventies in `.docs/` zijn HARDE REGELS

Nu laadt Claude een kleine CLAUDE.md (weinig tokens), en leest alleen de docs die relevant zijn voor de huidige taak. In plaats van 50K tokens aan documentatie bij elke interactie, misschien 5K wanneer nodig.

Dit is het .docs pattern dat ik gebruik in James.

Laravel projecten: Laravel Boost

Voor Laravel projecten is Laravel Boost een uitkomst. Het is een MCP server speciaal voor Laravel die Claude voorziet van:

• Database schema - Claude ziet je tabellen, kolommen, relaties
• Artisan commands - Beschikbare commands met parameters
• Routes - Alle routes in je applicatie
• Eloquent models - Model structuur en relaties
• search-docs - Semantische search over 17.000+ Laravel-specifieke docs

In plaats van alles in CLAUDE.md uitleggen, laat je Boost het werk doen. Claude kan je schema opvragen, routes checken, en versie-specifieke documentatie zoeken.

Installeren:

composer require laravel/boost --dev
php artisan boost:install

Voor Claude Code:

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

Het resultaat: minder in CLAUDE.md, betere context, accuratere code.

Skills vs CLAUDE.md

De belangrijkste beslissing: wat gaat in CLAUDE.md, wat gaat in skills?

Voorbeeld: "Gebruik Pest voor testing" → CLAUDE.md. "Hoe je Pest arch tests schrijft" → skill.

Emphasis voor belangrijke regels

Claude volgt instructies met emphasis beter. Anthropic raadt aan:

## Regels
- BELANGRIJK: Nooit direct naar production pushen
- MUST: Run tests voor elke commit
- NEVER: Verwijder migrations zonder approval

Maar overdrijf niet. Als alles BELANGRIJK is, is niets belangrijk.

Itereren en testen

Behandel CLAUDE.md als code:

1. Review wanneer dingen misgaan - Claude doet iets verkeerd? Check of de instructie er staat en duidelijk is
2. Prune regelmatig - Verwijder wat niet meer relevant is
3. Test changes - Observeer of Claude's gedrag verandert na een edit

Begin minimaal. Voeg alleen toe wat nodig is. Een CLAUDE.md van 50 regels is bijna altijd te veel.

Starten met /init

Heb je nog geen CLAUDE.md? Start met:

/init

Claude genereert een basis CLAUDE.md gebaseerd op je project structuur. Verfijn van daaruit.

Volgende stap

CLAUDE.md is de basis. De echte kracht zit in de combinatie met skills en subagents en project documentatie.

In mijn AI trainingen bouw je een complete setup van scratch. Of bekijk hoe ik dit toepas bij AI implementatie projecten.

Vragen? Neem contact op.