CLAUDE.md en rules: projectinstructies voor Claude Code schrijven

Claude Code kiest steeds opnieuw het verkeerde testcommando. Je corrigeert het, de sessie gaat verder en een week later begint hetzelfde gesprek opnieuw. Dat is een goede reden om een projectinstructie vast te leggen. Je hoeft daarvoor geen handboek over je hele codebase te schrijven.

Een bruikbaar CLAUDE.md helpt bij beslissingen die anders steeds verkeerd worden genomen. Zet er compacte afspraken in die vandaag gelden. Bewaar het lange onderzoek achter zo'n afspraak op een eigen, passende plek, zodat een nieuwe sessie niet eerst alle oude omwegen hoeft te lezen.

Neem een ledenapp voor een vereniging. Er is een bestaande functie voor geldbedragen, omdat contributies in centen worden opgeslagen. In het project staan ook oude schermen die zelf bedragen afronden. Claude kan die schermen vinden en het verouderde patroon kopiëren.

Een nuttige instructie vertelt daarom welk patroon nu geldt en waarom: gebruik de bestaande geldfunctie; de opslag werkt met centen. Een opsomming van alle schermen voegt voor die keuze weinig toe. De regel moet helpen het verkeerde voorbeeld te herkennen.

Vraag bij iedere nieuwe regel: wanneer zou deze het gedrag veranderen? 'Schrijf goede code' geeft geen beslisregel. 'Gebruik voor contributiebedragen de bestaande omzetting van centen naar euro's' wijst een concrete route aan. Controleer wel eerst of die functie echt bestaat en nog de bedoelde route is.

Stel dat het project npm gebruikt en deze scripts al heeft. Dan kan een eerste versie zo compact zijn:

De bestandsnamen en scripts zijn onderdeel van het oefenproject. Neem ze niet blind over. Laat Claude in jouw project de echte functie en commando's aanwijzen. Draai de commando's zelf of bekijk de uitvoering voordat je ze als vaste afspraak opslaat.

De praktijkrichtlijnen van Anthropic adviseren korte projectinstructies met informatie die niet vanzelf uit de code blijkt. Het bestand blijft zo een ingang voor het werk, in plaats van een tweede beschrijving van alles wat al in de repository staat.

Voor Claude Code kun je instructies verder opdelen in .claude/rules/. Met paths koppel je een regel aan passende bestanden. De officiële instructiehandleiding beschrijft wanneer zulke regels worden ingeladen.

Voor de ledenapp zou een regel voor de contributiecode bijvoorbeeld in .claude/rules/contributie.md staan:

Deze afspraak helpt bij de contributiefunctie. Bij het aanpassen van een profielfoto is zij vooral ruis. Verplaats regels alleen wanneer hun bereik duidelijk is; tientallen bestanden met ieder één bijna gelijke regel maken onderhoud juist moeilijker.

Een volledige releaseprocedure heeft weer een andere vorm. Daar telt de volgorde van stappen. Zet die stappen in een aparte skill en verwijs vanuit de projectafspraken naar de procedure.

Gebruik /context om de instructies te bekijken die bij de start zijn geladen. Open voor een plaatselijke regel een passend bestand en controleer de laadmelding met het regelpad. De startlijst bewijst niet dat iedere later geladen regel daarin verschijnt.

Gebruikt het team ook AGENTS.md, houd rekening met de ingestelde instructiekeuze en de geïnstalleerde Claude Code-versie. Automatisch rechtstreeks laden daarvan vraagt minimaal v2.1.277. Een aanwezige CLAUDE.md of CLAUDE.local.md kan de standaardkeuze veranderen; de actuele handleiding legt de combinatie uit. Ga dus niet alleen op de bestandsnaam af.

Test vervolgens het effect met een beperkte opdracht: vraag welke geldfunctie Claude voor een contributieoverzicht wil gebruiken en waarom. Het juiste antwoord moet naar de bestaande functie wijzen. Een bestand in de contextlijst bewijst dat het geladen is; dit vervolg laat zien of de afspraak bij de taak wordt toegepast.

Misschien kostte het uitzoeken van de afrondingsfout een middag. Daarbij zijn drie oplossingen afgevallen en stonden er tijdelijke vermoedens in het gesprek. Die hele geschiedenis in CLAUDE.md plakken maakt niet duidelijker wat nu geldt.

Bewaar het onderbouwde productbesluit waar je team zulke besluiten bijhoudt. Zet in de instructie alleen de geldende afspraak en eventueel een verwijzing. Moet iemand later weten waarom afronden op deze manier gebeurt, dan kan die de onderbouwing opzoeken.

Maak ook onderscheid tussen een blijvende regel en de stand van één taak. 'Het contributieoverzicht moet nog worden nagekeken' is werkstatus. Het hoort niet maandenlang iedere nieuwe wijziging te sturen. Haal zo'n melding weg zodra de taak is afgehandeld.

Verandert het testscript of verhuist de geldfunctie, pas dan de verwijzing aan bij dezelfde wijziging. Zoek bij een terugkerende fout eerst naar een verouderde of tegenstrijdige afspraak. Meer nadruk en hoofdletters lossen die tegenstelling niet op.

Je kunt een instructie bovendien niet als technische blokkade behandelen. Als een bepaalde controle een wijziging moet tegenhouden, moet je dat in het controleproces organiseren. De uitleg over Claude Code memory en de complete handleiding helpen bij die inrichting. In Claude Code voor beginners bouw je daar vanaf de basis aan.

Bijgewerkt op 27 oktober 2026. De productfeiten zijn gecontroleerd in de volgende officiële bronnen.