CLAUDE.md na Opus 5: waarom lange instructies Claude nu in de weg zitten

Informatie over werken met Ailoot vind je in de documentatie.

Wat is er na de release van Opus 5 veranderd in Claude?#

Opus 5 verscheen op 24 juli 2026 en werd meteen het standaardmodel in Claude Code. Het model zelf — de prijs, benchmarks en inspanningsmodi — wordt uitgebreid behandeld in een aparte gids, “Moet je overstappen op Claude Opus 5?”. Dit artikel gaat over iets anders: met de release van het model veranderde ook hoe je er effectief mee communiceert.

Anthropic publiceerde een analyse op de Claude-blog. De kern ervan is als volgt:

De kernformulering is “te veel beperken”. Toen modellen zwakker waren, hadden ze houvast nodig: doe dit, doe dat niet, hier is een voorbeeld, herhaal het nog eens. Opus 5 heeft dat houvast niet meer nodig en erger nog, het kan in de weg gaan zitten. Anthropic formuleert het nieuwe principe eenvoudig: laat Claude zijn eigen oordeel gebruiken.

Wat betekent dat in de praktijk voor jou?

• Je CLAUDE.md is hetzelfde soort systeemprompt, maar dan voor je project. Als Anthropic zijn eigen bestand met 80 procent heeft ingekort, is dat van jou waarschijnlijk ook uit zijn voegen gegroeid.
• Lange lijsten met regels garanderen niet langer dat ze worden opgevolgd. Integendeel: hoe meer regels er zijn, hoe minder nauwkeurig het model ze volgt (hieronder lees je meer, met cijfers uit de documentatie).
• Er zijn nieuwe mechanismen bijgekomen—automatisch geheugen en skills—die een deel van het werk overnemen waarvoor je vroeger alles handmatig in CLAUDE.md moest uitschrijven.

Het belangrijkste werk gebeurt vóór de prompt: in wat je in de context van het model zet voordat je je eerste verzoek doet. De update van Opus 5 is in wezen Anthropic’s officiële bevestiging van hetzelfde idee. Deze keer zijn er concrete cijfers en nieuwe tools bijgekomen. Ik bespreek ze een voor een.

Waarom zit een lange CLAUDE.md nu in de weg?#

Zo werkt het. CLAUDE.md is een bestand met regels dat Claude aan het begin van elke sessie leest. Een aparte gids, “CLAUDE.md instellen”, legt uit hoe je er een vanaf nul opbouwt; dit artikel gaat juist over wat je er nu uit moet verwijderen. Alles wat je erin schrijft, komt vóór je eerste verzoek in de context en blijft daar gedurende het hele gesprek. De context is niet oneindig — elke extra regel neemt ruimte in die anders voor je taak beschikbaar was.

De Claude Code-documentatie zegt het zonder omhaal:

Het tweede punt is belangrijker dan het eerste: lange bestanden verminderen het opvolgen van instructies. Het model gaat minder aandachtig luisteren. Dit is een valkuil waar bijna elke beginner intrapt. De redenering lijkt waterdicht: ik wil dat Claude naar me luistert, dus schrijf ik meer regels. In de praktijk gebeurt het tegenovergestelde. Hoe langer de lijst, hoe meer de aandacht van het model versnipperd raakt en hoe vaker het een regel overslaat.

Zo is de aanpak veranderd:

Er is nog een tweede probleem: tegenstrijdigheden. Naarmate een bestand groeit, stapelen regels die elkaar tegenspreken zich bijna onvermijdelijk op. Er staat ergens “schrijf altijd tests” en ergens anders “kom niet aan de testmap”. De documentatie waarschuwt dat Claude bij twee tegenstrijdige regels willekeurig een van beide kan kiezen. Met andere woorden: een overvol bestand maakt het gedrag van het model minder voorspelbaar.

Een eenvoudige regel: CLAUDE.md is een korte notitie met wat Claude niet zelf kan afleiden. Alles daarbovenop neemt alleen maar aandacht in beslag.

Wat moet je in CLAUDE.md houden en wat moet je verwijderen?#

De documentatie geeft een duidelijk criterium om te bepalen of een regel in CLAUDE.md thuishoort. Voeg hem toe als:

1. Claude voor de tweede keer dezelfde fout maakte.
2. Een codecontrole iets aan het licht bracht wat het model over dit project had moeten weten.
3. Je dezelfde correctie voor de tweede keer in de chat typt.
4. Een nieuw teamlid dezelfde context nodig zou hebben om te voorkomen dat het project stukgaat.

Het algemene principe is om projectspecifieke valkuilen te behouden en het vanzelfsprekende te verwijderen. Claude Code heeft zelfs een ingebouwde claude doctor-controle die voorstelt een overvolle CLAUDE.md op te schonen. De controle schrapt details die het model uit de codebase kan afleiden—mappenstructuur, lijst met afhankelijkheden, architectuuroverzicht—en behoudt valkuilen, de redenen erachter en conventies die afwijken van de standaard.

De tweede belangrijke regel is specificiteit. Vage formuleringen werken niet. Vergelijk:

Het verschil is eenvoudig. Het model kan “formatteer het goed” interpreteren zoals het wil. “Gebruik een inspringing van 2 spaties” kan ondubbelzinnig worden gecontroleerd. Elke regel in CLAUDE.md moet iets zijn wat je kunt controleren en zien—of de regel is gevolgd of niet.

En ten derde: verwijder het vanzelfsprekende. Als je “schrijf schone code” of “volg best practices” in CLAUDE.md zet, is dat ruis. Het model weet dat al, en de regel neemt ruimte in en versnipperd zijn aandacht. Anthropic raadt nadrukkelijk af context te besteden aan vanzelfsprekende zaken.

Waar moet je regels naartoe verplaatsen die niet in CLAUDE.md passen?#

Hier komt de meest onderschatte tool van pas. Als vroeger alle instructies in CLAUDE.md moesten staan, hebben lange procedures nu een eigen plek: skills. Een aparte gids, “Claude Code-skills kiezen”, legt uit hoe je de juiste kiest zonder er te veel toe te voegen.

Het verschil is fundamenteel. CLAUDE.md wordt aan het begin van elke sessie volledig geladen. Een skill niet. De documentatie zegt het als volgt:

Dit heet progressive disclosure: informatie naar behoefte laden. Het idee is om het model op het juiste moment context in delen te geven. Anthropic heeft zijn gedetailleerde instructies—bijvoorbeeld voor codebeoordelingen—naar skills verplaatst en uit de systeemprompt gehaald.

Het criterium om iets naar een skill te verplaatsen is eenvoudig: een onderdeel van CLAUDE.md is van een feit veranderd in een procedure. Een notitie van één regel, “Builds draaien via npm run build,” is een feit en hoort in CLAUDE.md. Tien stappen voor “hoe we het project publiceren” vormen een procedure en horen in een skill.

Een praktisch principe: draag iets over als je het meer dan een paar keer doet. Leg bijvoorbeeld één keer uit hoe je een wekelijks klantverslag samenstelt, zet die uitleg om in een skill en je hoeft het niet nog eens uit te leggen. De skill staat klaar zonder context in te nemen en kan bij naam worden aangeroepen met een opdracht zoals /otchet.

Dingen die nuttig zijn om naar skills te verplaatsen:

• Procedures met meerdere stappen (publiceren, een verslag samenstellen, controles vóór een release).
• Lange instructies die je zelden nodig hebt, maar dan wel volledig.
• Alles wat je voor de tweede of derde keer van de ene chat naar de andere kopieert.

Er is ook een tussenoplossing: regels die alleen voor een bepaalde map gelden. Als een instructie slechts voor één deel van een project belangrijk is, kun je die in .claude/rules/ zetten en aan de relevante bestanden koppelen. Dan wordt ze alleen geladen wanneer Claude met die bestanden werkt, in plaats van voortdurend in de context te blijven.

Wat is automatisch geheugen en waarom gebruik je het in 2026?#

Het tweede nieuwe mechanisme dat CLAUDE.md ontlast, is automatisch geheugen. Het idee is dat Claude nu niet alleen onthoudt wat je hebt opgeschreven, maar ook wat het zelf heeft opgemerkt. Een aparte gids, “Claude-geheugen versus CLAUDE.md”, legt uit hoe de werking ervan verschilt van CLAUDE.md.

Het verschil tussen de twee soorten geheugen:

Zo werkt het: terwijl Claude aan je taak werkt, merkt het nuttige details op—welk commando de build uitvoert, waar het debuggen vastliep, wat je vroeg om anders te doen—en slaat die op in zijn notities. In de volgende sessie haalt het ze weer op. Belangrijk: het slaat selectief op en bewaart alleen wat het nuttig acht voor later.

De notities staan in een aparte map voor elk project, met een indexbestand dat MEMORY.md heet. Je kunt ze bekijken en bewerken met de opdracht /memory. Het zijn gewone tekstbestanden, dus je kunt ze op elk moment lezen, bewerken of verwijderen.

Wat dit in de praktijk voor je verandert: Claude legt nu een deel vast van wat je na elke fout zelf aan CLAUDE.md toevoegde. Daardoor wordt je regelsbestand nog korter—and dat is goed.

Waarom gaat Opus 5 tegen je instructies in?#

Er is ook een keerzijde.

Een model dat de ruimte krijgt om zelf te oordelen, zal per definitie soms een rigide opdracht afwijzen wanneer het in de context een betere optie ziet.

Wat dit voor jou betekent als je naar Opus 5 bent overgestapt en er iets misgaat:

1. Controleer je oude skills en plugins opnieuw. Configuraties voor eerdere modellen kunnen botsen met de nieuwe logica. Iets wat vroeger als een klok liep, moet je nu opnieuw testen.
2. Schrap de meest rigide formuleringen. Modellen van de vijfde generatie kunnen minder goed overweg met opdrachten als “doe X nooit, doe altijd alleen Y” dan met flexibele formuleringen die uitleggen waarom.
3. Let op plekken waar het model te vroeg stopt. Soms wijst dit erop dat een instructie zichzelf tegenspreekt of botst met een regel in een overvolle CLAUDE.md.

