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.

Het probleem is niet Claude Code. Het probleem is dat Claude Code 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 je context opbouwt over tijd. Met voorbeelden uit mijn .NET codebase, maar de aanpak werkt voor elke stack.

Zonder context is Claude Code een overenthousiaste nieuwe collega. CLAUDE.md checklist met project, commands en conventions.

Wat is context?

Context is alles wat de AI 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? 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, een spec is per taak.

Gebruik je Cursor of Copilot? Dan heb je .cursorrules of copilot-instructions.md in plaats van CLAUDE.md. Het principe is hetzelfde.

Claude Code onthoudt ook dingen binnen een sessie, maar dat is vluchtig. Bij lange sessies wordt het gesprek samengevat en gaan details verloren. Tussen sessies is alles weg, tenzij het in een bestand staat.

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.

In mijn artikel over AI-adoptie noem ik dit De Fundering: de kaders waarbinnen de AI werkt.

De gouden regel: kort, universeel, actueel

Kort

<100 regels werkt beter dan 500. Anthropic’s eigen teams gebruiken ~100 regels. Hoe langer, hoe meer Claude Code negeert.

Universeel

Elke regel gaat in elke sessie mee. Zet er alleen in wat altijd relevant is. Specifieke instructies horen in rules/ of in een spec.

Actueel

Een verouderde CLAUDE.md is erger dan geen CLAUDE.md. Verouderde regels leiden tot verkeerde output. Je merkt het direct.

Waarom dit ertoe doet: Claude Code heeft een beperkte ‘attention span’. Als je hem 200 regels voert over CSS-naamgeving terwijl hij een SQL-bug moet oplossen, is dat ruis die de kwaliteit van de output verlaagt. Regels die niet relevant zijn voor de huidige taak, kosten aandacht die je liever besteedt aan het echte probleem.

Vuistregel: vraag bij elke regel “is dit altijd relevant?” Zo nee, verplaats het naar een rule-bestand of schrap het.

Hoe bouw je het op?

Stap 0: /init

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. Het is niet perfect, maar het is een startpunt dat je in 5 minuten kunt reviewen en aanscherpen.

Na /init: review en aanscherpen

/init geeft je een startpunt. Het is gewoon een markdown bestand, geen vast formaat. Zet er minimaal in: je tech stack, je build/test commands en je belangrijkste architectuurkeuzes. Review het en schrap wat niet klopt:

## Project
.NET 10 solution, multi-tenant SaaS platform

## Commands
dotnet build Invullen.sln
dotnet test

## Architecture
4 microservices, 1 frontend (MVC), 1 marketing website
Communication via REST APIs between services
Authentication: OpenID Connect with SSO towards Entra ID
Authorization: JWT bearer tokens, role-based access

Week 1-2: fouten worden regels

Elke keer dat de AI iets fout doet dat je vaker verwacht, voeg je een regel toe:

  • AI gebruikt raw SQL → voeg toe: “gebruik altijd de repository-laag”
  • AI vergeet [Authorize] → voeg toe: “gebruik [Authorize] op alle protected endpoints”
  • AI genereert Console.WriteLine → voeg toe: “log via ILogger, nooit Console.WriteLine”

Dat is de feedbackloop: elke correctie die vaker terugkomt, wordt een regel.

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.

Week 3-4: splitsen en opschonen

Je CLAUDE.md groeit en wordt te groot. Tijd om te splitsen:

Blijft in CLAUDE.md

Project structuur, build/test commands, top 10 conventies. Universeel, altijd relevant.

Verhuist naar .claude/rules/

security.md, ef-data-types.md, frontend-conventions.md, testing.md, exception-logging.md. Wordt alleen geladen als relevant.

Rules worden alleen geladen als Claude Code werkt in bestanden die matchen. Minder ruis, scherpere output.

Maandelijks: opschonen

  • Verwijder regels over dingen die elk model sowieso goed doet (bijv. “gebruik geen goto”)
  • Houd regels over project-specifieke keuzes die het model niet kan weten (bijv. “Newtonsoft.Json, niet System.Text.Json”)
  • Update regels die niet meer kloppen (framework geüpdatet, patronen veranderd)
  • Verplaats regels die te specifiek zijn naar .claude/rules/ of een spec
  • Controleer of rules-bestanden nog actueel zijn
  • Check bestandsnamen en verwijzingen: na refactoring kloppen paden vaak niet meer

Een context-file is geen document dat je één keer schrijft. Het is een levend bestand dat meegroeit met je codebase.

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.

CLAUDE.md vs hooks: de 80/100 regel

Claude Code volgt CLAUDE.md ongeveer 80% van de tijd. 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)

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/await

Als 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.

Veelgemaakte fouten

  • Te lange CLAUDE.md: 500+ regels, Claude Code negeert de helft. Schrap of splits.
  • Code-snippets in CLAUDE.md: verouderen snel. Verwijs naar bestandspaden in plaats van code te kopiëren.
  • Nooit opschonen: verouderde of tegenstrijdige regels leiden tot onvoorspelbare output.
  • Alles in CLAUDE.md: specifieke regels horen in rules/ of een spec.
  • Geen feedbackloop: als je niet bijwerkt na terugkerende correcties, blijf je dezelfde bijsturing doen.

Onthoud

  • CLAUDE.md < 100 regels. Alles wat niet altijd relevant is, hoort ergens anders.
  • Regels zijn advies, geen garantie. Review blijft nodig.
  • Context bouw je niet in een dag. Het is een feedbackloop: elke correctie die vaker terugkomt, wordt een regel.

Hoeveel regels heeft jouw CLAUDE.md? En wanneer heb je hem voor het laatst opgeschoond?

Hoe bouw je samen met je team gedeelde context op?

In Van AI-experimenten naar AI-adoptie beschrijf ik hoe je samen met je team context opzet en iedereen erbij betrekt.

Lees ook: Hoe Claude Code mijn .NET development-workflow versnelt