CLAUDE.md instellen in 2026: sjabloon en 6 regels

Materiaal over vibe coding: tools, praktijkvoorbeelden, fouten. Ailoot-gidsen.

Waarom heb je CLAUDE.md nodig, en waarom vergeet Claude het project zonder dit bestand?#

Op dinsdag open je Claude Code en leg je uit: “Ik werk aan dit project, dit zijn de tools, doe dit niet.” Het werkt.

Op donderdag is diezelfde chat alweer afgelopen, dus herhaal je alles. Op zaterdag opnieuw; op maandag nog een keer.

Zo ziet werken met een agent zonder CLAUDE.md eruit: elk nieuw venster is een stagiair die met een schone lei begint en aan wie je steeds dezelfde dingen moet vertellen. Ik besteedde vroeger 5-10 minuten aan het typen van deze introductie voor elke sessie. De prompts werden lang omdat ik alle context handmatig moest meegeven. En het resultaat bleef algemeen: de agent kende mijn doelgroep, mijn verdienmodel en mijn principes niet.

Met een CLAUDE.md die je bijhoudt, verdwijnt de introductie. Alle regels die je vroeger in elke chat herhaalde, staan in één bestand en verschijnen automatisch aan het begin van elke sessie. De prompt wordt kort: “doe X” in plaats van “ik werk aan project Y, de tools zijn Z, doe A en B niet, en vergeet trouwens ook C niet.”

Daarna verdwijnen de terugkerende fouten.

Elke fout van de agent is een reden om één regel aan CLAUDE.md toe te voegen. Na een maand heb je een levende “projectgrondwet” en trapt Claude niet meer in dezelfde bekende valkuilen.

En er is nog een derde laag: de agent schrijft niet langer in een vacuüm. Via CLAUDE.md verwijs ik Claude naar mappen met context: waar informatie over de doelgroep, prijzen en branding te vinden is. Zonder die verwijzingen schrijft de agent “hoogwaardige oplossingen” zonder mijn verdienmodel te kennen, waardoor ze abstract, clichématig en “net als die van iedereen” worden.

Wat is CLAUDE.md, en in welke volgorde leest Claude het?#

Anthropic beschrijft CLAUDE.md als volgt in de officiële documentatie:

De vier plaatsen waar Claude Code naar CLAUDE.md zoekt, in oplopende volgorde van prioriteit:

Alle vier de bestanden worden tegelijk in de context geladen. Als de regels met elkaar in conflict zijn, zegt Anthropic in de documentatie rechtstreeks dat onbekend is welke regel voorrang krijgt; Claude kan er willekeurig een kiezen. Daarom is het eenvoudiger om alle belangrijke informatie in de CLAUDE.md van het project te bewaren en geen duplicaten te maken.

Er is één technisch detail waar bijna niemand over schrijft, maar dat veel vreemd gedrag verklaart.

Met andere woorden: CLAUDE.md is in strikte zin geen “systeemprompt”. Het is het eerste gebruikersbericht dat Claude ziet. De regels zijn dus sterke suggesties, geen wetten. Moet een regel worden afgedwongen, gebruik dan een geteste hook voor de betreffende gebeurtenis en machtigingen of omgevingsisolatie voor de bredere toegangsgrens. Het automatisch uitvoeren van een hook maakt de controles ervan niet volledig. Hieronder leg ik uit waar de grens ligt tussen hooks en CLAUDE.md.

Hoe schrijf je in 5 minuten een minimale CLAUDE.md (kant-en-klaar sjabloon)?#

Hieronder staat een sjabloon dat ik in tientallen projecten heb getest. Het houdt het bestand rond de 80-120 regels, binnen Anthropics aanbeveling om naar minder dan 200 regels te streven. Met dit sjabloon geeft de agent de meest bruikbare resultaten.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Om Claude dit sjabloon automatisch voor je project te laten invullen, geef je het deze prompt. Claude leest de context en vult de velden tussen vierkante haken in:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Streef naar minder dan 200 regels voor de resulterende CLAUDE.md. Bekijk bij een langer bestand duplicaten en verplaats gedetailleerde procedures naar gekoppelde bestanden. Behoud essentiële regels voor planning, terugblik en de repository en test die daarna op representatieve taken.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Als je nog geen mappen about-me/ en business/ hebt, is dat geen probleem. Claude stelt verduidelijkende vragen en stelt een minimale CLAUDE.md samen op basis van wat beschikbaar is. Je kunt de mappen later maken, zodra je weet wat erin moet.