CLAUDE.md herschrijven voor Opus 5: stap voor stap#

Zo pak je een CLAUDE.md aan die je van eerdere modellen hebt overgenomen.

1. Voer de ingebouwde controle uit

   Typ claude doctor in het project. De controle stelt voor wat je uit het overvolle bestand kunt verwijderen en wat je kunt behouden.

2. Verwijder het vanzelfsprekende

   Verwijder elke regel die Claude uit de code zelf kan afleiden: de mappenstructuur, de lijst met bibliotheken en algemene formuleringen zoals “schrijf schone code”.

3. Verwijder tegenstrijdigheden

   Loop het bestand van boven naar beneden door en zoek regels die elkaar tegenspreken. Behoud er één en verwijder de tegenstrijdige regel.

4. Verplaats procedures naar skills

   Verplaats alles wat van een feit is veranderd in een stapsgewijze instructie naar een aparte skill. Laat in CLAUDE.md een link van één regel achter.

5. Maak de overgebleven regels specifiek

   Formuleer elke regel zo dat je hem kunt controleren: “formatteer het goed” wordt “gebruik een inspringing van 2 spaties”.

6. Schakel automatisch geheugen in en controleer de lengte

   Controleer of automatisch geheugen werkt (/memory) en het bestand minder dan 200 regels telt. Zo niet, dan is er nog iets dat verplaatst moet worden.

Laat Claude het werk doen om de eerste opschoonronde niet met de hand uit te voeren. Hier is een prompt die je als uitgangspunt kunt gebruiken—kopieer hem en plak hem in een sessie die in je project is geopend:

Lees mijn CLAUDE.md en mijn code. Jouw taak is om CLAUDE.md korter en nuttiger te maken voor een model van de vijfde generatie.

Loop het bestand door en verdeel alle regels in drie groepen:

KEEP - projectspecifieke valkuilen en conventies die je niet zelf uit de code kunt afleiden.

DELETE - voor de hand liggende dingen die je al weet, en alles wat uit de code kan worden afgeleid.

MOVE TO A SKILL - procedures met meerdere stappen die nu als tekst in CLAUDE.md staan.

Formuleer voor groep 1 vage regels opnieuw zodat ze concreet en controleerbaar zijn.
Zoek regels die elkaar tegenspreken en vermeld ze afzonderlijk.
Geef een nieuwe versie van CLAUDE.md van minder dan 200 regels terug, plus een lijst van wat je naar skills voorstelt te verplaatsen.
Wijzig geen bestanden voordat ik dat bevestig.

Let op de laatste regel: “Wijzig niets voordat ik dat bevestig.” Bij een model dat nu zijn eigen oordeel gebruikt, is het belangrijk dat het eerst een plan laat zien en de beslissing aan jou laat.

Waarom is context belangrijker dan de prompt?#

Als je de details over Opus 5 even opzijzet en naar het grotere geheel kijkt, draait deze hele analyse om één idee: context is belangrijker dan de prompt. Het belangrijkste werk gebeurt vóór het verzoek—wanneer je de omgeving samenstelt waarin het model gaat werken.

CLAUDE.md, skills en automatisch geheugen zijn allemaal onderdelen van één geheel: wat Claude ziet voordat je je eerste bericht verstuurt. Je kunt de formulering van je verzoek eindeloos aanpassen, maar als de context slecht in elkaar zit—een overvolle CLAUDE.md, tegenstrijdige regels, geen structuur—blijven de resultaten inconsistent.

Een eenvoudige controle: zonder een eerste brein helpt een tweede brein niet. Met “tweede brein” bedoelt dit artikel de kennisstructuur over een project die het model bij elk verzoek leest. Maar die werkt alleen als jij de taak zelf helder begrijpt. Een tool versterkt je denken, en daar eindigt zijn rol.

De update van Opus 5 heeft deze logica aangescherpt. Anthropic liet met zijn eigen werk zien dat extra regels alleen maar nadelig zijn wanneer het model slim genoeg is, en dat degene die de context zorgvuldig heeft samengesteld in het voordeel is. Dit is een vaardigheid die je meeneemt naar elk volgend model, of dat nu Opus 6 is of iets anders.

Waar begin je nu?#

Stel het niet uit tot “ooit”. De eenvoudigste eerste stap is om CLAUDE.md nu meteen te openen en jezelf eerlijk bij elke regel af te vragen: is dit een valkuil die Claude niet kan afleiden, of een vanzelfsprekendheid die ik voor de zekerheid heb toegevoegd? Alles in de tweede groep komt in aanmerking om verwijderd te worden.

Loop het bestand daarna door met de prompt uit de bovenstaande sectie, verplaats lange procedures naar skills en controleer of automatisch geheugen is ingeschakeld. Eén avond werk en je context wordt een beknopte, nauwkeurige basis voor het model.

Je kunt dit toepassen op een echt project van jezelf: CLAUDE.md, een tweede brein en skills voor je taken.

Maak kennis met Ailoot.