Het probleem

Je opent Claude Code in je .NET-project. Je vraagt: “Voeg een endpoint toe voor het ophalen van gebruikersnotificaties.”

Claude Code gaat aan de slag. Maar het maakt een controller aan terwijl jullie Minimal API’s gebruiken. Het zet de connectionstring hardcoded neer terwijl jullie alles via appsettings.json doen. Het maakt een eigen NotificationService aan terwijl jullie al een generieke IEventHandler<T> hebben.

Technisch werkt het. Maar het past niet bij je project.

Je corrigeert. Claude Code past aan. Volgende vraag, zelfde verhaal. Het weet niet hoe jullie dingen doen, want dat staat nergens beschreven — niet voor een AI althans.

Zoals John Lindquist (egghead.io) het treffend zegt: “Every time an AI starts, it has no memory, no idea of what’s going on in your application.” En dan proberen developers het bij te sturen met regels en correcties, maar ze vergeten het belangrijkste: de AI vertellen hoe hun applicatie in elkaar zit.

Dit is het frustrerende aan AI-tools zonder context. Ze zijn slim genoeg om code te schrijven, maar ze kennen je project niet. Elke sessie begin je weer bij nul.

De oplossing: CLAUDE.md

CLAUDE.md is een Markdown-bestand in je project dat Claude Code automatisch inleest bij elke sessie. Het is het geheugen van je AI-assistent.

Geen plugin, geen install, geen setup. Gewoon een .md-bestand met daarin de dingen die Claude Code moet weten over jouw project.

Je maakt het aan met één commando:

claude
/init

Claude Code scant je project en genereert een eerste versie. Maar de echte waarde zit in wat jij er daarna aan toevoegt. Zie /init als een startpunt — niet als het eindresultaat.

Wat zet je erin?

Geen roman. Geen volledige documentatie. Alleen de dingen die je anders steeds opnieuw zou moeten uitleggen.

Projectstructuur en conventies:

## Project
- ASP.NET Core 8 Web API met Minimal API's (geen controllers)
- Entity Framework Core met SQL Server
- Mediator pattern via MediatR
- Alle configuratie via appsettings.json, nooit hardcoded

Patronen die jullie gebruiken:

## Conventies
- Endpoints staan in /Endpoints, gegroepeerd per domein
- Services implementeren altijd een interface
- Validation via FluentValidation, niet via data annotations
- Exceptions worden centraal afgehandeld via middleware

Dingen die Claude Code niet moet doen:

## Niet doen
- Geen controllers aanmaken, we gebruiken Minimal API's
- Geen Console.WriteLine voor logging, gebruik ILogger<T>
- Geen hardcoded connectionstrings
- Geen business logic in endpoints

Minstens zo belangrijk: wat je er niet in zet. Dingen die Claude al weet door je code te lezen hoeven er niet in. Standaard C#-conventies ook niet. En stijlregels die een linter kan afdwingen? Gebruik een linter, geen CLAUDE.md. Hoe minder ruis, hoe beter Claude de regels volgt die er wél toe doen.

Het verschil

Zonder CLAUDE.md vraag je om een endpoint en krijg je dit:

[ApiController]
[Route("api/[controller]")]
public class NotificationsController : ControllerBase
{
    private readonly string _connectionString = "Server=localhost;...";

    [HttpGet]
    public async Task<IActionResult> GetNotifications() { ... }
}

Met CLAUDE.md vraag je om hetzelfde endpoint en krijg je dit:

app.MapGet("/api/notifications", async (IMediator mediator) =>
{
    var result = await mediator.Send(new GetNotificationsQuery());
    return Results.Ok(result);
})
.WithName("GetNotifications")
.WithTags("Notifications");

Geen controller. Geen hardcoded strings. Wel MediatR, wel Minimal API’s — precies zoals jullie het doen. Alsof een collega het geschreven heeft die weet hoe jullie werken.

Hetzelfde geldt voor refactoring, debugging, documentatie — alles wat Claude Code doet wordt beter als het weet hoe jouw project in elkaar zit.

Team vs. persoonlijk

CLAUDE.md is niet één bestand. Het is een gelaagd systeem:

CLAUDE.md in je project root is voor het hele team. Check het in via git, zodat iedereen dezelfde afspraken deelt. Dit is waar je architectuurkeuzes, conventies en “niet doen”-regels neerzet.

CLAUDE.local.md is voor jou alleen. Dit bestand wordt automatisch aan .gitignore toegevoegd. Hier zet je je persoonlijke voorkeuren: jouw sandbox-URLs, jouw testdata, jouw manier van werken.

~/.claude/CLAUDE.md in je home directory geldt voor al je projecten. Handig voor persoonlijke stijlvoorkeuren die je overal wilt.

Zo deel je teamafspraken via git, zonder dat je persoonlijke setup in de weg zit. En voor grotere projecten kun je regels zelfs opsplitsen in .claude/rules/ — aparte bestanden per onderwerp zoals code-style.md, testing.md of security.md, die allemaal automatisch worden ingeladen.

Claude leert ook zelf

CLAUDE.md is niet alleen iets dat jij schrijft. Claude Code heeft ook auto memory: het slaat zelf notities op over patronen die het ontdekt, debugging-inzichten en architectuurkeuzes. Deze worden bewaard in ~/.claude/projects/<project>/memory/ en automatisch geladen bij elke sessie.

En er is een handige snelkoppeling: begin een regel met # tijdens een sessie (bijvoorbeeld # gebruik altijd MUI componenten) en Claude slaat het direct op als geheugenregel.

Maar het krachtigste is de feedback-loop. Als je Claude corrigeert, kun je zeggen: “Voeg dit toe aan CLAUDE.md zodat je het onthoudt.” Claude schrijft de regel dan zelf. Boris Cherny, de maker van Claude Code, raadt precies dit aan: “Invest in your CLAUDE.md file. After every correction, update it so you don’t make that mistake again. Claude is effective at writing rules for itself.”

Zo groeit je CLAUDE.md organisch mee met je project — zonder dat je er een documentatieproject van hoeft te maken.

Tips om het scherp te houden

Houd het kort. CLAUDE.md is geen wiki. Richt op maximaal 300 regels. Hoe langer het bestand, hoe meer Claude belangrijke regels over het hoofd ziet. De officiële documentatie waarschuwt hier expliciet voor: als je CLAUDE.md te lang wordt, negeert Claude de helft. Vuistregel: als Claude iets al goed doet zonder de instructie, verwijder die instructie.

Werk het bij als je iets corrigeert. Als je Claude Code voor de tweede keer moet vertellen dat jullie geen controllers gebruiken, zet het dan in CLAUDE.md — of vraag Claude het zelf toe te voegen. Dat hoef je het daarna nooit meer te zeggen.

Wees specifiek. “We volgen clean architecture” zegt niks. “Services staan in /Application/Services en implementeren altijd een interface uit /Application/Interfaces” zegt alles.

Gebruik imports voor grote projecten. CLAUDE.md ondersteunt @pad/naar/bestand om andere bestanden in te laden. Zo houd je het hoofdbestand lean zonder context te verliezen:

Zie @README.md voor projectoverzicht en @docs/architecture.md voor architectuur.

Zelf beginnen?

Open je terminal in je project:

claude
/init

Kijk wat Claude Code genereert, pas het aan met jullie eigen conventies, en merk het verschil bij je volgende vraag.

Ja, meer context betekent meer tokens — en dat kost iets meer. Maar de tijd die je bespaart door niet steeds dezelfde correcties te doen weegt daar ruimschoots tegenop.

Je AI is zo goed als de context die je het geeft. CLAUDE.md is die context.