Claude Code best practices: plannen, contextoverdracht, TDD

Claude Code beloont een soort discipline waar de meeste ontwikkeltools niet om vragen. Als je het al een tijdje gebruikt, heb je gemerkt dat sommige sessies precies opleveren wat je wilt, terwijl andere door tokens heen branden zonder resultaat. Anthropic’s eigen team ontdekte dat ongeleide pogingen ongeveer 33% van de tijd slagen, en de maker van de tool breekt 10–20% van de sessies af. 

Het verschil zit ’m in de patronen die je om de tool heen bouwt, niet in de prompts die je erin typt.

Dit artikel laat zien hoe die patronen er in de praktijk uitzien, gebaseerd op productieworkflows bij bedrijven als Abnormal AI, incident.io en Trail of Bits. 

Heb je een opfrisser nodig over setup en kernfeatures, dan vind je alles in onze gids over Claude Code 2.1. Hier gaan we ervan uit dat je de basis al kent en meer uit de tool wilt halen.

Voor een breder beeld van hoe agenten redeneren en waar de patronen uit deze tutorial in passen, raad ik je sterk aan om je in te schrijven voor onze AI Agent Fundamentals-track, die alle onderliggende principes behandelt.

Waarom planningsdiscipline alles verandert

Elke beslissing die Claude zonder sturing neemt, kan op zichzelf een hoge nauwkeurigheid hebben. Klinkt prima voor één keuze, maar over een feature met veel beslismomenten heen neemt de kans op een volledig juiste uitkomst snel af. Ga je uit van 80% nauwkeurigheid voor 20 beslissingen, dan krijg je 0,8^20: dus slechts zo’n 1% kans op een volledig correcte implementatie.

Planning vouwt die 20 ambigue beslissingen samen tot een gereviewde specificatie, waarbij elke keuze dicht bij 100% uitkomt omdat jij de knoop al hebt doorgehakt.

Plannen met de annotatiecyclus-workflow

De planningsworkflow die het best op schaal werkt, is een annotatiecyclus, zoals Boris Tane voorstelt. Je laat Claude een plan.md opstellen, opent het in je editor en voegt inline notities toe op plekken waar Claude de verkeerde keuze maakte of iets vaag liet: "gebruik drizzle:generate, niet raw SQL" of "dit moet PATCH zijn, niet PUT." 

Daarna stuur je het geannoteerde plan terug met de guardzin "address all notes, don't implement yet." Die guardzin is belangrijk, want zonder die instructie slaat Claude het plan over en begint meteen te coderen. Je herhaalt deze cyclus totdat alle ambiguïteit verdwenen is. Dan pas implementeert Claude, met veel minder foute afslaanmomenten, omdat alle keuzes vooraf zijn gemaakt.

# plan.md — annotation cycle
 
## Step 3: Database migration
Create a new migration for the users table.
> NOTE: use drizzle:generate, not raw SQL
> NOTE: add created_at with default NOW()
 
## Step 4: API endpoint
Add PUT /users/:id endpoint.
> NOTE: this should be PATCH, not PUT. Partial updates only.
 
# After annotating, send back with:
# "address all notes, don't implement yet"

Planmodus in Claude Code gebruiken

Voelt een annotatiecyclus te zwaar, dan is Claude Code’s ingebouwde planmodus een lichtere optie: 

1. Druk twee keer op Shift+Tab.
2. Werk het plan iteratief bij in de conversatie.
3. Schakel over naar auto-accept met één keer Shift+Tab. 

Plannen worden opgeslagen in ~/.claude/plans/, dus ze overleven compaction en herstarts van sessies. Dat maakt planmodus een solide default voor de meeste taken. Voor hele grote features werkt een volledige specificatie vooraf ook goed: een ontwikkelaar besteedde twee uur aan een 12-stappen-spec en bespaarde naar schatting 6–10 uur implementatietijd. 

Plannen verder doortrekken

Welke aanpak je ook kiest: goed open-sourcevoorbeeldcode naast je planverzoek plakken verbetert de output merkbaar, omdat Claude beter werkt met een werkende referentie dan met abstracte beschrijvingen.

Planning schaalt ook horizontaal via git worktrees. Engineers bij incident.io draaien 4–5 parallelle Claude-sessies op aparte branches, elk met een eigen plan. Eén engineer gaf $8 uit aan Claude-tegoed en leverde een implementatie op die de API-generatietijd met 18% verbeterde, goed voor 30 seconden winst op een tool die het hele team dagelijks gebruikte. 

