CLAUDE.md: projectgeheugen voor Claude Code

Elke sessie met Claude Code begint met een leeg contextvenster. Claude weet dan niet welke codestandaarden je hanteert of met welke opdracht je de tests draait. Zonder voorbereiding leg je steeds dezelfde dingen opnieuw uit.

CLAUDE.md lost dat op. Het is een gewoon tekstbestand in Markdown dat je in je project zet. Claude Code leest het aan het begin van elke sessie. Schrijf erin wat je anders steeds zou herhalen: opdrachten om te bouwen en te testen, codestandaarden, architectuurkeuzes, naamgeving en werkafspraken. Gebruikt je project al een AGENTS.md voor andere programmeerhulpen, dan kan Claude Code dat bestand ook lezen.

Een CLAUDE.md kan op meerdere plekken staan, elk met een eigen bereik. Van breed naar specifiek:

• Organisatie (beheerd door IT): op macOS /Library/Application Support/ClaudeCode/CLAUDE.md, op Linux en WSL /etc/claude-code/CLAUDE.md en op Windows C:\Program Files\ClaudeCode\CLAUDE.md. Dit bestand geldt voor elke sessie op die computer en is niet uit te zetten met eigen instellingen.
• Persoonlijk: ~/.claude/CLAUDE.md, met jouw voorkeuren voor al je projecten.
• Project: ./CLAUDE.md of ./.claude/CLAUDE.md. Dit bestand deel je via versiebeheer met je team. Het is het bestand dat je het meest gebruikt.
• Persoonlijk per project: ./CLAUDE.local.md, met je eigen aantekeningen bij dit project. Zet het in .gitignore, zodat het niet in versiebeheer komt.

Bij de start laadt Claude Code de bestanden in je werkmap en in alle mappen daarboven. Een CLAUDE.md in een submap volgt pas als Claude met bestanden in die submap werkt. De bestanden vullen elkaar aan en overschrijven elkaar niet. Instructies die het dichtst bij je werkmap staan, leest Claude als laatste. Spreken twee instructies elkaar tegen, dan kan Claude elk van beide volgen. Houd ze dus met elkaar in lijn.

Bij een groot project kun je instructies ook verdelen over losse bestanden in de map .claude/rules/, bijvoorbeeld een bestand over testen en een over de API. Zo'n regel kun je beperken tot bepaalde bestanden. Hij wordt dan alleen geladen als Claude met die bestanden werkt.

• opdrachten om te bouwen en te testen, zoals npm test of python -m pytest;
• de opbouw van het project: welke map wat bevat, en waarom;
• codestandaarden, zoals inspringen met 2 spaties;
• architectuurkeuzes, zoals "API-handlers staan altijd in src/api/handlers/";
• werkafspraken, zoals "push nooit direct naar main".

Houd het kort: de documentatie adviseert minder dan 200 regels per bestand. Een langer bestand kost meer ruimte in het contextvenster en Claude volgt de instructies dan minder goed op. Schrijf concreet en controleerbaar. Niet "formatteer code netjes", maar "gebruik 2 spaties om in te springen". Niet "test je wijzigingen", maar "draai npm test voor elke commit".

Een CLAUDE.md is context, geen afdwingbare instelling. Claude leest het en probeert het te volgen, maar dat is niet gegarandeerd, zeker niet bij vage of tegenstrijdige instructies. Moet iets echt nooit gebeuren, leg dat dan vast met een hook of een toestemmingsregel.

Naast CLAUDE.md heeft Claude Code een tweede geheugen: auto memory.

• CLAUDE.md schrijf jij: instructies en regels voor Claude.
• Auto memory schrijft Claude zelf: aantekeningen over je rol en voorkeuren, correcties die je gaf, lopend werk en besluiten die niet uit de code blijken, en waar informatie buiten het project te vinden is. Wat Claude uit de code zelf kan afleiden, slaat het niet op.

Auto memory staat standaard aan en hoort bij een repository. Het staat alleen op je eigen computer, in ~/.claude/projects/<project>/memory/. Aan het begin van elke sessie leest Claude de eerste 200 regels of 25 KB van het overzichtsbestand MEMORY.md. Vraag je Claude om iets te onthouden, dan komt het in auto memory. Wil je het in CLAUDE.md, vraag dat dan uitdrukkelijk.

Je hoeft een CLAUDE.md niet vanaf nul te schrijven. Typ /init in een sessie. Claude bekijkt je project en maakt een eerste versie met opdrachten om te bouwen en te testen en de afspraken die het ontdekt. Bestaat er al een CLAUDE.md, dan stelt Claude verbeteringen voor in plaats van het bestand te overschrijven. Vul het daarna aan met wat Claude niet zelf kan ontdekken, zoals teamafspraken of beveiligingsregels.

Met /memory open en bewerk je je CLAUDE.md-bestanden en zet je auto memory aan of uit. Met /context zie je welke bestanden echt geladen zijn.