Welke 6 regels maken van CLAUDE.md een levend document?#

Regel 1. Houd het onder 200 regels

Anthropic zegt het beknopt in de officiële documentatie:

Een lange CLAUDE.md werkt op twee manieren tegen zichzelf. Ten eerste kost het tokens. Een bestand met 800 regels instructies wordt in elk venster geladen en verbruikt in elke sessie enkele duizenden tokens van je budget. Bij een Pro-abonnement met een daglimiet vermindert dat merkbaar het aantal beschikbare sessies. Ten tweede begint het model de regels te negeren.

De documentatie raadt aan onder de 200 regels te blijven om contextgebruik te beperken en naleving te verbeteren. Ze stelt geen scherpe faalgrens bij regel 201 vast. Beoordeel relevantie, tegenstrijdigheden, de geladen hoeveelheid tokens en echte taakresultaten voordat je besluit wat je elders onderbrengt.

Regel 2. Sluit elke sessie af met een terugblik

Schrijf in CLAUDE.md: “Leg aan het einde van elke sessie vast wat je hebt gedaan en geleerd in retrospectives/YYYY-MM-DD_*.md.” Zodra je deze regel toevoegt, begint Claude elke sessie vanzelf met een terugblik af te sluiten; je hoeft er niet om te vragen.

Waarom terugblikken:

• Twee weken later kun je een oude terugblik openen en je herinneren waarom je die aanpak koos.
• Wanneer je een maand later terugkeert naar het project, heb je een kant-en-klare kaart van recente beslissingen.
• Als je in een team werkt, kan een partner de terugblik lezen en in 2 minuten begrijpen wat de huidige stand is, zonder telefoontje.

Regel 3. Commit na elke afgeronde taak

In mijn CLAUDE.md staat: “Maak na elke afgeronde taak een git-commit met een betekenisvolle boodschap.” Claude begint het werk dan vanzelf in atomaire commits op te delen.

Dit levert je twee dingen op. Ten eerste kun je, als er iets stukgaat, één handeling terugdraaien in plaats van “alles wat ik vandaag heb gedaan”. Ten tweede wordt de commitgeschiedenis een werklogboek dat laat zien wat er veranderde en in welke volgorde.

Regel 4. Raadpleeg altijd de map business/

Bij elke taak over klanten, producten of teksten moet de agent eerst business/INDEX.md openen en het relevante bestand waarnaar daar wordt verwezen. In mijn CLAUDE.md staat expliciet: “Controleer bij werk aan de UI of teksten eerst business/audience/avatar.md en business/assets/brand-guidelines.md.”

Zonder deze regel schrijft Claude teksten in “de algemene stijl van een goede website”. Met de regel schrijft het in jouw stijl, voor jouw klant en zonder jouw verboden woorden.

Regel 5. Voeg na elke fout van de agent een regel toe

Dit is de hoofdregel die CLAUDE.md actueel houdt.

Voorbeelden uit mijn eigen CLAUDE.md die na specifieke fouten zijn toegevoegd:

• “Commit nooit WIP-bestanden van iemand anders met git add . - stage bestanden op naam.”
• “Controleer vóór een push naar main git log origin/main..main --oneline - is de uitvoer niet leeg, push dan niet.”
• “Verzin geen waarden - haal ze uit .env of de code. Vooral URL’s, gebruikersnamen en tokens.”

Elk van deze regels is het spoor van een specifiek incident. Een keer heeft een agent de onafgemaakte branch van een partner gecommit. Een keer heb ik de ongepushte commits van iemand anders opgenomen. Een keer verzon een agent een URL die niet bestaat. Elke fout wordt een regel en dezelfde zelf toegebrachte wond ontstaat niet opnieuw.

Regel 6. Zet beveiligingsregels in .claude/settings.json, niet in CLAUDE.md

In CLAUDE.md kun je schrijven “raak .env niet aan”, maar dat is een verzoek; Claude kan het overtreden omdat CLAUDE.md als gebruikersbericht wordt geladen en geen wet is. Gebruik voor cruciale beveiliging .claude/settings.json, waar je bepaalde opdrachten strikt kunt blokkeren.