Sommige developers gaan nog verder en laten concurrerende worktrees verschillende benaderingen van hetzelfde probleem implementeren om de resultaten te vergelijken.

Best practices voor CLAUDE.md-architectuur

Je CLAUDE.md-bestand heeft een budget waar je waarschijnlijk geen weet van hebt. HumanLayer’s analyse van de interne werking van Claude Code laat zien dat het systeem boven je instructies een reminder injecteert: "This context may or may not be relevant to your tasks." 

Claude Code’s gelaagde instructiesysteem begrijpen

Claude filtert actief wat het opvolgt, in plaats van alles als blijvende commando’s te behandelen. Bovendien volgen frontier thinking-modellen ruwweg 150–200 instructies voordat de naleving afneemt, en de systeemprompt van Claude Code neemt daar zo’n 50 van in. Dat laat ongeveer 100–150 slots over voor jouw regels. HumanLayer houdt het eigen bestand onder 60 regels.

Je kunt dit budget aan het werk zien. Voeg een regel toe aan je CLAUDE.md met "always address me as Mr. Tinkleberry" en kijk hoe snel Claude ermee ophoudt—meestal binnen een paar duizend tokens. Zodra de naam verdwijnt, zijn je instructies door het attentiemechanisme gedeprioriteerd, en verliezen ook de andere regels in je CLAUDE.md invloed.

Progressive disclosure gebruiken voor instructieverwijzingen

De manier om binnen dit budget te werken, is progressive disclosure. Je root-CLAUDE.md blijft kort en focust op regels die overal gelden. Voor domeinspecifieke zaken verwijs je naar een apart bestand zonder het inline op te nemen: "Bij werken aan het betalingssysteem: lees eerst docs/payment-architecture.md." 

Claude leest het verwezen bestand alleen wanneer het dat deel van de codebase binnengaat, zodat je instructiebudget vrij blijft voor high-priority regels. Een bedrijf dat maandelijks miljarden tokens verbruikt, structureert zijn monorepo-CLAUDE.md op deze manier, met per team een tokenbudget voor hun sectie:

# Monorepo CLAUDE.md — progressive disclosure
 
## Python
- Always use type hints for function signatures
- Test with: pytest -x --tb=short
 
## <Internal CLI Tool>
- <usage example>
- Always validate input before processing
- Never use raw SQL, prefer the ORM
For <complex usage> or <error> see path/to/<tool>_docs.md

Subdirectory-CLAUDE.md-bestanden trekken dit verder door. Zet een CLAUDE.md in src/persistence/ met databasespecifieke instructies, en een andere in src/api/ met endpointconventies. 

Claude laadt automatisch CLAUDE.md-bestanden van de werkmap omhoog tot aan de projectroot, dus subdirectory-bestanden worden alleen actief wanneer Claude in dat gebied werkt. Zo blijft je rootbestand algemeen, terwijl Claude precies daar gerichte hulp krijgt waar dat nodig is.

Een veelgemaakte fout: @-file documentatie niet in CLAUDE.md embedden. Dat voegt het hele bestand elke run in en vreet je instructiebudget op vóór de conversatie begint.

Contextbeheer in Claude Code

Claude Code geeft je 200K tokens aan context, maar het bruikbare venster is kleiner dan het lijkt. 

Een verse monorepo-sessie verbruikt ongeveer 20K tokens aan systeemprompt, tooldefinities en CLAUDE.md voordat je iets hebt getypt. Elke MCP-server voegt toolschema’s toe die permanent context innemen, dus praktisch kun je zo’n 5–8 servers gebruiken voordat je het echte werk begint weg te drukken.

Wat dit verergert, is hoe vroeg de kwaliteit daalt. Meerdere practitioners kwamen onafhankelijk op dezelfde grens uit: laat de context niet boven 60% capaciteit komen. 

Claude’s output begint al te degraderen bij 20–40% van het venster, ruim voordat een limiet ingrijpt, omdat het attentiemechanisme eerdere instructies minder gewicht geeft naarmate de context volloopt. 

Auto-compaction treedt in werking rond 83,5%, en dat is lossig: een developer verloor 3 uur refactorwerk toen alle kennis van migratiebeslissingen halverwege de sessie werd gewist en slechts 20–30% van de details overbleef.

Het Document & Clear-patroon gebruiken

De beste verdediging is het Document & Clear-patroon. Als de context zwaar wordt: 

