CLAUDE.md: het bestand dat bepaalt of Claude Code helpt of tegenwerkt

In mijn eerste twee weken serieus werken met Claude Code draaide ik ruim een op de vijf wijzigingen weer terug. Zelden omdat de code kapot was; meestal omdat het niet de code was die ik wilde: verkeerde mappen, verkeerde patronen, een stijl die nergens bij mijn repo paste. Vier weken later was datzelfde percentage 7 procent.

Er kwam geen betere prompt aan te pas en geen nieuwe modelversie. Het verschil zat in CLAUDE.md: een gewoon tekstbestand in je repository dat Claude Code aan het begin van elk gesprek inleest. Zie het als het inwerkdocument dat je een nieuwe collega geeft. Elke week test ik een AI-onderwerp onder realistische omstandigheden; deze week dus dat ene bestand. Het is tot nu toe de grootste hefboom die ik heb gevonden om “senior engineer”-output te krijgen in plaats van generieke AI-brei, en het onderdeel dat ik om me heen het vaakst overgeslagen zie worden.

De afgelopen zes weken leverde ik 240 Claude Code-commits uit, verspreid over drie repo’s. De grootste voorspeller van welke commits ik moest terugdraaien was de kwaliteit van dit ene bestand.

Deze post beschrijft wat ik vandaag in CLAUDE.md zou zetten en wat ik met vallen en opstaan heb geleerd. Plus de werkafspraken over hoe de agent moet werken, in het vak workflow orchestration genoemd, die ik nu als basisvereiste beschouw.

Wat CLAUDE.md eigenlijk doet

CLAUDE.md wordt geladen als projectgeheugen aan het begin van elk Claude Code-gesprek. Het werkt als context: de agent leest het mee, maar het is geen dwingende instructie. Claude behandelt de regels erin zoals een competente contractor een briefing behandelt: als een stevig uitgangspunt waarvan hij af en toe afwijkt als de taak daarom vraagt.

Een vaag CLAUDE.md levert vage code op. Een specifiek bestand levert code op die past bij je repo. Ontbreekt het, dan krijg je de aanpak die in brede trainingsdata het vaakst als “best practice” voorkomt, en dat is vaak het verkeerde antwoord voor jouw codebase.

Voor wie is dit nu relevant?

Gebruikt je team Claude Code, Cursor of een vergelijkbare AI-coding tool? Dan gaat de vraag allang niet meer over óf je zo’n contextbestand nodig hebt. De vraag is wie het schrijft en bijhoudt. Wat ik bij veel teams zie, ook in Nederland: er wordt volop geëxperimenteerd met deze tools, maar vaak zonder serieuze projectcontext. Het resultaat: code die er goed uitziet, waarna reviewers hem met de hand terugbuigen naar de conventies van de repo. Dat kost precies de tijd die de tool had moeten besparen.

De realistische eerste stap kost een uur, geen project: schrijf de tech stack op (inclusief wat je niet gebruikt), de echte build- en testcommando’s, en drie tot vijf architectuurregels waar reviewers nu steeds op corrigeren. Wie geen AI-tooling in de ontwikkelstraat heeft, hoeft hier nog niets mee: zonder een agent die het bestand leest, doet het niets.

De tien secties die hun plek verdienen

De structuur waar ik op uitkwam na het bestand vijf keer te hebben herschreven:

1. Projectoverzicht. Drie tot vijf zinnen. Wat het product is. Voor wie het is. Waarop het optimaliseert. De belangrijkste vraag om te beantwoorden: wat moet voor Claude zwaarder wegen als hij moet kiezen?
2. Tech stack. Wees expliciet. Schrijf niet “React stack”. Schrijf “Next.js 16 App Router + TypeScript + Tailwind v4 + shadcn/ui + Supabase”. Neem ook op wat je NIET moet gebruiken. “Geen Redux. Geen Material UI. Geen styled-components.” Dit ene subonderdeel bespaarde me ruwweg een derde van mijn vroege reverts.
3. Architectuur. Verantwoordelijkheden van mappen en beslisregels. Niet “src/components bevat componenten”. In plaats daarvan: “Gebruik components/ui voor herbruikbare presentatie-primitieven. Gebruik features/* voor domein-UI en logica. Houd API-calls buiten presentatiecomponenten.”
4. Codeerconventies. Naamgeving, exports, typebeleid, bestandsgrootte, comments. Specifiek, anders is het ruis. “Gebruik named exports behalve voor route-bestanden” is elke keer beter dan “gebruik clean code”.
5. UI- en designregels. Spacing-ritme, typografie, interactieve states, toegankelijkheidsminimum. Als je project een frontend heeft, is dit goud waard. Vertaal “modern” naar “8px ritme, ingetogen kleur, sterke typografische hiërarchie”.
6. Content- en copyrichtlijnen. Onderschat. Vertelt Claude in welke stem hij moet schrijven voor UI-teksten, foutmeldingen, marketingcopy. Zonder dit krijg je standaard LinkedIn-taal.
7. Testen en kwaliteitsniveau. Waarvoor je tests toevoegt. Wat “klaar” betekent. De exacte lint- en typecheck-commando’s. Zonder dit gaat Claude óf te veel testen (scaffolding voor triviale UI) óf te weinig (logica overslaan die dekking nodig heeft).
8. Regels voor bestands- en componentplaatsing. “Waar hoort nieuwe code thuis?” Het onderdeel dat repo-drift voorkomt. In volwassen repo’s is dit het verschil tussen een schone PR en drie bijna-identieke componenten.
9. Regels voor veilige wijzigingen. Wat Claude niet zomaar mag aanraken. Publieke API-routes, schema-migraties, auth-flows. De “wees hier niet te slim”-lijst.
10. Commando’s. De daadwerkelijke install-, dev-, build-, lint-, test- en typecheck-commando’s. Echt en actueel. Verouderde commando’s zijn erger dan ontbrekende.

Het patroon achter al deze secties: een vage voorkeur wordt pas bruikbaar als je hem herschrijft tot een regel waar de agent iets mee kan.

Dat is de standaardlijst, en die brengt je een heel eind. Maar genoeg is het niet.

Waar mijn CLAUDE.md verder gaat

Na genoeg reverts voegde ik een workflow-orchestration sectie toe. Die zegt niets over wat het project is; hij beschrijft hoe Claude moet werken. Dit waren de toevoegingen die mijn revert rate (het aandeel commits dat ik moest terugdraaien) van 21% naar 7% brachten.

Plan mode als standaard. Plan mode is de stand waarin Claude eerst een plan voorlegt voordat hij code aanraakt. Ga in plan mode voor elke niet-triviale taak (3+ stappen of elke architecturale beslissing). Als iets misgaat, stop en herplan in plaats van doorduwen. Gebruik plan mode ook voor verificatie, niet alleen voor het bouwen.

Subagent-strategie. Subagents zijn hulp-agents die een deeltaak apart uitvoeren, zodat het werkgeheugen van het hoofdgesprek (het contextvenster) schoon blijft. Besteed onderzoek, verkenning en parallelle analyse uit. Zet meer rekenkracht in voor lastige problemen door taken te parallelliseren over subagents. Eén taak per subagent voor gerichte uitvoering.

Zelfverbeterlus. Werk tasks/lessons.md na elke correctie van mij bij met het patroon dat misging. Schrijf een regel die dezelfde fout voorkomt. Bekijk de lessen aan het begin van elke sessie. Deze ene sectie liet mijn percentage herhaalde fouten met een factor tien dalen.

Verificatie voor afronding. Markeer nooit een taak als voltooid zonder te bewijzen dat het werkt. Vergelijk het gedrag tussen main en de wijziging. Vraag jezelf: “zou een staff engineer dit goedkeuren?” Draai tests, controleer logs, toon correctheid aan.

Eis elegantie (in balans). Voor niet-triviale wijzigingen: pauzeer en vraag “is er een elegantere manier?” Voelt een fix als een omweg, implementeer dan de nette oplossing. Sla dit over bij simpele fixes (niet overengineeren). Zoek zelf het gat in je oplossing voordat je hem presenteert.

Autonoom bugs oplossen. Bij een bugrapport: gewoon oplossen, zonder eerst om richting te vragen. Raadpleeg logs, foutmeldingen en falende tests, en werk vandaaruit. Zo hoef ik er niet telkens mijn eigen werk voor te onderbreken.

Taakbeheer. Plan eerst (tasks/todo.md), verifieer het plan, houd voortgang gaandeweg bij, leg wijzigingen bij elke stap uit, documenteer resultaten, leg lessen vast na correcties.

Kernprincipes. Eenvoud eerst. Niet de makkelijke weg kiezen (zoek grondoorzaken, geen tijdelijke fixes, senior-developer-standaarden). Minimale impact (wijzigingen raken alleen wat noodzakelijk is).

Dit leest als generiek procesadvies totdat je beseft dat de agent zonder deze regels elke sessie schoon begint. Met deze regels heeft hij een werkwijze om op terug te vallen.

De cijfers van zes weken

Ik heb 240 Claude Code-commits nagelopen en elke commit beoordeeld als: schoon uitgeleverd, uitgeleverd met aanpassingen, of teruggedraaid.

• Weken 1–2 (minimale CLAUDE.md): 198 commits geprobeerd, 156 uitgeleverd, 42 teruggedraaid. 21% revert rate.
• Weken 3–4 (leerboek 10 secties): 156 commits geprobeerd, 137 uitgeleverd, 19 teruggedraaid. 12% revert rate.
• Weken 5–6 (volledige CLAUDE.md met workflow orchestration): 184 commits geprobeerd, 172 uitgeleverd, 12 teruggedraaid. 7% revert rate.

Zelfde model, zelfde projecten, zelfde ik. Het enige dat veranderde was het contextbestand. Eén meting van één persoon, geen wetenschap, maar consistent genoeg om er mijn werkwijze op in te richten.

De meest waardevolle toevoeging was de zelfverbeterlus. Zodra Claude actief regels schreef om zijn eigen fouten uit het verleden te voorkomen, kwamen dezelfde correcties bijna niet meer terug. De op één na nuttigste toevoeging was de sectie over verificatie-voor-afronding. De meeste van mijn vroege reverts waren namelijk technisch werkende code die ik gewoon niet wilde hebben.

Wat niet werkt

Drie faalpatronen die ik moest afleren:

Lange merkverhalen. Ik had een prachtig geschreven projectoverzicht met bedrijfsgeschiedenis, missiestatement en “waar we in geloven”. Het was nutteloos. Claude heeft een scherp mentaal model nodig. Drie zinnen wint het van drie alinea’s.

Vage voorkeuren. “Schrijf schone code” is geen regel. “Houd componenten onder de 200 regels tenzij er een gedocumenteerde reden is om dat te overschrijden” is dat wel. Elke regel in CLAUDE.md moet zo staan dat je kunt nakijken of hij is opgevolgd.

Verouderde commando’s. Toen ik het testcommando veranderde van pnpm test naar npm run check en vergat CLAUDE.md bij te werken, bleef Claude het oude commando draaien en taken “verifiëren” tegen een commando dat niet bestond. Verificatie stelde daardoor niets meer voor. Ik behandel de commando-sectie nu als onderdeel van de build.

Wat ik zou meegeven aan iedereen die er net mee begint

Drie regels die ik mezelf aan het begin zou meegeven:

1. De tien secties zijn noodzakelijk, niet voldoende. Voeg een workflow-orchestration sectie toe. Zonder die sectie weet de agent niets over de manier waarop jij werkt.
2. Behandel CLAUDE.md als code, niet als documentatie. Versioneer het, review het, controleer het op veroudering. Een verkeerde regel is erger dan geen regel.
3. Leg lessen vast terwijl je corrigeert. De gewoonte die me het meest heeft opgeleverd. Elke correctie wordt een toekomstige regel. Het model leert er zelf niets van, maar het bestand waaruit het leest wordt elk gesprek beter.

Agentic coding beloofde “vertel het wat je wilt en loop weg”. In de praktijk is “wat je wilt” het bestand dat je voor altijd blijft bewerken. CLAUDE.md is dat bestand. Mijn inschatting: teams die dit bestand als code behandelen, halen structureel meer uit dezelfde tooling dan teams die het overslaan. In mijn eigen cijfers was dat het verschil tussen 21 en 7 procent terugdraaien.