Werken met Claude Code: Complexe Projecten

Je hebt een monorepo met 340 bestanden. De API-laag gebruikt een verouderd foutafhandeling-patroon — try/catch blokken die foutcodes als strings returnen in plaats van je custom AppError class te gooien. Het patroon zit in 47 bestanden verspreid over zes directories. Je opent Claude Code en typt: “Refactor alle error handling in de API naar het AppError-patroon.”

Claude begint enthousiast. Het leest de eerste vijf bestanden, past ze aan, leest er drie, past er twee aan, leest er tien, en ergens halverwege de sessie begint de kwaliteit te dalen. De context loopt vol. Claude vergeet het patroon dat het in de eerste bestanden heeft toegepast. De zesendertigste aanpassing is inconsistent met de vijfde. Je zit met een half-gerefactorde codebase.

De les is niet dat Claude Code geen grote refactorings aankan. De les is dat grote refactorings een strategie vereisen.

Multi-file refactoring: de juiste aanpak

Een refactoring die tientallen bestanden raakt werkt met Claude Code wanneer je drie principes volgt.

Principe 1: Eerst het patroon vaststellen

Voordat je Claude Code begint te laten schrijven, stel je het doelpatroon vast.

> Lees src/services/order.ts en src/services/billing.ts.
> Beide gebruiken het oude error-patroon met string-codes.
> Lees src/services/auth.ts — dat gebruikt al het nieuwe AppError-patroon.
> Beschrijf het verschil tussen het oude en het nieuwe patroon,
> en formuleer een migratieregel die ik kan toepassen op alle
> services.

Claude analyseert de drie bestanden en produceert een beschrijving:

Oud patroon:
- try/catch met return { error: "ORDER_NOT_FOUND" }
- Caller checkt if (result.error) ...

Nieuw patroon (AppError):
- throw new AppError("ORDER_NOT_FOUND", 404, "Order niet gevonden")
- Error wordt gevangen door de globale error handler in src/middleware/errorHandler.ts
- Caller hoeft geen error-checks te doen

Migratieregel:
1. Vervang return { error: "..." } door throw new AppError(...)
2. Verwijder if (result.error) checks bij de caller
3. Voeg import { AppError } from '../errors' toe als die ontbreekt

Nu heb je een expliciete migratieregel. Die regel is je referentie voor de rest van de refactoring.

Principe 2: Batch per directory

Werk niet door 47 bestanden in één sessie. Splits de refactoring op in batches die logisch bij elkaar horen.

> Pas de AppError-migratieregel toe op alle bestanden in
> src/services/. Doe ze één voor één. Toon na elk bestand
> de wijziging zodat ik kan verifiëren.

Eén directory per sessie. Na de services draai je de tests:

> Run npm test -- --testPathPattern=services

Pas na succesvolle tests ga je door naar de volgende directory. Dit voorkomt dat fouten zich opstapelen over de hele codebase.

Principe 3: Verifieer na elke batch

Na elke batch drie checks:

1. Tests. Draaien alle tests die gerelateerd zijn aan de gewijzigde bestanden?
2. Consistentie. Volgen de wijzigingen dezelfde migratie-regel als de vorige batch?
3. Typecheck. Zijn er TypeScript-fouten geïntroduceerd door de wijzigingen?

> Run deze drie checks:
> 1. npm test -- --testPathPattern=services
> 2. npx tsc --noEmit
> 3. Vergelijk de wijziging in src/services/order.ts met die in
>    src/services/notification.ts — is het patroon identiek?

Claude draait de tests, controleert de types en vergelijkt de patronen. Dit is het verschil tussen een gecontroleerde refactoring en een gok.

Sub-agents voor parallelle taken

Claude Code kan sub-agents spawnen. Een sub-agent is een zelfstandige Claude-instantie die een deeltaak uitvoert met een eigen context. Het model beslist zelf wanneer een sub-agent nuttig is, maar je kunt het ook expliciet vragen.

Wanneer sub-agents helpen

Sub-agents zijn nuttig voor taken die parallel kunnen draaien en onafhankelijk van elkaar zijn:

> Ik wil drie dingen weten:
> 1. Welke dependencies in package.json zijn verouderd?
> 2. Welke functies in src/services/ hebben geen unit tests?
> 3. Hoeveel TODO-comments staan er in de codebase?
> Gebruik sub-agents om deze drie vragen parallel te beantwoorden.

Claude spawnt drie sub-agents. Elk onderzoekt een vraag onafhankelijk. De resultaten komen terug in de hoofdsessie.

Dit is sneller dan de vragen sequentieel beantwoorden, omdat sub-agents parallel draaien. Voor verkennende taken — “geef me een overzicht van X, Y en Z” — besparen sub-agents reële tijd.

Wanneer sub-agents niet helpen

Sub-agents werken slecht voor taken die van elkaar afhangen:

> Sub-agent 1: Refactor de UserService
> Sub-agent 2: Update alle tests die UserService gebruiken

Dit gaat fout. Sub-agent 2 kent de wijzigingen van sub-agent 1 niet, want ze hebben een eigen context. De tests worden geüpdatet op basis van de oude interface. Afhankelijke taken moeten sequentieel, in dezelfde sessie.

De vuistregel: parallel voor verkenning, sequentieel voor mutatie.

Van prototype naar productie

Claude Code is uitstekend voor prototyping. Een werkend prototype in een middag is realistisch. De overgang naar productie is waar de meeste teams struikelen.