1. Dump je huidige plan en voortgang naar een markdownbestand

2. Voer /clear uit om de sessie te resetten

3. Begin opnieuw en laat Claude dat bestand lezen

Zo krijg je een volledig venster van 200K tokens met alleen wat jij wilt behouden—beter dan /compact, omdat jij precies bepaalt wat blijft. 

Een custom /catchup-commando maakt de overgang soepeler: na het leegmaken leest het alle gewijzigde files in de huidige gitbranch, zodat Claude zonder oude gespreksgeschiedenis weer kan oppakken waar je was gebleven.

<!-- .claude/commands/catchup.md -->
Rebuild context after a /clear. Read all files modified on the
current branch compared to main. For each file, understand the
changes made. Then summarize what's been implemented so far and
what work remains.
 
Changed files on this branch:
$ git diff --name-only main

Context overdragen met custom Claude Code-skills

Ik gebruik een /transfer-context-skill die nog een stap verder gaat. Wanneer een sessie begint te degraderen, dumpt het commando een gestructureerd overdrachtsbestand met voltooid werk, openstaande beslissingen, valkuilen om te vermijden en relevante bestands paden. De volgende sessie leest dat bestand en pakt de draad op waar de vorige sessie stopte, met alleen de relevante informatie en zonder gespreksballast.

Overige best practices om context te sparen

Je kunt ook proactief context besparen door tools lui te laden. Een project won ongeveer 15.000 tokens per sessie terug door UserPromptSubmit-hooks te gebruiken die skilldefinities pas injecteerden wanneer de prompt van de gebruiker relevante trefwoorden triggerde, in plaats van alles bij startup te pre-loaden.

De simpelste regel hierachter: één taak per conversatie. Opnieuw beginnen kost 20K tokens, niets vergeleken met het kwaliteitsverlies van een vervuilde sessie.

Claude Code-hooks als deterministische vangrails

Zelfs een goed gestructureerde CLAUDE.md wordt maar zo’n 70% van de tijd opgevolgd. Voor code-stijlvoorkeuren is dat prima. Voor veiligheidsregels als "niet naar main pushen" of "geen productiedata verwijderen" niet. Hooks dichten de kloof naar 100% door shellscripts op specifieke momenten in Claude’s workflow uit te voeren.

Er zijn twee typen die je moet kennen. Block-at-Submit-hooks draaien als PreToolUse-events en stoppen acties hard: exitcode 2 blokkeert de actie en dwingt Claude iets anders te proberen. Hint-hooks geven niet-blokkerende feedback, zoals een linter na elke edit draaien en de output terugkoppelen zonder Claude’s flow te onderbreken.

De meest uitgebreide publieke hookconfiguratie doet het volgende:

• Blokkeert rm -rf-commando’s (stelt trash voor), 

• Voorkomt directe pushes naar main, 

• Logt alle mutaties met timestamps, en 

• Draait een anti-rationalisatiepoort. 

Die poort gebruikt Haiku om Claude’s reacties te beoordelen op uitvluchten als "pre-existing issues" of "out of scope." Wanneer Claude te vroeg de vlag hijst, wijst de poort de reactie af met concrete feedback en dwingt het door te werken. Een lichtere setup draait Prettier en TypeScript-checks automatisch na elke file-edit:

{
  "hooks": {
	"PostToolUse": [
  	{
    	"matcher": "Edit|Write",
    	"hooks": [
      	{
        	"type": "command",
        	"command": "prettier --write \"$CLAUDE_FILE_PATHS\""
      	}
    	]
  	}
	]
  }
}

Eén valkuil om te vermijden: blokkeer nooit Edit of Write-tools midden in een plan. Schrijven blokkeren breekt meerstapsredeneren omdat Claude de draad kwijtraakt. Laat het schrijven afronden en valideer dan via PostToolUse-hooks of pre-commit-checks. Onze Claude Code-hooks-tutorial behandelt meer patronen om op voort te bouwen.

Testgedreven ontwikkeling als optimale agentische codingstrategie

Zonder tests kan Claude zijn werk alleen toetsen met zijn eigen oordeel, dat afneemt naarmate de context voller raakt. Tests creëren een externe orakelbron die accuraat blijft, ongeacht hoe lang de sessie loopt. 

Elke rood-naar-groen-cyclus geeft Claude ondubbelzinnige feedback, en het kan de hele suite doorlopen zonder menselijke tussenkomst. Daardoor is testgedreven ontwikkeling (TDD) het sterkste patroon voor werken met agentische codingtools.

