Hoe je een CLAUDE.md schrijft die je hele team ook echt volgt

Een CLAUDE.md met 500 regels regels wordt aan het begin van elke sessie gelezen en wordt minder dan de helft van de tijd opgevolgd. Hetzelfde project, teruggebracht naar 150 regels en gekoppeld aan drie afgedwongen hooks, draait dichter bij 100 procent compliance. Dat is precies het gat waar de meeste teams in stappen wanneer ze CLAUDE.md behandelen als een wiki voor hun AI.

Waarom teams er sowieso een schrijven is logisch. Claude opent fris bij elke sessie, zonder geheugen aan het vorige gesprek, de naamgevingsconventies van het team, de woordenlijst of de regels waar zes maanden trial-and-error in zijn gaan zitten. Een persistent contextbestand lost dat op. Het probleem zit nooit in het idee. Het probleem zit in wat er in het bestand belandt.

Waarom CLAUDE.md vaak wordt genegeerd

De officiële documentatie van Anthropic noemt CLAUDE.md advisory context. In de praktijk betekent dat ergens tussen 60 en 80 procent compliance op een goede dag, afhankelijk van hoe vol het contextvenster is op het moment dat Claude de regel probeert te herinneren. De analyse van HumanLayer benoemt de faalmodus rechtstreeks: de meeste bestanden zijn te lang, te vaag en vol advies dat Claude zelf ook wel had opgevolgd.

Een tweede mechanisme versterkt het probleem. Het State of AI Engineering rapport 2026 van Datadog liet zien dat 69 procent van alle input-tokens in productie-traces opgaat aan systeemprompts, instructies, policies en tool-beschrijvingen die bij elke call worden meegestuurd. Iedere regel in CLAUDE.md gaat bij elke call mee. Zodra de context volloopt met code en gesprek, geeft het model voorrang aan wat aan het allereerste en het allerlaatste deel staat en laat het stilletjes de aandacht voor het middendeel zakken. Het plafond van rond de 300 regels dat Blink in zijn template-handleiding aanhoudt, is niet willekeurig. Het is de globale grens waar de betrouwbaarheid begint in te storten.

De derde reden is minder spannend. De meeste CLAUDE.md-bestanden worden één keer geschreven, nooit aangepast en nooit gemeten. Ze stapelen aspirationele regels op zoals 'wees beknopt' of 'denk goed na' die Claude al doet, en laten precies de specifieke bedrijfsregels weg ('het V2 dashboard is dat in productie', 'noem deze klant niet bij voornaam in schrijven') die wel echt het verschil maken.

Het redactionele budget van 150 regels

Behandel het bestand als een editorial brief, niet als een kennisbank. Elke regel verdient zijn plek. De vier secties die zichzelf consistent terugverdienen:

Stem- en toonregels. Dingen die Claude zonder expliciete instructie fout doet. 'Schrijf in de tegenwoordige tijd. Gebruik je niet de gebruiker. Maximaal drie zinnen per alinea. Open met het meest verrassende cijfer, niet met de aanloop.' Kort, imperatief, controleerbaar.

Woordenlijst. Interne productnamen, klantsegmenten, afkortingen. Wat MQL betekent in jouw funnel. Waar het V2 dashboard precies naar verwijst. Welke klant je tutoyeert en welke niet. Dit is de sectie die zichzelf elke keer terugbetaalt wanneer een nieuw teamlid of een nieuwe Claude-sessie begint.

Niet-doen-lijst. Vijf tot tien korte regels van wat nooit mag. 'Publiceer nooit zonder vrijdagreview.' 'Gebruik nooit em dashes in klantcommunicatie.' 'Verzin nooit prijzen, check altijd /docs/pricing.md.' Negatieve regels zijn in advisory tekst makkelijker te handhaven dan positieve, omdat Claude één voorwaarde toetst in plaats van iets vanaf nul goed te produceren.

Source of truth links. Verwijzingen naar waar de echte data leeft. Prijzen in één bestand. ICP-definities in Airtable. Brand voice in een aparte skill. Het bestand hoeft niet zelf de antwoorden te bevatten. Het hoort Claude naar de juiste plek te sturen om ze op te halen.

Wat geen plek verdient is alles wat Claude al goed doet uit zichzelf. Modelgedrag herhalen, opvullen met 'denk altijd voordat je handelt', of dupliceren wat een fatsoenlijke folderstructuur al laat zien. De best practices pagina van Anthropic zelf raadt aan om eerst /init te draaien om vanuit de echte codebase op te bouwen, en daarna hard te snoeien.

