Claude.md: het bestand dat Claude Code voor je laat werken

Je devteam legt Claude Code steeds dezelfde dingen uit. Waar de authenticatielogica staat. In welke map de Stripe-webhooks zitten. Waarom niemand aan de oude billingmodule komt. Elke sessie begint weer bij nul, en elke sessie kost tijd waarvoor je betaalt.

CLAUDE.md lost dat op. Het is een platte-tekstbestand dat in je project staat en automatisch wordt gelezen voordat Claude aan de slag gaat. Zie het als het inwerkdocument dat je een nieuwe medewerker op dag één zou geven, alleen wordt dit exemplaar echt elke keer gelezen.

De meeste teams doen dit op een van twee manieren verkeerd. Ze slaan het bestand over en betalen keer op keer voor dezelfde correcties. Of ze proppen het hele technische handboek erin en Claude verdrinkt in details die het niet nodig had. Geen van beide levert op waarvoor je betaalt.

Twijfel je nog of Claude Code de moeite waard is om in te voeren? Lees dat eerst. Dit artikel gaat ervan uit dat je die knoop al hebt doorgehakt en de setup nu goed wilt doen.

Belangrijkste punten

• CLAUDE.md is een bestand dat Claude Code automatisch leest, zodat je niet langer betaalt om het elke sessie opnieuw je project te laten leren
• Het werkt als een inwerkdocument voor een nieuwe medewerker, niet als een technisch configuratiebestand
• Een goed bestand is kort en specifiek voor de eigenaardigheden van jouw project, geen lijst met generieke regels die uit een sjabloon zijn gekopieerd
• De beste CLAUDE.md-bestanden worden bijgewerkt elke keer dat Claude dezelfde fout herhaalt, net zoals je een nieuwe medewerker zou corrigeren
• Anthropic raadt aan het bestand onder de ongeveer 200 regels te houden, want opgeblazen bestanden vreten context op en verslechteren de kwaliteit van de output
• Hieronder vind je een echt voorbeeld en een kopieerbare template, geen programmeerervaring nodig om ze te gebruiken

Wat is claude.md?

CLAUDE.md is een tekstbestand dat in de root van je project staat. Zodra je een Claude Code-sessie start, leest het dat bestand voordat het iets anders aanraakt. Dat is het hele mechanisme. Geen plugin, geen dashboard, geen installatiewizard.

Waar het staat

Het bestand staat in de rootmap van je project, naast je package-configuratie en de bovenliggende broncodemappen. Bij grotere codebases wordt soms een tweede CLAUDE.md toegevoegd in een specifieke submap, zoals een API-service of een mobiele app, zodat die map zijn eigen lokale context krijgt bovenop de projectbrede context.

Wanneer Claude het leest

Claude controleert het bestand aan het begin van een sessie, voordat het wijzigingen aanbrengt. Het leest het niet opnieuw halverwege een gesprek, tenzij je het bestand bewerkt en opnieuw begint. Daarom moet het bestand instructies bevatten die voor het hele project blijven gelden, niet een notitie over waar je vandaag aan werkt.

Het probleem dat het oplost

Zonder CLAUDE.md typ je elke keer opnieuw dezelfde context in de chat: wat het product doet, welke patronen gevolgd moeten worden, welke bestanden verboden terrein zijn. Met het bestand schrijf je dat één keer op en controleert Claude het automatisch aan het begin van elke sessie. Dat betekent minder uitleg, minder herhaalde fouten en minder tijd van je developer die gaat zitten aan het opnieuw briefen van een AI in plaats van bouwen.

Chatinstructies versus een permanent bestand

Het verschil dat voor een founder ertoe doet, is simpel. Chatinstructies zijn een gesprek dat je steeds opnieuw moet voeren. CLAUDE.md is een beslissing die je één keer neemt en die Claude respecteert totdat je die wijzigt. Als een regel voor elke toekomstige sessie moet gelden, hoort die thuis in het bestand, niet in een bericht.

Wat zet je in claude.md?

Hier gaat het bij de meeste bestanden mis: ofwel te mager om iets uit te maken, ofwel te opgeblazen om te lezen. Dit is wat daadwerkelijk een plek verdient:

• Projectoverzicht. Eén of twee zinnen over wat het product doet. Het soort dingen dat je hardop tegen een nieuwe medewerker zou zeggen, geen specificatiedocument.
• Architectuur en mapstructuur. Hoe de onderdelen in elkaar passen, kort gehouden. Dit is oriëntatie, geen diepgaande analyse.
• Codeerconventies en commando's. Ook als je zelf nooit een code-editor opent, is dit belangrijk voor jou: consistentie hier betekent minder bugs die drie weken later opduiken.
• Testinstructies. Hoe je controleert dat er niets kapot is gegaan. Dit is het onderdeel dat antwoord geeft op de vraag of het veilig is om te lanceren.
• Dependencies. Waar het project op leunt en waarom.
• Dingen die Claude nooit mag doen. Founders lezen dit onderdeel het snelst, want het is een vangrail, geen toestemmingsbriefje. Raak nooit rechtstreeks de betalingstabel aan. Verwijder nooit migratiebestanden. Dat soort dingen.
• Workflow en definitie van "klaar". Hoe "klaar" eruitziet binnen jouw team, niet Claude's standaardaanname van klaar.
• Bekende addertjes onder het gras. De rare dingen. De API die liegt over zijn rate limits. Het ene component dat kapotgaat als je er voor 9 uur 's ochtends aankomt, figuurlijk gesproken.

Elk van deze punten hoort erin omdat het verandert wat Claude doet. Als een regel het gedrag van Claude niet zou veranderen, hoort die er niet in.

Claude.md-voorbeeld

Zo ziet dit eruit op een echte stack: Next.js voor de frontend, Supabase voor database en auth, Stripe voor billing. Geen hypothetisch voorbeeld, maar een projectvorm die de meeste founders in deze positie daadwerkelijk hebben.

Voorbeeldbestand

# CLAUDE.md

This file explains how Claude Code should work inside this repository.

Read it before making changes.

## Project

This is a web application for [briefly describe the users and product].

Current priority:
- Build: [current feature or phase]
- Deadline: [date, if relevant]
- Scope: [link or file containing requirements]

If requirements are unclear, ask before implementing.

## Tech stack

- Frontend: Next.js
- Language: TypeScript
- Database: PostgreSQL
- Hosting: Vercel
- Testing: [testing framework]

Do not introduce new frameworks or major dependencies without approval.

## Key project rules

- Follow the existing architecture and coding conventions.
- Keep changes limited to the requested task.
- Do not refactor unrelated code.
- Never modify an existing database migration. Create a new one.
- Add tests for new behaviour and bug fixes.
- Never expose secrets, API keys or environment variables.
- Ask before making architectural changes.

Add new rules here when important project decisions are made.

## Before coding

Before implementing a substantial change:

1. Read the relevant existing code.
2. Identify the files likely to change.
3. State any assumptions.
4. Explain the proposed approach.
5. Define how the result will be tested.

If something is ambiguous, stop and ask rather than guessing.

## Development guidelines

### Keep it simple

Write the minimum code required to solve the requested problem.

Avoid:
- unnecessary abstractions
- speculative features
- new dependencies without a clear reason
- changes unrelated to the task

### Make surgical changes

Every changed line should have a reason connected to the task.

Match the existing project's conventions instead of rewriting surrounding code to match your preferences.

### Verify your work

For a bug:

1. Reproduce the problem.
2. Add or identify a test that catches it.
3. Fix the problem.
4. Run the relevant tests.

For a feature:

1. Define the expected behaviour.
2. Implement it.
3. Test the main path and important edge cases.
4. Run the relevant test suite.

Do not describe work as complete until the relevant checks pass.

## Git workflow

Never work directly on `main`.

For each task:

1. Pull the latest `main`.
2. Create a dedicated branch.
3. Make focused commits.
4. Run tests before opening a pull request.
5. Review the final diff for unrelated changes.

## Communication

Keep explanations short and clear.

When finishing a task, report:

- what changed
- which files were affected
- what was tested
- anything that still needs human review

If you are uncertain about a requirement, say so instead of silently choosing an interpretation.

Waarom deze versie werkt

Niets in dat bestand legt uit wat Next.js is of wat een webhook in het algemeen doet. Het beschrijft alleen wat waar is voor dít project. Dat is precies het punt. Een founder die het leest, kan nog steeds de vorm ervan volgen: wat er is, wat verboden terrein is en wat als klaar geldt, zonder ook maar één regel van de daadwerkelijke codebase te hoeven lezen.

Claude.md-template

Haal de specifieke details eruit en dit is wat overblijft. Kopieer dit, geef het aan je developer en laat diegene de haakjes invullen.

Kopieerbare structuur

# Projectoverzicht
[Wat het product doet, in één of twee zinnen]

# Architectuur
[Belangrijkste mappen en wat erin staat]

# Conventies
[Patronen om te volgen, patronen om te vermijden]

# Commando's
[Dev-server, tests, build, lint, wat je daadwerkelijk gebruikt]

# Doe dit nooit
[Specifieke acties die iets zouden breken of een bedrijfsregel zouden schenden]

# Definitie van klaar
[Wat "klaar" betekent voordat iets wordt uitgebracht]

# Bekende addertjes
[De niet-voor-de-hand-liggende dingen waar je team eerder tegenaan is gelopen]

Zeven onderdelen. Als je bestand langer is dan anderhalve pagina, staat er waarschijnlijk iets in dat al wordt uitgelegd door de code zelf.

Claude.md best practices