De workflow die Anthropic aanbeveelt volgt een specifieke volgorde:

1. Write tests first
   > "Write tests for the auth module using pytest.
  	TDD approach, no mock implementations."
 
2. Confirm tests fail
   > "Run the tests. They should all fail."
 
3. Commit the failing tests as a checkpoint
 
4. Implement until green
   > "Write the implementation. Do not modify the tests.
  	Keep going until all tests pass."

Die laatste instructie is belangrijker dan het lijkt. Soms past Claude tests aan om ze te laten slagen in plaats van de implementatie te repareren. De tests vooraf committen geeft je een vangnet: als Claude ze wijzigt, laat de diff precies zien wat er is veranderd en kun je terugdraaien.

Voor frontendwerk werkt een visuele variant van deze loop goed: geef Claude een designmock plus een Puppeteer MCP-server, dan maakt het na de implementatie een screenshot, vergelijkt dat met de mock en iterate. Deze verificatielus levert 2–3x kwaliteitswinst op wanneer Claude zijn eigen output kan checken tegen een visueel doel.

Claude Code: kosteneconomie en modelkeuze

Volgens Anthropic’s officiële data kost Claude Code gemiddeld $6 per ontwikkelaar per dag op API-tarieven, met 90% van de developers onder $12/dag. Omgerekend komt dat neer op zo’n $100–200 per maand per ontwikkelaar op Sonnet 4.6.

Het Max-abonnement verandert de rekensom volledig. Een ontwikkelaar trackte 8 maanden gebruik met zo’n 10 miljard tokens en kwam uit op een API-equivalente kost van meer dan $15.000, terwijl zijn daadwerkelijke Max-abonnement ongeveer $800 was: 93% besparing. 

Meer dan 90% van zijn tokens waren cache-reads, daarom hakt metered API-pricing zoveel harder in dan een vast abonnement. Het breakevenpunt voor Max ligt rond $100–200/maand aan API-equivalent gebruik—een drempel die elke dagelijkse gebruiker snel passeert.

Modelkeuze is een optimalisatie op zich. Claude Code’s "opusplan"-modus routeert Opus 4.6 voor planning en schakelt automatisch naar Sonnet 4.6 voor codegeneratie. Zo krijg je redenering op Opus-niveau waar het het meest telt, met Sonnet’s 5x goedkopere tarieven voor implementatietokens. 

In Anthropic’s interne tests werd Sonnet 4.6 door 59% van de Claude Code-gebruikers verkozen boven Opus 4.5, en het neigt naar schonere code met minder over-engineering. Voor workflows met veel subagenten laat CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929" subagenten op Sonnet draaien terwijl Opus de orkestrator blijft.

Vermijd in elk geval de drie grootste bronnen van verspilde tokens: 

• Geen context wissen tussen taken 

• Redundante file-reads door een slechte CLAUDE.md-structuur

• Vage prompts die Claude in trial-and-error-lussen sturen

Alleen al deze drie oplossen halveert doorgaans het tokenverbruik.

Claude Code: troubleshooting

Voordat we afronden, kijken we naar veelvoorkomende issues waar developers tegenaan lopen met Claude Code en hoe je ze oplost.

Contextverlies

De hardste failmodus is contextverlies. Het Document & Clear-patroon uit de contextsectie bestaat precies om die reden: laat een lange sessie nooit je enige vastlegging van beslissingen zijn. Commit vaak, dump voortgang naar files en behandel elke sessie als wegwerpbaar.

Hallucinaties bij nichetechnologieën

Claude genereert ook zelfverzekerde, plausibel ogende code voor technologieën die het niet goed kent. Werk je in een taal of framework die je niet zelf kunt verifiëren, dan heeft elke output extra controle nodig. Zoals een developer zei: "I've got myself in a PILE of trouble using LLMs with technologies I am unfamiliar with. But with something I'm familiar with, LLMs have improved my velocity massively."

Over-engineering

Over-engineering komt vaak voor. Claude schrijft extra abstracties, ongevraagde helperfuncties en te vroege refactors tenzij je anders aangeeft. "Gebruik de simpelst mogelijke aanpak" toevoegen aan je CLAUDE.md helpt, en je codebase indelen naar probleemdomeinen in plaats van technische lagen verlaagt de cognitieve belasting voor zowel Claude als mensen.

Verlies van kritieke data