De blokkeerlijst die ik aan elk nieuw project toevoeg:

• rm -rf (bestanden recursief verwijderen).
• .env volledig lezen (Read .env).
• export en curl in dezelfde opdracht (een patroon om geheimen naar buiten te lekken).
• git push --force zonder expliciete goedkeuring.

Vind andere gidsen op Ailoot.

Hoe is CLAUDE.md opgebouwd in een actief bedrijf (anatomie van een bestand met 280 regels)?#

De meeste CLAUDE.md-voorbeelden online zijn technische sjablonen voor ontwikkelaars: “Gebruik TypeScript”, “Schrijf geen tests die langer zijn dan 50 regels.” Voor een ondernemer is zo’n CLAUDE.md nutteloos - de zakelijke kant ontbreekt.

Hieronder staat de structuur van mijn werkende CLAUDE.md. Ik heb de specifieke regels en paden verwijderd omdat die mijn interne bedrijfsvoering weerspiegelen. Maar de structuur en logica van de onderdelen zijn op elk project toepasbaar: vul ze in met je eigen situatie en je krijgt een werkend bestand.

1. Korte projectbeschrijving (15 regels). Wat we doen, wie de doelgroep is en welke producten we aanbieden. Geen samenvatting van de marketingwebsite, maar een samenvatting voor de agent zodat die begrijpt “waar we naartoe werken”.

2. Over mij (10 regels). Een verwijzing naar de map about-me/ - een digitale weergave van hoe ik denk. Toon, waarden, principes en verboden woorden. Wanneer Claude tekst “namens mij” schrijft, leest het eerst deze map zodat de stem overeenkomt.

3. Repositoriumstructuur (20 regels). Een boomstructuur met opmerkingen: waar de code staat, waar de bedrijfscontext te vinden is en waar plannen en terugblikken staan. Zonder deze kaart zoekt Claude elke keer blind naar bestanden.

4. Tabel “Waar vind je dingen?” (25 regels). Verwijzingen van “vraag → bestand”. Voor een makelaarskantoor kan er bijvoorbeeld staan: “hypotheekvoorwaarden nodig → business/products/mortgage.md” of “tone of voice voor posts nodig → business/assets/voice.md.” Vervang dit door je eigen bestanden. Deze tabel is de kern van CLAUDE.md. Zonder tabel moet de agent raden welk bestand het antwoord bevat. Met de tabel gaat die rechtstreeks naar de bron.

5. Belangrijke projectprincipes (40 regels, 10-15 punten). Dit onderdeel groeit langzaam en kost de meeste moeite. Elk punt is het spoor van een specifieke fout. Voor een webwinkel kunnen de regels bijvoorbeeld zijn: “hardcode nooit prijzen en levertijden”, “publiceer geen product zonder een expliciete opdracht” en “controleer de stijl aan de hand van de merkwoordenlijst voordat je een productvermelding publiceert.” Dit onderdeel is de “projectgrondwet”.

6. Operationele planning (20 regels). Een triggertabel met de koppeling “zin van de gebruiker → actie”. Bijvoorbeeld: “Als ik zeg ‘plan de week’, open ops/monthly.md en maak het bestand voor de week.” Zo wordt Claude een operationele assistent die de context van opdrachten begrijpt.

7. Tools (5 regels). Technologieën. Kort en zonder opvulling.

8. Publiceren (15 regels). Een stapsgewijs proces om wijzigingen naar productie te publiceren: welke opdrachten je in welke volgorde uitvoert en wat je controleert. Vroeger legde ik dit elke keer uit. Nu weet Claude het.

9-12. Beveiliging (35 regels). Vier afzonderlijke subonderdelen: regels voor het werken met .env, toegang tot de productiedatabase, veilige opdrachten voor demo’s (schermopnames, streams, schermafbeeldingen, zodat tokens niet per ongeluk worden blootgesteld) en regels voor het roteren van geheimen.

13. De map plans/ (10 regels). De planningsstandaard: bestandsnaam, fasenstructuur en wat er in het samenvattingsblok moet staan.

14. De map retrospectives/ (5 regels). De terugblikstandaard: sjabloon, bestandsnaam en wat erin moet staan.