Anthropic's eigen richtlijn noemt een specifiek getal: houd deze bestanden onder de ongeveer 200 regels. Voorbij dat punt begint het bestand context op te eten die Claude nodig heeft voor het eigenlijke werk, en wordt het opvolgen van instructies slechter, niet beter. Meer is hier niet nuttiger. Het is precies andersom.

Documenteer niet wat Claude al kan lezen

Als een functie calculateInvoiceTotal heet, hoef je geen regel toe te voegen die uitlegt wat er wordt berekend. Claude leest code. Bewaar het bestand voor wat de code niet uit zichzelf kan vertellen.

Geef prioriteit aan wat uniek is voor jouw project

'Schrijf schone code' vertelt Claude niets. 'Omzeil nooit het RLS-beleid in de facturentabel' vertelt Claude iets wat het onmogelijk had kunnen raden. Generiek advies is overal gratis te vinden. De specifieke regels van jouw project zijn het enige dat dit bestand kan bieden wat een algemene AI-codeergids niet kan.

Gebruik commando's, geen omschrijvingen

Run npm run test is beter dan een vage herinnering om te zorgen dat het getest is. Een instructie die Claude direct kan uitvoeren is meer waard dan een omschrijving die het moet interpreteren.

Documenteer de grenzen

Wees specifiek over wat Claude niet mag aanraken: welke tabellen, welke bestanden, welke mappen verboden terrein zijn en waarom. Dit is het onderdeel dat de dure fouten voorkomt, de fouten die een founder echt geld kosten om terug te draaien.

Vertel Claude hoe het zijn eigen werk kan controleren

Als er een testsuite of een typecheck-commando is, zet dat dan rechtstreeks in het bestand. Een model dat weet hoe het zijn eigen output kan controleren, vangt meer problemen op voordat ze bij jou terechtkomen.

Maak er geen technisch handboek van

Een volledig inwerkhandboek, stijlgids of architectuurbeslissingenlogboek kan ergens anders staan. CLAUDE.md is bedoeld voor wat het gedrag van Claude daadwerkelijk verandert in déze specifieke codebase, niets meer.

Laat het meegroeien met Claude's fouten

Dit is de praktijk die het meest telt, en die zelden voorkomt in generieke gidsen. Als Claude dezelfde projectspecifieke fout twee keer maakt, is dat geen eenmalige correctie meer. Dat is een regel die in het bestand thuishoort, net zoals je inwerkmateriaal zou bijwerken nadat een nieuwe medewerker twee keer over hetzelfde struikelde. Behandel elke herhaalde fout als een signaal om het bestand bij te werken, niet alleen de code.

Hoe wij claude.md gebruiken bij AI-ondersteunde ontwikkeling

We schrijven dit niet vanaf een whiteboard. Elk project dat we met Claude Code bouwen, begint met een CLAUDE.md-bestand dat meegroeit met de codebase, in plaats van één keer geschreven en daarna aan zijn lot overgelaten te worden. Weeg je Claude Code af tegen andere coding agents voor je team? Onze vergelijking van Gemini CLI en Claude Code laat zien waar elk van de twee sterk staat.

Minder herhaalde uitleg

De tijd die wordt besteed aan het opnieuw uitleggen van context, sessie na sessie, daalt tot bijna nul, omdat het bestand dat al bevat. Dat levert uren op bij elk project, niet alleen in de eerste week ervan.

Meer consistentie in de codebase

Een codebase die over weken wordt opgebouwd, blijft consistent wanneer dezelfde regels automatisch in elke sessie gelden. Dat is belangrijk wanneer een founder erop vertrouwt dat AI-ondersteund werk standhoudt bij echt gebruik, niet alleen in een demo.

Minder onzichtbare architecturale wijzigingen

Grenzen die in het bestand zijn vastgelegd, voorkomen dat Claude wijzigingen doorvoert die een niet-technische founder onmogelijk had kunnen opmerken totdat er iets stukging in productie.

Betrouwbaardere tests en controles

Tests en controles worden daadwerkelijk uitgevoerd zoals bedoeld, omdat het bestand Claude vertelt hoe het zijn eigen werk moet verifiëren in plaats van die stap optioneel te laten.

Betere continuïteit tussen sessies

Die continuïteit is wat AI-ondersteunde ontwikkeling laat standhouden op het tempo dat founders daadwerkelijk nodig hebben, niet alleen in een demo, maar over de maanden die het kost om iets echts te bouwen.

Klaar om je project te bouwen met een team dat claude.md als onderdeel van de deliverable ziet?

We zetten dit soort contextbestanden op bij elke AI-ondersteunde build die we uitvoeren, zodat je codebase consistent blijft, ook lang na de eerste sprint. Plan een gesprek in en we laten je zien hoe dat er voor jouw project uitziet.

Start je project, bel Tom.

‍