Werken met Claude Code: Effectief Aansturen

Je opent Claude Code, typt “maak een login-pagina”, en krijgt iets terug. Het werkt, technisch. Maar het volgt geen van je bestaande patronen. Het gebruikt een andere CSS-aanpak dan de rest van je app. De error handling wijkt af. De naamgeving is inconsistent. Je kunt het fixen — maar dat kost net zoveel tijd als het zelf schrijven.

Het probleem zit niet in het model. Het zit in de prompt.

Intentie versus instructie

Er zijn twee manieren om Claude Code aan te sturen. De eerste is instructie: stap voor stap vertellen wat het model moet doen. De tweede is intentie: beschrijven wat je wilt bereiken en waarom, en het model de uitvoering laten bepalen.

Instructie ziet er zo uit:

> Maak een bestand src/pages/Login.tsx.
> Importeer React en useState.
> Maak een component met een form.
> Voeg twee input-velden toe: email en password.
> Voeg een submit-handler toe die POST naar /api/auth/login.

Intentie ziet er zo uit:

> Voeg een login-pagina toe. Gebruik dezelfde component-structuur als de
> bestaande pagina's in src/pages/. De pagina moet email en password
> accepteren en authenticeren via de bestaande auth-API in src/api/.
> Volg de error-handling patronen uit src/components/forms/.

Het verschil is substantieel. Bij instructie beslis jij de implementatie vooraf. Claude voert uit. Bij intentie beschrijf jij het doel en de constraints, en Claude leest je bestaande code om te bepalen hoe de implementatie eruitziet.

Instructie werkt wanneer je precies weet hoe iets moet en het model geen ruimte nodig heeft. Intentie werkt beter wanneer je codebase patronen bevat die het model kan volgen. En dat is bijna altijd het geval.

De vuistregel: beschrijf wat en waarom, verwijs naar bestaande patronen, laat hoe aan het model.

Goede prompts versus slechte prompts

Concrete voorbeelden maken het verschil helder.

Slecht:

> Refactor de code.

Welke code? Welke richting? Wat is het doel van de refactor? Claude gaat gokken.

Beter:

> De functies in src/utils/validation.ts dupliceren logica. Elk van de
> vier validate-functies doet dezelfde null-check en type-conversie.
> Extract de gedeelde logica naar een helper-functie en refactor de
> vier functies om die helper te gebruiken.

Slecht:

> Voeg tests toe.

Beter:

> Voeg unit tests toe voor de drie publieke functies in
> src/services/billing.ts. Gebruik het test-framework en de
> mock-patronen uit de bestaande tests in src/services/__tests__/.
> Test minstens: happy path, ongeldige input, en network error.

Slecht:

> Fix de bug op de homepage.

Beter:

> De homepage toont "undefined" als de gebruiker geen profielfoto
> heeft. Het probleem zit waarschijnlijk in src/components/Avatar.tsx
> waar user.avatarUrl wordt gebruikt zonder fallback. Voeg een default
> avatar toe die consistent is met hoe we dat in andere componenten doen.

Het patroon: localiseer het probleem, beschrijf het gewenste resultaat, verwijs naar context. Hoe specifieker je prompt, hoe minder iteraties je nodig hebt.

CLAUDE.md als projectgeheugen

In deel 1 introduceerden we CLAUDE.md als een bestand dat Claude Code automatisch leest bij sessiestart. Nu gaan we het serieus inzetten.

Een goed CLAUDE.md bestand bevat drie categorieën informatie:

1. Projectcontext

Wat is dit project? Welke stack? Welke architectuurbeslissingen zijn genomen?

## Project
E-commerce platform. Next.js 14, TypeScript, PostgreSQL via Prisma.
Monorepo met packages/api en packages/web.

## Architectuur
- API: Express in packages/api/src/
- Web: Next.js App Router in packages/web/app/
- Shared types: packages/shared/types/
- Database migraties: packages/api/prisma/migrations/

2. Conventies

Hoe schrijf je code in dit project? Welke patronen gelden?

## Conventies
- Async/await, nooit callbacks of .then() chains
- Error handling via custom AppError class (packages/api/src/errors/)
- API responses altijd via sendResponse helper (packages/api/src/utils/response.ts)
- React componenten: function components met named exports
- State management: Zustand stores in packages/web/stores/
- Geen default exports behalve Next.js pages

3. Commando’s

Hoe bouw je, test je, en run je dit project?

## Commando's
- Dev server: pnpm dev (start api + web parallel)
- Tests: pnpm test (Jest, alle packages)
- Lint: pnpm lint
- Type check: pnpm typecheck
- Database migratie: cd packages/api && npx prisma migrate dev
- Seed: cd packages/api && npx prisma db seed

Elke keer dat je een sessie start, leest Claude Code dit bestand. Dat betekent dat Claude je conventies kent voordat je ze in elke prompt hoeft te herhalen. “Voeg een nieuw endpoint toe” wordt automatisch “voeg een endpoint toe met async/await, AppError handling en sendResponse” — omdat dat in CLAUDE.md staat.

CLAUDE.md onderhouden

CLAUDE.md is een levend document. Update het wanneer:

• Je een architectuurbeslissing neemt die de standaard patronen verandert.
• Je een nieuwe conventie introduceert.
• Je merkt dat Claude steeds dezelfde fout maakt — dat is een signaal dat er context mist.