15. Live databasegegevens (15 regels). Een regel om “verse gegevens” aan te geven: wanneer een bestand zegt dat cijfers actueel moeten zijn, haalt de agent ze op bij de bron in plaats van oude cijfers te gebruiken. Zo voorkom je dat Claude de cijfers van gisteren gebruikt.

16. Taal (3 regels). “Antwoord altijd in de voorkeurstaal van de gebruiker. Gebruik alleen koppeltekens, geen gedachtestreepjes.”

In totaal ongeveer 280 regels. Dat ligt boven het doel voor beknoptheid, maar maakt het bestand niet ongeldig. In dit voorbeeld bleef het nuttig; behoud ervan moet afhangen van gemeten contextgebruik en representatieve taakcontroles. Tabellen zijn niet automatisch goedkoper in tokens dan lopende tekst.

Wat doet de opdracht /init, en waarom is die niet genoeg?#

Anthropic beschrijft de opdracht als volgt in de documentatie:

Wat /init goed doet:

• Herkent tools in package.json, Cargo.toml en pyproject.toml.
• Vermeldt build- en testopdrachten.
• Herkent conventies in bestaande bestanden (.eslintrc, .prettierrc).
• Ziet bestaande Cursor-regels (.cursorrules, .cursor/rules/) en Copilot-regels en neemt relevante onderdelen over. In de modus CLAUDE_CODE_NEW_INIT=1 wordt ook AGENTS.md opgepikt.

Wat /init niet doet:

• Het weet niet wie je klant is.
• Het neemt je verboden woorden voor teksten niet op.
• Het voegt geen regels toe over fouten van de agent, omdat die nog niet zijn gemaakt.
• Het maakt geen tabel “waar vind je dingen?” voor je bedrijfsstructuur.

De juiste werkwijze is dus:

1. Voer /init uit in Claude Code

   Je krijgt een eerste versie van CLAUDE.md van 30-50 regels met tools en opdrachten. Dit is de technische basis.

2. Voeg het sjabloon uit dit artikel toe

   Gebruik het onderdeel “Een minimale CLAUDE.md in 5 minuten”. Voeg onderdelen toe voor navigatie, verwijzingen en principes.

3. Vul de velden tussen vierkante haken in

   Geef Claude de prompt “lees mijn project en vul het sjabloon in”. Als de mappen business/ en about-me/ nog niet bestaan, stelt Claude verduidelijkende vragen.

4. Doe een stresstest

   Zeg tegen Claude: “Lees mijn CLAUDE.md en vind 10 onduidelijkheden waardoor je als agent me verkeerd zou kunnen begrijpen.” Je krijgt een lijst met verbeteringen.

5. Werk vervolgens met het bestand

   Voeg na elke fout van de agent één regel toe. Na een maand heb je een levende CLAUDE.md die op jouw bedrijf is afgestemd.

Prompt voor stap vier:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md vs AGENTS.md vs MEMORY.md: wie leest wat in 2026?#

De belangrijkste vraag die nieuwe gebruikers in verwarring brengt, is: leest Claude Code AGENTS.md? Vóór september 2026 was het antwoord “nee”: de documentatie van Anthropic adviseerde een CLAUDE.md te maken die AGENTS.md importeert. Sinds versie 2.1.277 (uitgebracht op 18 september 2026) leest Claude Code AGENTS.md zelf, maar alleen als er in de werkmap of daarboven geen CLAUDE.md, .claude/CLAUDE.md of CLAUDE.local.md staat.

Als het project een CLAUDE.md heeft, leest Claude Code standaard alleen dat bestand en slaat het AGENTS.md over. Je kunt dit wijzigen in /config, onder Project instructions: de instelling claude-md-and-agents-md zorgt er bijvoorbeeld voor dat beide bestanden worden gelezen. Een andere manier werkt in elke versie: voeg een import toe aan CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

De syntaxis @filename importeert een ander bestand. Claude leest het en laadt het samen met CLAUDE.md in de context. De import zorgt er niet voor dat het bestand twee keer wordt gelezen, zelfs niet wanneer Claude Code AGENTS.md zelfstandig kan lezen.