Wat Claude Code goed doet bij prototyping

• Snel een werkende structuur opzetten.
• Boilerplate genereren (routes, models, types, configuratie).
• Itereren op de interface (endpoint signatuur, response-formaat) zonder veel handwerk.
• Mocking en seed-data genereren voor demonstraties.

Wat productie-ready maken vergt

Error handling die alle paden dekt. Een prototype gooit een generieke error en gaat door. Productie-code behandelt elke faalmode expliciet. Claude Code kan dit doen, maar je moet er specifiek om vragen:

> De createOrder-functie behandelt het happy path. Voeg error
> handling toe voor: database-connectie faalt, gebruiker bestaat
> niet, voorraad onvoldoende, betaling mislukt. Gebruik het
> AppError-patroon en retourneer specifieke HTTP-statuscodes.

Logging die debugging ondersteunt. Prototypes loggen naar stdout. Productie-code logt gestructureerd met context. Vraag Claude expliciet om logging toe te voegen met request-IDs, gebruikers-context en actie-beschrijvingen.

Performance-bewustzijn. Claude Code optimaliseert niet voor performance tenzij je daarom vraagt. Een query die werkt op tien rijen maar traag is op een miljoen rijen wordt niet vanzelf gesignaleerd. Vraag expliciet:

> Review de getOrders query. Zal deze query performen bij 100.000
> orders? Welke indexen zijn nodig?

Security-review. Claude Code introduceert zelden bewust kwetsbaarheden, maar mist soms subtiele issues: SQL-injection via string-concatenatie in plaats van parameterized queries, ontbrekende input-validatie, hardcoded credentials in configuratiebestanden.

> Doe een security-review van src/api/auth.ts. Check specifiek:
> SQL-injection, XSS, ontbrekende input-validatie, hardcoded secrets.

De overgang van prototype naar productie is niet één stap. Het is een checklist die je per domein doorloopt — error handling, logging, performance, security, monitoring — en Claude Code kan elk domein adresseren als je het expliciet aanstuurt.

Wanneer Claude Code de juiste tool is

Claude Code presteert het best bij:

Werken in een bestaande codebase. Claude Code leest je project, begrijpt je patronen, en volgt je conventies. Hoe meer context er is, hoe beter het model presteert.

Iteratief bouwen. Stap voor stap een feature toevoegen, testen, bijsturen. Het voorstel-review-accept ritme past bij hoe software groeit.

Refactoring met een duidelijk patroon. Wanneer het doelpatroon helder is en de wijzigingen mechanisch zijn, doet Claude Code in een uur wat handmatig een dag kost.

Verkenning van onbekende code. “Leg uit hoe de authenticatie-flow in dit project werkt” — Claude leest de relevante bestanden en geeft een overzicht dat je handmatig zou moeten puzzelen.

Boilerplate en herhaling. Tests schrijven voor bestaande functies. Migraties genereren op basis van schema-wijzigingen. CRUD-endpoints toevoegen die het bestaande patroon volgen.

Wanneer Claude Code niet de juiste tool is

Architectuurbeslissingen op hoog niveau. Claude Code kan je helpen een architectuur te implementeren. Het kan je niet vertellen welke architectuur de juiste is voor je specifieke product, team en groeistrategie. Die beslissing vereist context die buiten de codebase leeft.

UX- en design-keuzes. Claude Code kan een component bouwen. Het kan niet beoordelen of dat component de juiste interactie biedt voor je gebruikers.

Domein-specifieke kennis die nergens in code staat. Als de business-regels in de hoofden van drie mensen zitten en niet in documentatie of code, kan Claude ze niet ontdekken.

Performance-optimalisatie van kritieke paden zonder metingen. Claude Code kan een query optimaliseren als je vertelt dat hij traag is. Het kan niet zelf identificeren welke van je honderd queries de bottleneck is — daarvoor heb je profiling-data nodig.

Werk in een codebase zonder structuur. Een project met duizend bestanden in een platte map, geen README, geen tests, en geen consistente naamgeving geeft Claude Code weinig houvast. Het model reflecteert de kwaliteit van je project. Chaos in, chaos uit.

De kern van complexe projecten

Het patroon dat door deze hele serie loopt is hetzelfde: Claude Code is een krachtig model dat zijn best doet met wat je het geeft. De kwaliteit van je output is een functie van drie variabelen:

1. De kwaliteit van je codebase. Duidelijke structuur, goede naamgeving, consistente patronen. Het model leert van je code. Hoe beter je code, hoe beter het model presteert.

2. De kwaliteit van je prompts. Intentie boven instructie. Specificiteit boven vaagheid. Verwijzingen naar bestaande patronen boven abstracte beschrijvingen.

3. De kwaliteit van je verificatie. Tests die draaien na elke stap. Type-checks. Linting. Hooks die automatisch controleren. Het model maakt fouten. Je vangnetten bepalen hoeveel die fouten kosten.

Claude Code vervangt geen vakmanschap. Het versterkt vakmanschap. Een developer die goed refactort, goed test en goed communiceert, wordt met Claude Code sneller in elk van die drie. Een developer die niet weet wat hij wil bouwen, bouwt met Claude Code sneller het verkeerde.

Dat is de fundamentele les. De tool is zo goed als de intentie erachter.

Dit is deel 5 en het laatste deel van de serie “Werken met Claude Code”. Begin bij deel 1 voor installatie en eerste stappen, of lees de individuele delen voor het onderwerp dat je nu nodig hebt.