Houd het beknopt. Een CLAUDE.md van vijftig regels werkt beter dan eentje van vijfhonderd. Claude Code leest het elke sessie. Alles wat erin staat kost tokens. Wees zuinig met context, net als met code.

Het plan-patroon

De krachtigste techniek voor complexe taken is het plan-patroon. In plaats van direct te vragen om een implementatie, vraag je eerst om een plan.

> Ik wil een notificatiesysteem toevoegen. Gebruikers krijgen een
> melding wanneer hun bestelling van status verandert. Maak eerst een
> plan: welke bestanden moeten aangemaakt of gewijzigd worden, in welke
> volgorde, en waarom.

Claude antwoordt met een gestructureerd plan:

Plan:
1. Maak packages/api/src/services/notification.ts — service die
   notificaties aanmaakt en opslaat
2. Voeg NotificationChannel enum toe aan packages/shared/types/
3. Maak Prisma model Notification in schema.prisma
4. Maak migratie
5. Voeg sendNotification call toe aan de bestaande
   updateOrderStatus functie in packages/api/src/services/order.ts
6. Maak GET /api/notifications endpoint voor ophalen
7. Voeg tests toe voor notification service

Nu heb je een overzicht. Je kunt het plan beoordelen voordat er één regel code geschreven is. Zit er een stap in die je anders wilt? Ontbreekt er iets? Merk je dat Claude een bestand mist? Dit is het moment om bij te sturen — niet nadat er al zeven bestanden zijn aangemaakt.

Na goedkeuring van het plan:

> Het plan klopt. Voer stap 1 en 2 uit.

Stap voor stap door het plan werken geeft je controle zonder dat je elke regel code hoeft te dicteren. Het is de balans tussen intentie en structuur.

Wanneer context geven en wanneer Claude laten ontdekken

Een veelgemaakte fout is te veel context vooraf meegeven. Claude Code kan je project doorzoeken. Laat het dat doen.

Te veel context:

> In het bestand src/services/order.ts op regel 45 staat de functie
> updateOrderStatus. Die functie importeert OrderStatus uit
> src/types/order.ts. De functie accepteert een orderId (string) en
> een newStatus (OrderStatus). Ze roept prisma.order.update aan met
> where: { id: orderId } en data: { status: newStatus }. Ik wil dat
> je na de update een notificatie stuurt.

Je hebt zojuist informatie getypt die Claude zelf kan lezen. Dat kost jou tijd en het voegt geen waarde toe.

Juiste hoeveelheid context:

> Voeg een notificatie toe na de status-update in
> src/services/order.ts. Lees de bestaande functie en de notification
> service die we net gemaakt hebben.

Claude leest de bestanden zelf en heeft nu de actuele versie — niet jouw samenvatting van wat er staat, die inmiddels verouderd kan zijn.

De uitzondering: geef context wanneer Claude het niet zelf kan vinden. Business-regels die niet in code staan. Beslissingen die niet uit de codebase blijken. “We willen notificaties alleen bij statusverandering naar SHIPPED en DELIVERED, niet bij PROCESSING” — dat staat nergens in je code, dus dat moet je vertellen.

Sessiebeheer

Claude Code sessies leven zolang je terminal open is. Sluit je de terminal, dan verlies je de sessiecontext. Dat is een bewuste beperking — context is duur en sessies die oneindig groeien worden onbeheersbaar.

Praktische tips:

Eén feature per sessie. Start een nieuwe sessie voor een nieuwe feature. Dat houdt de context gefocust en voorkomt dat oude conversatie-elementen de nieuwe taak vervuilen.

Sluit af met een samenvatting. Voordat je een sessie afsluit, vraag Claude om een samenvatting van wat er gedaan is. Plak die samenvatting in een commit-bericht of in CLAUDE.md als het een architectuurbeslissing was.

Gebruik –print voor one-shots. Voor enkelvoudige taken die geen interactieve sessie nodig hebben:

claude --print "Welke dependencies in package.json zijn verouderd?"

Dit draait Claude Code in print-modus: het antwoordt en sluit af. Geen interactieve sessie, geen bijgehouden context. Ideaal voor snelle vragen.

Het verschil na twee weken

Na twee weken met Claude Code en een goed onderhouden CLAUDE.md merk je drie verschuivingen:

Je denkt in intentie. In plaats van “ik ga nu twintig regels boilerplate schrijven” denk je “ik beschrijf wat dit endpoint moet doen en laat Claude de boilerplate genereren.” De cognitieve last verschuift van typen naar beoordelen.

Je prompts worden korter. Omdat CLAUDE.md de basiscontext draagt, hoef je minder te herhalen. “Voeg een endpoint toe voor het ophalen van notificaties” is voldoende als je conventies in het projectgeheugen staan.

Je reviewt meer dan je schrijft. Het werkritme verschuift van schrijven naar reviewen. Claude stelt voor, jij beoordeelt. Dat is een andere vaardigheid — en een die je bewust kunt trainen.

In deel 3 kijken we naar de tools die Claude Code onder de motorkap gebruikt, het permissiesysteem dat bepaalt hoeveel vrijheid het model krijgt, en hoe je hooks instelt voor automatische acties.

Dit is deel 2 van de serie “Werken met Claude Code”. Lees deel 1 voor installatie en eerste sessie.