Wanneer heb je AGENTS.md nodig? Als je Claude Code samen gebruikt met Codex CLI, Cursor of Copilot, maak dan een AGENTS.md als enige bron van waarheid, zet @AGENTS.md in CLAUDE.md en voeg daarbovenop eventuele Claude-specifieke regels toe. Als zulke regels er niet zijn, hoef je geen CLAUDE.md te maken: sinds versie 2.1.277 leest Claude Code AGENTS.md zelf. Werk je alleen met Claude Code, dan heb je AGENTS.md niet nodig; gebruik alleen één CLAUDE.md. Zie voor alle opties stap voor stap de gids voor het gebruik van AGENTS.md en CLAUDE.md in één project.

Wat is MEMORY.md? Sinds een recente update houdt Claude Code automatisch notities over jou bij in ~/.claude/projects/<project-name>/memory/MEMORY.md. Daarin staan gesprekgewoonten (“de gebruiker geeft de voorkeur aan korte antwoorden”), terugkerende verzoeken (“emoji’s in code verboden”) en observaties over je gedrag (“werkt op macOS, gebruikt zsh”).

Dit is een afzonderlijk geheugensysteem, geen CLAUDE.md. Je schrijft het niet zelf; Claude doet dat op basis van je gesprekken. Staat er iets in MEMORY.md dat een regel moet worden, verplaats het dan naar CLAUDE.md. Bevat het iets onnodigs of onjuists, dan kun je het handmatig verwijderen; het is een tekstbestand.

Wat is een bruikbare omvang voor CLAUDE.md, en hoe beoordeel je een lang bestand?#

In elk Claude Code-venster worden verschillende lagen in de context geladen: de systeemprompt van Anthropic (naar schatting tienduizenden tokens), je CLAUDE.md, bestanden die met @ zijn geïmporteerd, MEMORY.md, de huidige chatgeschiedenis en de inhoud van bestanden die Claude opent. Dit alles moet in het contextvenster van het model passen (200K tokens voor Sonnet, 1M voor Opus).

Hoe groter CLAUDE.md wordt, hoe minder ruimte er overblijft voor het huidige werk. Een bestand van 1,000 regels telt ongeveer 8,000 tokens en wordt in elke sessie opnieuw geladen. Bij een Pro-abonnement (naar mijn ervaring ongeveer 10-12 “zware” prompts per dag) vermindert dat je capaciteit met een kwart.

Kosten zijn slechts één aandachtspunt. Naleving kan afnemen wanneer instructies lang, irrelevant of tegenstrijdig zijn; er bestaat geen universeel aantal instructies dat betrouwbaar wordt gevolgd. Test enkele representatieve taken die de cruciale regels aanspreken, leg fouten vast en vergelijk het gedrag na een gerichte wijziging.

Dit is dus de vuistregel voor de omvang:

• 80-120 regels - een handig startbereik voor een beknopte projectkaart, geen gegarandeerde nalevingsscore.
• 150-200 regels - een nuttige aanleiding om relevantie te beoordelen en gedetailleerde procedures naar gekoppelde bestanden te verplaatsen.
• 200-300 regels - bekijk de hoeveelheid tokens, duplicaten en taakresultaten; het bedrijfsvoorbeeld van 280 regels hierboven kan nog steeds goed werken.
• 400+ regels - een sterke reden voor gerichte beoordeling, geen bewijs dat het bestand onbruikbaar is. Behoud essentiële grenzen en verplaats details pas nadat je hebt gecontroleerd dat verwijzingen en regels blijven werken.

Het aantal regels alleen bewijst geen succes of mislukking. Herhaal na een wijziging dezelfde representatieve taken en controleer de belangrijke regels, in plaats van een verzonnen nalevingspercentage toe te kennen.

Anthropic geeft in de documentatie een directe test:

Pas dit op elke regel toe. Als het antwoord “het zou het nog steeds goed doen” is, verwijder de regel dan. CLAUDE.md is niet bedoeld voor documentatie, de geschiedenis van beslissingen of filosofie. Het bevat alleen de regels die de agent nodig heeft om geen fouten te maken.

Welke 7 fouten maken CLAUDE.md nutteloos?#

Fout 1. “Wees een goede ingenieur”

De meest voorkomende fout. Mensen schrijven algemene wensen in CLAUDE.md: “schrijf schone code”, “gebruik best practices”, “denk als een senior engineer”.

Deze woorden betekenen niets. Claude schrijft in algemene zin al “schone code”. Deze regels nemen context in zonder een beslissing te beïnvloeden.

