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. Meestal niet omdat de code kapot was, maar 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.

Het verschil zat niet in een betere prompt en niet in een nieuwe modelversie. Het 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 de grootste hefboom die ik tot nu toe heb gevonden om “senior engineer”-output te krijgen in plaats van generieke AI-brei, en het meest onderschatte onderdeel van de hele toolchain.

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, wat ik met vallen en opstaan heb geleerd, en de werkafspraken over hoe de agent moet werken (in het vak heet dat workflow orchestration) 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 is geen harde instructie, maar context. 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.

Als je CLAUDE.md vaag is, krijg je vage code. Als het specifiek is, krijg je code die past bij je repo. Als het ontbreekt, krijg je wat de trainingsdata van Claude als “best practice” beschouwt, 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 is de vraag niet óf je zo’n contextbestand nodig hebt, maar wie het schrijft en bijhoudt. Wat ik bij veel teams zie, ook in Nederland: er wordt volop geëxperimenteerd met deze tools, maar vrijwel altijd zonder serieuze projectcontext. Het resultaat: code die er goed uitziet en die reviewers handmatig terugbuigen naar de huisstijl van de repo, 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: het bestand doet niets zonder agent die het leest.

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. Die brengt je een heel eind. Genoeg is het niet.

Waar mijn CLAUDE.md verder gaat

Na genoeg reverts voegde ik een workflow-orchestration sectie toe die niets zegt over wat het project is, maar alles over 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?” Als een fix hacky aanvoelt: implementeer dan de elegante oplossing. Sla dit over bij simpele fixes (niet overengineeren). Daag je eigen werk uit voordat je het presenteert.

Autonoom bugs oplossen. Bij een bugrapport: los het gewoon op. Vraag niet om begeleiding. Raadpleeg logs, foutmeldingen en falende tests, en los ze dan op. Geen context-switching nodig van mijn kant.

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 als een schone lei behandelt. Met deze regels bouwt de agent van sessie op sessie voort.

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, stortte mijn percentage herhaalde fouten in. De op één na nuttigste toevoeging was de sectie over verificatie-voor-afronding. De meeste van mijn vroege reverts waren technisch werkende code die ik niet wilde, geen kapotte code.

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, geen merkboek. 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 uitvoerbaar zijn.

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 van vroeger zou meegeven:

1. De tien secties zijn noodzakelijk, niet voldoende. Voeg een workflow-orchestration sectie toe. Zonder die sectie heeft de agent geen enkel idee van hoe 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. De agent wordt slimmer met elk gesprek, in plaats van steeds opnieuw te beginnen.

De belofte van agentic coding was “vertel het wat je wilt en loop weg”. De realiteit is dat “wat je wilt” het bestand is 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.