De meest dramatische misser tot nu toe: tijdens het bouwen van een fonetiekapp verwijderde Claude alle fonemenaudiobestanden waarvoor een developer persoonlijk toestemming had geregeld, en verving ze door AI-gegenereerde geluiden. Het hernoemde bestanden en "raakte ervan overtuigd dat het verkeerd gelabeld had, terwijl het de relevante fonemen helemaal niet kon onderscheiden." 

De les: Commit of back-up onvervangbare bestanden altijd voordat je Claude er toegang toe geeft.

Onproductieve sessies

Anthropic’s eigen advies voor sessies die de verkeerde kant op gaan is verfrissend eerlijk: sla je state op voordat je Claude laat werken, laat het draaien en accepteer het resultaat of begin opnieuw—ga niet eindeloos zitten worstelen met correcties. 

Hoeveel je Claude met commits laat doen, hangt af van je testdekking en risicotolerantie. Sommige developers committen via slashcommando tientallen keren per dag, met PR-review als poort. Voor productiebases met betalende gebruikers is elke diff reviewen de moeite waard.

Aan de slag met Claude Code

Voor meer details is Anthropic’s Claude Code Overview hun canonieke bron waar de meeste communitycontent op voortbouwt. Wil je voortbouwen op wat we hier hebben behandeld en hands-on ervaring opdoen met verschillende Claude Code-features, bekijk dan deze tutorials:

• Claude Code 2.1 Guide — bekijk wat er nieuw is in versie 2.1, doorloop de setup van Claude Code en voer een reeks gerichte experimenten uit
• Claude Code Hooks Tutorial — ga dieper in op hook-gebaseerde automatisering en leer hoe je ze inzet voor taken als testen, formatteren en notificaties
• Using Claude Code With Ollama Local Models — draai GLM 4.7 Flash lokaal met Claude Code en Ollama om vendor lock-in en datatransfer naar de cloud te vermijden
• How to Build Claude Code Plugins — ontdek hoe je extensies installeert, kiest tussen skills en MCP’s, en een custom sessieloggerplugin bouwt
• Claude Code Docker — leer Claude Code in Docker draaien voor geïsoleerde omgevingen, en beheers veilige codingpraktijken voor AI-agenten
• Claude Code Router — ontdek hoe je Claude Code Router gebruikt om met meerdere modelproviders te verbinden en voor elke taak het juiste LLM in te zetten

Verschillende open-sourceprojecten bundelen ook de praktijken uit dit artikel in kant-en-klare configuraties:

• obra/superpowers — een composeerbaar skillsframework met TDD-handhaving, Socratisch brainstormen, fijnmazige planning en automatische code review tussen taken. Nu een officiële plugin in Anthropic’s marketplace.

• github/spec-kit — GitHub’s officiële Spec-Driven Development-toolkit. Structureert werk als Constitution → Specify → Plan → Tasks, waarbij de spec de single source of truth is voor elke codingagent.

• bmad-code-org/BMAD-METHOD — een volledig agile framework met 12+ agentpersonas (Architect, QA, Scrum Master) en 34+ workflows over de hele ontwikkelcyclus.

• wshobson/commands — 57 production-ready slashcommando’s die je zo in .claude/commands/ kunt droppen, inclusief 15 multi-agentworkflows.

• awesome-claude-code — de toonaangevende directory van skills, hooks, commando’s, agenten en plugins. Begin hier als je wilt verkennen wat er is.

Conclusie

Elk patroon in dit artikel wijst op hetzelfde idee: zet Claude vóór uitvoering strak in kaders en geef het daarna een manier om de eigen output te verifiëren. Planning haalt ambiguïteit weg. CLAUDE.md en hooks zetten grenzen. Tests bieden verificatie. Contexthygiëne houdt alles werkend over sessies heen.

Kies je één verandering om mee te beginnen, maak het dan Document & Clear. De kosten van contextrot over sessies wegen ruimschoots op tegen de 20K tokens die opnieuw starten kost. Daarna:

• Voeg een pre-commit-hook toe die commits blokkeert als tests falen

• Begin elke multifiletask met een plan vóórdat je code aanraakt

• Houd je CLAUDE.md onder 100 instructies en gebruik subdirectory-bestanden voor domeinspecifieke regels

We hebben onlangs een nieuwe skilltrack toegevoegd over AI Engineering with LangChain. De cursusinhoud is AI-native, zodat je kunt leren met je persoonlijke tutoragent aan je zijde. Aanrader als je een echte pro wilt worden in het engineeren van AI-workflows.