Vervang “schrijf schone code” door “gebruik inspringing van 2 spaties”, “gebruik geen any in TypeScript” of “functies mogen niet langer zijn dan 30 regels”. Specifiek en controleerbaar.

Fout 2. Herhalen wat Claude al weet

Beschrijvingen van standaardconventies van programmeertalen (“in JavaScript zijn functies first-class citizens”, “TypeScript heeft statische typering”). Uitleg over de werking van npm, git of docker.

Claude heeft dit allemaal tijdens de training geleerd. Het herhalen in CLAUDE.md voegt niets toe; het kost alleen context.

Fout 3. Lange stapsgewijze instructies in CLAUDE.md

Lange instructies over “hoe je het project uitrolt”, “hoe je een databasemigratie schrijft” of “hoe je een nieuwe component instelt”. Tientallen regels met stappen.

Dit is niet de plek voor lange stapsgewijze instructies. Het bestand is bedoeld voor regels van één regel. Zet lange instructies in skills/ (een afzonderlijk Claude Code-mechanisme dat op verzoek wordt geladen) of in docs/. Gebruik in CLAUDE.md een verwijzing van één regel: “Open docs/migrations.md wanneer je een nieuwe migratie maakt.”

Fout 4. Regels die al door een automatische codeanalysator worden gecontroleerd

“Gebruik puntkomma’s”, “laat geen ongebruikte imports staan”, “gebruik geen var.” ESLint, Prettier en Biome vangen dit allemaal op - het zijn linters (tools die code automatisch controleren).

Een linter is deterministisch: hij wordt uitgevoerd, vindt een fout en corrigeert die. Een regel in CLAUDE.md is probabilistisch; de agent kan hem vergeten. Je hoeft dit niet te dupliceren - de linter instellen is eenvoudiger.

Fout 5. Geheimen in CLAUDE.md

Ik heb wachtwoorden van testaccounts, sandbox-API-tokens en links naar geauthenticeerde beheerderspanelen gezien. Dat stond allemaal in een bestand dat in git was vastgelegd en in de context van het model van Anthropic werd geladen.

Nooit doen. Geheimen horen in .env, dat in .gitignore staat. Hooguit hoeft CLAUDE.md te zeggen: “Lees .env niet helemaal; gebruik grep voor een specifieke variabele.”

Fout 6. Een verzamelbestand van 500+ regels dat al zes maanden niet is opgeschoond

CLAUDE.md is gegroeid, dupliceert de helft van docs/, spreekt zichzelf op verschillende plaatsen tegen en niemand weet meer wat erin staat. De agent begint het grootste deel te negeren. Het team klaagt dat “Claude instructies niet opvolgt” en voegt meer regels toe, waardoor het erger wordt.

Tekenen dat een CLAUDE.md is verwaarloosd: meer dan 300 regels, herhaalde regels in verschillende onderdelen, verouderde links naar bestanden die niet meer bestaan en “historische” notities zoals “in 2024 besloten we dit zo te doen, maar later veranderden we van gedachten.”

De oplossing: vraag Claude elke twee weken het bestand na te kijken met de test van Anthropic: “Zou de agent een fout maken als deze regel werd verwijderd?” Verwijder alles waarvoor het antwoord “nee” is.

Fout 7. CLAUDE.md maken en vergeten

Dit is het tegenovergestelde van de vorige fout. Het bestand is één keer opgesteld, twee maanden geleden, en sindsdien niet meer aangeraakt. Ondertussen zijn de tools veranderd, zijn er nieuwe mappen bijgekomen en zijn er nieuwe fouten van agents aan het licht gekomen. CLAUDE.md weet daar niets van omdat niemand het heeft bijgewerkt.

Een duidelijk teken: je herhaalt dezelfde instructie in elke sessie. “Doe X niet”, “raak Y niet aan”, “onthoud Z”. Als je dit meer dan twee keer hebt herhaald, hoort de regel in CLAUDE.md en niet in je hoofd.

Hoe maak je CLAUDE.md zelflerend met een regel om het “aan het einde van de sessie bij te werken”?#

Mijn CLAUDE.md bevat een kort onderdeel:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Nadat dit onderdeel aan CLAUDE.md was toegevoegd, begon Claude aan het einde van elke sessie te vragen: “Was er iets nieuws dat het waard is om vast te leggen?” Zo ja, dan stelde het een conceptregel voor, verduidelijkte ik die en werd er een bestand gemaakt.