Waar CLAUDE.md stopt en hooks beginnen

De regels die een team echt niet 30 procent van de tijd genegeerd kan hebben, horen helemaal niet in CLAUDE.md. Die horen in hooks.

Een hook is code die voor of na een Claude-actie wordt uitgevoerd, buiten de redenering van het model om. Een analyse van Christopher Montes uit maart 2026 mat regels op promptniveau op 70 tot 90 procent compliance en hooks op 100 procent. De formulering die bleef hangen: regels in prompts zijn verzoeken, regels in code zijn wetten.

Een werkbare splitsing voor een bedrijfsteam ziet er zo uit. CLAUDE.md doet stijl, woordenlijst, naamgevingsconventies, stemregels en de niet-doen-lijst. Het soort regels waarbij af en toe afwijken acceptabel is en goed te spotten in review. Hooks doen alles wat destructief, duur of compliance-kritisch is. Pushes naar main blokkeren. Een human review-stap verplichten voordat een klantmail uitgaat. Een linter of typecheck verplichten voor commit. Bepaalde API-calls in bepaalde omgevingen weigeren. Het soort regel dat, als Claude het 30 procent van de tijd negeert, het experiment beëindigt.

Deze splitsing is precies wat CLAUDE.md kort houdt. Zodra de echt kritische regels naar hooks verhuizen, hoeft het bestand niet langer het gewicht te dragen om elke keer goed te zijn. Het wordt wat het had moeten zijn: een redactionele brief.

De vraag rond de open standaard

Een team dat in 2026 Claude adopteert, moet ook een keuze maken over AGENTS.md. AGENTS.md is een open, tool-agnostische instructiestandaard ontwikkeld door Sourcegraph, OpenAI, Google, Cursor en Factory, en wordt nu beheerd door de Linux Foundation. De adoptie zit voorbij 60.000 repositories, inclusief projecten als n8n en LangFlow.

Claude Code leest AGENTS.md standaard niet. Het schoonste patroon voor een team met meerdere tools is AGENTS.md als gedeelde source of truth (gelezen door Cursor, Codex, Copilot, Gemini) met een korte CLAUDE.md die hem importeert voor Claude-specifieke lagen zoals hooks en skill-verwijzingen. Als Claude de enige AI in de workflow is, is deze complexiteit overbodig en volstaat CLAUDE.md alleen. De beslissing hoort gestuurd te worden door welke tools het team daadwerkelijk gebruikt, niet door welke standaard op dit moment de GitHub-sterrenrace wint.

Een starttemplate die overeind blijft

De versie waar de meeste agencies die in productie op Claude draaien op uitkomen, na de derde of vierde herschrijving, ziet er zo uit. 10 tot 30 regels bovenaan voor doel van het project, stack en belangrijke folders. 20 tot 40 regels voor stem- en toonregels. 20 tot 40 regels voor de woordenlijst en naamgeving. 10 tot 20 regels voor de niet-doen-lijst. 10 tot 30 regels voor source of truth links. 5 tot 10 regels voor hoe om te gaan met onbekenden: wanneer vragen, wanneer een web search doen, wanneer stoppen en flaggen.

Totaal: 75 tot 170 regels. De grens van 200 is een zacht plafond, geen doel. Bestanden dichter bij 100 regels presteren regelmatig beter dan bestanden van 200 regels omdat de signaal-ruisverhouding hoog blijft. De eerste test voor elke nieuwe regel is of Claude de fout zonder die regel zou hebben gemaakt. Is het antwoord nee, dan is de regel ruis vermomd als instructie.

Eén discipline maakt nog meer verschil dan de structuur: bewerk het bestand wanneer het team iets leert. Een CLAUDE.md die in maand één wordt uitgerold en daarna nooit meer wordt aangeraakt, is in maand zes hetzelfde als geen CLAUDE.md. De compounding waarde zit in het bewerken, niet in het schrijven.

De praktische herkadering

Het instinct om alles wat een team weet op te schrijven is correct. Het instinct om het allemaal in CLAUDE.md te zetten niet. Een werkende CLAUDE.md is een redactionele brief met een hard budget, gekoppeld aan hooks die de regels afdwingen die niet mogen schuiven. Teams die het zo aanpakken krijgen de persistente context waar ze om vroegen. Teams die het als wiki behandelen, eindigen met hetzelfde blanke-sessie probleem dat ze dachten te hebben opgelost, plus de kosten van het schrijven van de wiki.