CLAUDE.md voor je websiteproject: schrijf bruikbare projectinstructies

Claude Code kan projectinstructies gebruiken om afspraken tussen sessies bij de hand te houden. Voor een websiteproject is een CLAUDE.md daarom een goede plek voor context die bij veel opdrachten opnieuw nodig is: hoe het project is opgebouwd, welke commando's je gebruikt en welke bestaande werking beschermd moet blijven.

Een bruikbaar bestand is geen encyclopedie en ook geen vervanging voor een concrete opdracht. Het geeft Claude Code een compacte routekaart naar de belangrijke delen van je project. Anthropic beschrijft projectgeheugen als gedeelde instructies in ./CLAUDE.md en noemt onder andere architectuur, coderingsafspraken en gangbare workflows als voorbeelden. (Anthropic: Claude Code-geheugen)

Wat is een CLAUDE.md-bestand?

Het is een Markdown-bestand met instructies voor Claude Code. Als je het in de projectmap zet, kan het gedeelde projectcontext bevatten. Het doel is terugkerende afspraken op één plek zetten, zodat je niet iedere prompt opnieuw hoeft te beginnen met dezelfde uitleg.

De inhoud moet wel actueel blijven. Verouderde commando's of grenzen kunnen net zo verwarrend zijn als ontbrekende instructies. Behandel CLAUDE.md daarom als projectdocumentatie: controleer het wanneer je scripts, architectuur of belangrijke routes verandert.

Begin met een korte projectkaart

Beschrijf in enkele regels wat de website doet, wie ze gebruikt en welke hoofdtechnologieën of mappen belangrijk zijn. Noem alleen informatie die Claude nodig heeft om gewone taken goed te plaatsen. Een marketingwebsite met een blog en een afgeschermde klantomgeving heeft bijvoorbeeld meer context nodig dan alleen “dit is een Next-project”.

Wees concreet over de onderdelen waar wijzigingen gevoelig liggen. Je kunt benoemen waar gedeelde navigatie zit, waar blogartikelen staan en welke bestaande routes of integraties behouden moeten blijven. Vermeld geen geheimen, API-sleutels of persoonlijke gegevens in dit bestand; het is projecttekst die in de repository kan staan.

Leg vaste afspraken vast, geen volledige opdracht

Een goede projectinstructie helpt bij meerdere taken. Denk aan bestaande componenten hergebruiken, semantische HTML gebruiken, geen dependency toevoegen zonder reden, of bij een kleine wijziging niet meteen de hele pagina herontwerpen.

De concrete taak hoort nog steeds in je prompt. CLAUDE.md kan zeggen dat bestaande routes behouden blijven; jouw opdracht vertelt welke route je wilt aanpassen en wat de gewenste uitkomst is. Zo voorkom je dat projectregels vaag moeten raden wat je vandaag bedoelt.

Schrijf de beschermde grenzen expliciet op

Websites bevatten vaak onderdelen waarbij een ogenschijnlijk kleine wijziging gevolgen heeft buiten het scherm. Benoem de relevante grenzen, bijvoorbeeld:

• routes die moeten blijven bestaan;
• checkout-, account- of toegangslogica die buiten de scope valt;
• mail- of webhookkoppelingen die niet aangepast mogen worden;
• beschermde content die niet in publieke pagina's mag belanden;
• bestaande prijzen, labels of productteksten die bron van waarheid zijn.

Pas die lijst aan je echte project aan. Neem geen generieke verboden op die niet bestaan; onjuiste regels maken het moeilijker om de instructies te vertrouwen. En als een latere opdracht uitdrukkelijk een grens wil wijzigen, vraag dan om de benodigde analyse in plaats van stilzwijgend tegenstrijdige regels te laten staan.

Noteer de echte commando's voor controle

Schrijf op hoe je dit project daadwerkelijk controleert. Dat kunnen aparte commando's zijn voor build, lint, types of tests. Kopieer ze uit package.json of projectdocumentatie en controleer dat ze werken wanneer je scripts aanpast.

Voeg geen fictieve commando's toe zoals npm run check-all als dat script niet bestaat. Je kunt ook beschrijven welke lokale route je na een wijziging in de browser controleert. Een korte, juiste controle-instructie is waardevoller dan een lange lijst generieke commando's.

Houd algemene afspraken compact en verwijs gericht door