Na twee maanden op deze manier werken heb ik meer dan twee dozijn bestanden in about-me/feedback/ - regels die uit specifieke fouten zijn geleerd. Elk bestand is één pagina in het formaat Regel → Waarom → Hoe toepassen. De map werd een “tweede geheugen” waarin mijn persoonlijke voorkeuren en taboes worden vastgelegd.

Fouten worden niet herhaald omdat ze in regels veranderen, en de regels stapelen zich op en versterken elkaar. Na zes maanden kent Claude mijn project beter dan ik het zelf nog weet na een pauze van een maand.

Hoe voeg je juridische regels, marketing en bedrijfsvoering toe aan CLAUDE.md?#

Voor de meeste teams is CLAUDE.md een puur technisch document: tools, buildopdrachten, programmeerconventies. Dat is nuttig, maar slechts een derde van de waarde.

Als een ondernemer CLAUDE.md bijhoudt, is het zinvol er zakelijke onderdelen aan toe te voegen. Drie zijn het belangrijkst:

Juridische regels (voor gereguleerde markten)

Als je teksten publiceert in een gereguleerde sector (financiën, geneeskunde, geneesmiddelenreclame, kinderproducten), hebben verboden woorden juridische betekenis en horen ze als expliciete regels in CLAUDE.md. Niet in iemands hoofd, niet op een screenshot van een editor - maar in een bestand dat de agent in elke sessie ziet.

Voorbeeld voor een fintechproject zonder bankvergunning:

Redactionele opmerking: Hieronder zie je de opmaak van een interne regel voor een specifiek project. Dit is geen universele toestemming om de genoemde termen te gebruiken: of een bewering aanvaardbaar is, hangt af van het toepasselijke recht en de status van het bedrijf.

🚨 KRITIEK - financiële formuleringen zijn verboden. Gebruik in materiaal voor klanten niet de termen “deposito”, “gegarandeerd rendement” of “beleggingsproduct”. Gebruik in plaats daarvan “spaarrekening”, “verwacht rendement” en “product met variabele rente”. De reden hiervoor zijn de wettelijke eisen die voor dit project gelden voor reclame voor financiële diensten.

Dit blok in CLAUDE.md doet iets eenvoudigs: elke keer dat je Claude vraagt om tekst voor klanten te schrijven, controleert de agent die aan de hand van deze verboden. Zonder deze regel duiken verboden woorden in elke derde campagne op. Met de regel vergeet je dat ze bestaan.

Dezelfde aanpak werkt voor:

• Medische projecten (geen beweringen dat iets “behandelt” of “geneest”).
• Geneesmiddelenreclame (geen beweringen over “meest effectief”; verplichte waarschuwingen toevoegen).
• Elke gereguleerde sector met eigen reclameregels.

Marketingstijl en tekstopmaak

Als je regelmatig teksten publiceert (sociale media, nieuwsbrieven, websites), is het verstandig de opmaak in één alinea in CLAUDE.md vast te leggen. Hier is een voorbeeld van wat een influencer of bureau met een berichtenkanaal zou kunnen schrijven:

Raadpleeg style/posts.md wanneer je kanaalposts schrijft. Gebruik de opmaakmarkeringen die het kanaal toestaat en vermijd “gevaarlijke” speciale tekens. Sluit af met een CTA met een UTM-tag volgens deze conventie: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude schreef vroeger posts in “de algemene stijl van een marketingwebsite”. Nu volgt het je opmaak, gebruikt het je UTM’s en verraadt de tekst niet dat die door AI is geschreven.

Operationele gewoonten

Triggertabellen. Wanneer je een specifieke zin zegt, weet de agent welke bestanden het moet openen en welke acties het moet uitvoeren. Hier is een voorbeeld voor een team dat per week plant:

“Plan de week” → open ops/monthly.md, maak YYYY-WNN.md in dezelfde map en verplaats de taken uit ops/backlog.md naar de juiste dagen. “Wat staat er op de backlog?” → lees ops/backlog.md en toon de inhoud als lijst. “Sluit de week af” → vul het onderdeel “Weeksamenvatting” in het bestand van de huidige week in.

