Zonder context is Claude Code een overenthousiaste nieuwe collega die je codebase nog niet kent. Dit is de Claude Code-uitwerking: hoe CLAUDE.md wordt geladen, wanneer je een hook gebruikt in plaats van een regel, en hoe dat er in mijn eigen codebase uitziet.
Voor wie? Developers die met Claude Code werken (of willen starten) en merken dat de output beter kan.
Dit artikel is de Claude Code-uitwerking. Het toolbrede verhaal (AGENTS.md, CLAUDE.md, copilot-instructions.md, .cursorrules) staat in welke instructies geef je een AI-agent mee in je repo?
Je vraagt om een simpele bugfix. Claude Code begint te typen en voor je het weet zie je een lijst van 12 gewijzigde bestanden voorbijkomen. Vijf nieuwe interfaces, een herschreven BaseController en een refactor die je helemaal niet wilde.
Eén /undo en de code is terug. Maar je bent wel je momentum kwijt. Je moet nu alsnog handmatig uitleggen wat de bedoeling was.
Aan Claude Code ligt het niet. Die opereert in een vacuüm. Zonder goede context is zelfs de slimste AI een overenthousiaste nieuwe collega die je codebase nog niet kent.
De meeste guides vertellen je wát je in CLAUDE.md moet zetten. Dit artikel laat zien hoe dat er in mijn eigen .NET-codebase uitziet: de laadmechanica, de grens tussen CLAUDE.md en hooks, en een concreet voorbeeld.
Wat is context in Claude Code?
Context is alles wat Claude Code helpt om betere output te leveren:
| Wat | Doel en gebruik | Houdbaarheid |
|---|---|---|
| CLAUDE.md | De “grondwet” van je project. Tech-stack keuzes, naamgevingsconventies, veelgebruikte commands. | Permanent. Groeit in het begin snel, daarna stabiliseert het. Regels die te specifiek worden verplaats je naar rules/. |
| .claude/rules/ | Modulaire regels. Bijvoorbeeld: ef-data-types.md wordt alleen geladen als je aan Entity Framework code werkt. Bespaart token-ruimte. |
Permanent. Per domein, wordt geladen wanneer nodig. |
| Commands / skills / agents | Herbruikbare workflows en snelkoppelingen. In plaats van 10 stappen uit te leggen: /skill-naam of /command-naam. |
Permanent. Worden on demand aangeroepen. |
| Specs / plannen | De blauwdruk voor een specifieke feature. Wat moet er gebeuren in story #402? Zie spec-driven development. | Per feature. Kan daarna weg of naar het archief. |
| Je prompt | De vraag die je nu stelt. “Fix de bug in regel 10.” | Vluchtig. Alleen relevant voor de huidige sessie. |
Elke laag wordt specifieker. CLAUDE.md is breed. Rules zijn per domein en een spec hoort bij één taak.
Belangrijk: CLAUDE.md wordt altijd geladen bij het opstarten van een sessie. Rules worden automatisch meegeladen als je werkt in bestanden die erbij passen. Commands en agents worden geladen als je ze aanroept. Skills worden automatisch geladen als ze relevant zijn, of handmatig met /skill-naam.
Dat maakt CLAUDE.md je belangrijkste bestand, en verklaart waarom het kort moet zijn: alles wat erin staat kost elke sessie token-ruimte.
Waarom je CLAUDE.md kort en actueel houdt, en hoe je 'm in het algemeen opbouwt, staat in welke instructies geef je een AI-agent mee in je repo?. Hieronder de Claude Code-specifieke kant: hoe je start, en waar de grens ligt tussen CLAUDE.md en hooks. En werk je met meerdere agents naast elkaar: zet de gedeelde instructies in AGENTS.md en laat CLAUDE.md daarnaar verwijzen. Dan kunnen Codex en GitHub Copilot met dezelfde afspraken werken.
Hoe begin je met CLAUDE.md?
Het snelste startpunt: draai claude /init in je project root. Claude Code analyseert je codebase en genereert een CLAUDE.md met project-structuur, tech stack, build commands en basisconventies. Perfect is het niet. Wel een startpunt dat je in 5 minuten kunt reviewen en aanscherpen.
Daarna groeit CLAUDE.md mee. Elke keer dat Claude Code iets fout doet dat je vaker verwacht, wordt dat een regel. Dit specificeren, reviewen en bijsturen is precies het ritme van mijn dagelijkse .NET-workflow met Claude Code.
Tip: je hoeft de regel niet zelf te schrijven. Mijn workflow: als Claude Code een fout maakt, herstel ik het en prompt direct: “Voeg een regel toe aan @.claude/rules/testing.md dat we altijd Moq gebruiken voor mocking en nooit NSubstitute.” Claude Code schrijft de regel, ik review het in de console en doe een double check bij de PR.
CLAUDE.md vs hooks: de 80/100 regel
In mijn ervaring volgt Claude Code CLAUDE.md ongeveer 80% van de tijd; meten deed ik het niet. Hooks worden 100% afgedwongen.
CLAUDE.md is advies: Claude Code kan ervan afwijken. Ga er niet vanuit dat regels bindend zijn. Review blijft nodig. Hooks zijn iets anders: dat zijn scripts (pre-commit hooks, CI-checks) die buiten Claude Code om draaien en altijd worden afgedwongen.
| CLAUDE.md | Hooks | |
|---|---|---|
| Naleving | ~80%* | 100% |
| Gebruik voor | Conventies, richtlijnen, patronen | Dingen die NOOIT fout mogen gaan |
| Voorbeeld | “Gebruik geen magic strings” | Geen secrets in commits (gitleaks) |
* Eigen observatie uit dagelijks gebruik, geen gemeten cijfer.
Mijn codebase
Mijn codebase: 4 microservices, 1 frontend, 1 website. Multi-tenant, SSO, AI-gestuurde vragenlijsten.
CLAUDE.md (~80 regels)
- Repository structuur
- Git workflow (spec → worktree → implementatie → PR)
- Beschikbare agents
- Task sizing (micro/standard/full)
- Top 10 conventies
7 rules-bestanden
.claude/rules/
security.md :[Authorize], AccountId, API keys, multi-tenancy
ef-data-types.md :String constants, geen enums in EF
json-serialization.md :Newtonsoft.Json only
exception-logging.md :ILogger, re-throw rules
frontend-conventions.md :Admin theme, Font Awesome
testing.md :NUnit, Moq, Arrange-Act-Assert
csharp-style.md :Primary constructors, braces, async/awaitAls Claude Code aan een frontend-taak werkt, laadt hij alleen frontend-conventions.md, csharp-style.md en security.md. Niet de EF- of JSON-serialization regels. Minder ruis, scherpere output.
Tip voor gevorderden: je kunt ook een extra CLAUDE.md per subfolder plaatsen. Claude laadt die automatisch als hij in die folder werkt. Handig voor monorepos of microservices: elke service krijgt zijn eigen instructies bovenop de root CLAUDE.md. Hoe je in zo'n monorepo één agent-sessie per user story over alle services laat werken, beschreef ik apart.
Hoeveel regels heeft jouw CLAUDE.md? En wanneer heb je hem voor het laatst opgeschoond?
CLAUDE.md is nooit af: het groeit mee met je codebase. Het toolneutrale principe hierachter, en hoe dat vertaalt naar AGENTS.md, copilot-instructions.md of .cursorrules, staat in welke instructies geef je een AI-agent mee in je repo?