Als de repository al documentatie heeft voor ontwerpregels, content, architectuur of een speciale workflow, link er dan vanuit CLAUDE.md naar in plaats van alle details dubbel te kopiëren. Zet bovenaan de paar regels die vrijwel elke opdracht nodig heeft. Specialistische afspraken horen bij voorkeur dichter bij het onderdeel waar ze gelden.

Anthropic documenteert ook dat geheugenbestanden andere bestanden kunnen importeren met @path/to/import. Controleer de actuele syntaxis in de officiële documentatie voordat je imports gebruikt; een Markdown-verwijzing die er alleen als gewone tekst uitziet, is niet automatisch hetzelfde als een werkende import. (Anthropic over geheugen en imports)

Een CLAUDE.md is instructietekst, geen harde beveiligingsmaatregel. Zet er dus niet alleen “wijzig nooit betalingen” in en ga er dan van uit dat code of acties technisch onmogelijk zijn. Gebruik voor echte toegangsbeperkingen de instellingen en permissies van je ontwikkelomgeving, en controleer gevoelige wijzigingen zelf. Anthropic maakt expliciet onderscheid tussen projectinstructies die gedrag sturen en instellingen die door de client worden afgedwongen. (Anthropic: projectinstructies en beveiligingsgrenzen)

Een compacte opzet voor een websiteproject

Je kunt met deze indeling beginnen en alleen onderdelen behouden die echt op je project slaan:

# Project
- Korte omschrijving van de website en de belangrijkste gebruikers.
- Belangrijkste routes en mappen: [vul echte paden in].

# Werkwijze
- Onderzoek eerst relevante bestanden; wijzig alleen de afgesproken scope.
- Behoud bestaande routes, productinformatie en werkende interacties.
- Gebruik bestaande componenten en patronen waar dat past.

# Grenzen
- Pas deze onderdelen niet aan zonder expliciete opdracht: [specifieke grenzen].
- Plaats geen geheimen of privégegevens in de repository.

# Controles
- Build: [echt commando uit package.json].
- Lint en types: [echte commando's uit package.json].
- Controleer lokaal: [route en relevante gebruikersactie].

Vervang ieder voorbeeld door echte gegevens of verwijder het. Een model kan niet afleiden welke routes of scripts jouw project heeft als je die niet controleert.

Controleer of Claude Code de instructies ziet

Na het opslaan kun je Claude Code vragen welke projectregels het heeft gelezen en waar relevante code staat. Controleer het antwoord tegen de echte repository. Als je een instructie toevoegt over een buildscript, kijk of dat script bestaat; als je een route noemt, open die route zelf.

Als het project ook AGENTS.md bevat, ga dan niet automatisch ervan uit dat elk bestand in iedere Claude Code-installatie op dezelfde manier wordt geladen. De huidige documentatie beschrijft dat dit afhangt van de versie en instelling voor projectinstructies. Controleer de relevante configuratie en laat Claude de geladen instructies samenvatten. (Anthropic over Claude Code-projectinstructies)

Bij twijfel over de volgorde van regels of imports, raadpleeg de actuele documentatie en vraag Claude om het relevante geheugenbestand te inspecteren. Voer niet meteen een wijziging uit om te bewijzen dat de context werkt; eerst lezen en samenvatten is een veilige controle.

Checklist voor je eerste versie

• ☐ De projectomschrijving legt in enkele zinnen uit wat de site doet.
• ☐ Belangrijke routes en mappen verwijzen naar paden die echt bestaan.
• ☐ Terugkerende afspraken staan hier; eenmalige taakeisen blijven in je prompt.
• ☐ Risicovolle onderdelen en grenzen zijn concreet en projectrelevant.
• ☐ Build-, lint-, type- en testcommando's komen overeen met dit project.
• ☐ Er staan geen wachtwoorden, tokens of privégegevens in het bestand.
• ☐ Dubbele regels zijn verwijderd en specialistische documenten gelinkt.
• ☐ Claude Code kan de instructies kort samenvatten zonder ze verkeerd uit te leggen.

Een goede CLAUDE.md maakt opdrachten consistenter, maar garandeert niet dat een wijziging correct is. Geef voor elke taak nog steeds de gewenste uitkomst, controleer de diff en test de relevante pagina. Lees ook het stappenplan voor een bestaande website aanpassen met Claude Code en gebruik eventueel het gratis taakdossier om één opdracht helder af te bakenen.