Met zulke tabellen verandert Claude van een “hulpje dat code schrijft” in een “operator” die de routine van je bedrijf kent. Elke maandag zeg ik “laten we de week plannen”, en Claude opent de juiste bestanden, leest de maanddoelen en stelt voor hoe we de taken kunnen opdelen.

Hoe controleer je je CLAUDE.md in 5 minuten met een checklist van 12 punten?#

1. Omvang. Is het beknopt, met ongeveer 200 regels als beoordelingsdoel in plaats van een harde slaag-/faalgrens?
2. Naam. Heet het precies CLAUDE.md met hoofdletters, en niet claude.md?
3. Locatie. Staat het in de hoofdmap van het project of in ./.claude/CLAUDE.md?
4. Projectbeschrijving. Maken de eerste 5 regels duidelijk wat het project is en voor wie het bedoeld is?
5. Tools. Zijn de technologieën expliciet en zonder opvulling vermeld?
6. Structuur. Staat er een diagram van de repository met toelichting in?
7. Verwijzingen. Is er een tabel “vraag → bestand” die laat zien waar je antwoorden kunt vinden?
8. Principes. Is er een onderdeel met regels die beginnen met “nooit” en “altijd”?
9. Specificiteit. Is elke regel controleerbaar? (“Gebruik 2 spaties”, niet “schrijf mooi”.)
10. Zelf bijwerken. Is er een regel om “aan het einde van de sessie te controleren wat je moet toevoegen”?
11. Terugblik. Is er een regel om “de samenvatting van de sessie in retrospectives/ vast te leggen”?
12. Beveiliging. Staan cruciale verboden (.env, rm -rf) ook in .claude/settings.json?

Als je meer dan vijf keer “nee” antwoordt, open dan Claude en geef het deze prompt:

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

Beknopt genoeg voor de taak; beoordeel rond 200 regels zonder dat als harde bovengrens te behandelen

Project description in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

Wat gebruik je na CLAUDE.md: Plan Mode, Skills of sub-agents?#

CLAUDE.md is de basis. Zodra het werkt, kun je drie Claude Code-mechanismen toevoegen die elkaar versterken.

Plan Mode. Een modus waarin Claude eerst een wijzigingsplan opstelt, op je goedkeuring wacht en pas daarna begint. Activeer de modus met Shift+Tab of de opdracht /plan. Dit pakt het grootste pijnpunt van vibe coding aan: “Ik vroeg Claude om één ding te repareren, en het herschreef de helft van het project.” Dat gebeurt niet in Plan Mode - je ziet het plan voordat de agent bestanden aanraakt.

Skills. Afzonderlijke .md-bestanden in de map .claude/skills/ met kennis voor een specifiek type taak. Een Skill over “hoe je een databasemigratie schrijft” bevat bijvoorbeeld een specifieke procedure, een sjabloon en voorbeelden. Die kennis staat niet in CLAUDE.md omdat ze te uitgebreid is. Wanneer Claude een taak tegenkomt zoals “schrijf een migratie”, laadt het de relevante Skill en volgt die.

Sub-agents. Als een taak veel context nodig heeft (bijvoorbeeld het beoordelen van een grote feature), kan Claude een aparte sub-agent starten met een eigen, schone context. De sub-agent voert het werk uit en geeft het resultaat terug zonder de context van je hoofdchat te vervuilen.

Alle drie de mechanismen gebruiken CLAUDE.md als startpunt: ze lezen het aan het begin van hun werk om de projectcontext te begrijpen. Daarom werken deze functies ook slecht zonder een CLAUDE.md die je bijhoudt. Eerst de basis, dan de lagen erbovenop.

Volgende stap. Maak een bestand CLAUDE.md in de hoofdmap van het project, kopieer het sjabloon aan het begin van dit artikel en vul de velden tussen vierkante haken in met behulp van de hulpprompt. Werk vervolgens met het bestand: maak van elke fout van de agent een nieuwe regel. Na twee of drie weken is CLAUDE.md niet langer “een document dat we schreven en vergaten”, maar iets wat Claude in elke sessie raadpleegt.

Wil je een compleet raamwerk rond CLAUDE.md bouwen - een map business/ voor een tweede brein, een map about-me/ voor een digitale weergave van jezelf, basis-Skills en een geconfigureerde Plan Mode - gebruik dan de stappen en voorbeelden in dit artikel. Ailoot-gidsen.

Ga verder met Ailoot.