Deel D · Module 02
Werkwijzen
Hoe werk je met agents: TDD, spec-first, plan-driven?
Leerdoelen
Na deze module kun je:
- voor een taak een werkwijze kiezen (verkennen en plannen, spec-first, test-first, schrijver/reviewer) en de momenten aanwijzen waarop jij beslist;
- "klaar" verifieerbaar maken: een check die pass of fail teruggeeft, en kiezen hoe strikt die wordt afgedwongen;
- een prompt en een CLAUDE.md schrijven die alleen bevatten wat Claude niet zelf kan vinden.
Voorkennis-check
Twee vragen over hooks en context. Fout? Lees C2 Hooks en C1 Sturen eerst terug.
Waar zitten we?
Werkwijzen horen bij laag 5: hoe mensen en agents samenwerken. Ze gebruiken de mechanismen uit deel C (plan mode, hooks, subagents), maar de keuze voor wanneer een mens beslist, is een afspraak in je team, geen instelling.
De stof in drie lagen
Kern ± 5 min lezen, daarna vier werkwijzen doorlopen
De docs van Claude Code beginnen hun best practices met een geruststelling: in de meeste gevallen doet je eerste gewone prompt al het juiste. Als een sessie toch misgaat, is het bijna altijd één van vier dingen:
- Claude bouwde iets anders dan je bedoelde: het mist informatie die niet in de repo staat. Vertel het wat het niet kan zien.
- Claude zei dat het klaar was, maar dat was het niet: het had niets om het te controleren. Geef het een check die pass of fail teruggeeft.
- Claude deed iets wat nooit mag, of sloeg iets over wat altijd moet. Dwing het af (C2).
- Het klopte, maar het kostte meer tijd, tokens of prompts dan de taak waard was. Pas een standaard aan (D5).
Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually is done, "looks done" is all it has to go on.
Een werkwijze is een vaste volgorde die die vier punten regelt, met een paar bewuste checkpoints waarop jij beslist. Niet bij elke stap, want dan ben jij de bottleneck. Wel op de plekken waar een fout het duurst is om later te herstellen: de richting (plan, spec, test) en de merge. Doorloop hieronder vier werkwijzen.
Samengevat: leg de richting vast vóór er code is (plan, spec of test), geef Claude iets wat het zelf kan draaien om "klaar" te bewijzen, laat iemand die niet meeschreef reviewen, en houd de merge bij een mens.
Verdieping deterministisch of niet, wat je opschrijft, de verificatieladder
Twee soorten instructies
Elke instructie is óf iets wat het model leest en meeweegt, óf iets wat de harness afdwingt (C2). De best practices zetten ze per onderwerp naast elkaar:
| Claude beslist | Claude Code dwingt af | |
|---|---|---|
| Wat te doen | prompt, CLAUDE.md, skills die Claude zelf kiest | hooks, skills die alleen jij kunt starten |
| Wat het mag aanraken | de classifier van auto mode | deny-regels, sandbox, managed settings |
| Wanneer het klaar is | vragen om bewijs, /goal, /code-review | tests, typecheck, een Stop-hook, CI |
| Hoeveel het uitgeeft | effort-niveau, eigen tempo | --max-turns, --max-budget-usd met -p, een spend limit |
| Wie het laatste woord heeft | Claudes samenvatting van wat het deed | branch protection, een mens die de merge goedkeurt |
Meestal wil je dat Claude beslist: met de code voor zich weegt het een richtlijn vaak beter af dan een regel die je vooraf schreef. Afdwingen is voor wat altijd of nooit moet.
If you keep adding emphasis to a
CLAUDE.mdline and Claude still misses it, that's a sign the line belongs in a hook. The reverse holds too: if you have hooks for things that are only preferences, delete them and let Claude decide.
Vertel wat het niet kan zien
Only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session.
Claude leest je code snel en goed: layout, conventies, testframework. Wat het niet kan vinden: een besluit uit een overleg, een deployproces dat in iemands hoofd zit, de omgevingsvariabele die integratietests nodig hebben. Een goede toets: zou Claude het kunnen vinden door de code te lezen, en zou het dat ook doen? Twee keer ja: laat het weg.
| In plaats van | Probeer |
|---|---|
| "fix the login bug" | "users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it" |
| "add a calendar widget" | "follow the pattern in HotDogWidget.php and build a calendar widget that lets you pick a month and page between years. no new libraries" |
Weet je nog niet precies wat je wilt? Laat Claude je dan interviewen tot er een spec ligt (zie de werkwijze "Spec-first"). Wil je de uitgebreide versie in plaats van de kleinste die werkt, zeg dan "be ambitious".
De verificatieladder
Van "Claude beslist" naar "Claude Code dwingt af":
- In de prompt: "draai de auth-tests en ga door tot ze slagen". Werkt meteen, zonder setup.
- Als doel:
/goal all tests in tests/auth pass and lint is clean. Een apart model controleert na elke beurt of het doel gehaald is. Vooral nuttig bij lange achtergrondruns. - Als Stop-hook: de beurt eindigt pas als je script met 0 afsluit (bij exit 2 werkt Claude door). Afgedwongen.
- Door iemand die niet meeschreef:
/code-reviewlaat een verse subagent de diff beoordelen.
Vraag bij elke variant om bewijs: het commando en de output, of de screenshot. "Alle tests slagen" zegt weinig; output lezen is sneller dan alles zelf opnieuw draaien.
Don't drop the
skip stylepart of that prompt. A reviewer that's asked to find problems will always find something.
Onder de motorkap plan mode, onbewaakte runs, wat je kunt laten
Plan mode
Met Shift+Tab (tot de statusbalk ⏸ plan mode on toont) of --permission-mode plan leest Claude bestanden en draait het alleen-lezen-commando's, maar het wijzigt niets tot jij het plan goedkeurt. Het plan zelf wordt naar schijf geschreven, en na compaction wordt het opnieuw ingevoegd (B4).
Runs zonder jou
Voor een run die niemand bekijkt (CI, een cronjob, claude -p) gelden dezelfde vier punten, maar strenger. Er is niemand om bij te sturen, dus:
- Weet het wat klaar is? Een goal, een spec-bestand of een falende test die groen moet worden.
- Grenzen:
--max-turnsen--max-budget-usdbegrenzen een-p-run. - Afgedwongen checks: Stop-hook of CI, want "ga door tot het klaar is" in de prompt is in een onbewaakte run je enige vangnet.
- Bewijs in de output: voor een sessie die je niet zag, is het commando met de output het enige bewijs dat je hebt.
Wat je kunt laten (uit de docs)
| Oud advies | Waarom het weg kan |
|---|---|
| IMPORTANT of HOOFDLETTERS bij instructies die Claude mist | huidige modellen volgen een gewoon geformuleerde regel; extra nadruk laat ze de regel juist te breed toepassen. Kan de regel echt niet buigen: hook of deny-regel. |
| "think hard", "be thorough" in de prompt | effort is de knop daarvoor; zulke zinnen zijn gewone prompttekst |
| "ga door tot het klaar is, wees niet lui" | leidt eerder tot overwerk; geef liever een check om te halen |
| architectuur en mappenstructuur in CLAUDE.md beschrijven | Claude leest de repo zelf |
| delegeren aan een subagent voor een beter antwoord | delegeren maakt het antwoord niet beter; een verse reviewer helpt omdat hij jouw redenering niet zag |
Uitgewerkt voorbeeld: test-first met een afgedwongen check
Een bug: korting wordt naar beneden afgerond in plaats van half-up. In drie berichten en één hook:
Bericht 1: alleen de test
write a failing test in tests/test_prijs.py that shows korting(999, 15) should be 849
(half-up rounding). don't change any non-test code yet. run it and show me the failure.
- Eerst de test: die legt vast wat "goed" is, in code die pass of fail teruggeeft.
- Nog geen fix: zo kun jij de test lezen voordat hij de maatstaf wordt. Dit is het checkpoint dat telt.
.claude/settings.json: de check wordt afgedwongen
{ "hooks": { "Stop": [ { "hooks": [ { "type": "command",
"command": "python3 -m unittest -q 1>&2 || exit 2" } ] } ] } }
- Stop-hook: wil Claude zijn beurt beëindigen terwijl er tests falen, dan gaat de testoutput (stderr) als reden terug en werkt Claude door. Er zit een limiet op het aantal blokkades achter elkaar, zodat het niet eindeloos doorgaat.
Bericht 2 en 3
the test is right. now fix korting() so it passes. don't edit the tests.
/code-review
- De test is de spec: een agent die de test aanpast tot hij groen is, heeft niets opgelost. Zeg het, of blokkeer edits in
tests/met een PreToolUse-hook als het echt nooit mag.
Spec-first: van vaag idee naar een geverifieerde feature
Gebruik oefenrepo/c4-subagents/ (prijsmodule met tests). Je voegt een feature toe: kortingscodes.
Opdracht
- Start
claudeen zeg: "I want to add discount codes to winkel/prijs.py but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md." Beantwoord de vragen. - Lees
SPEC.md. Klopt het met wat je bedoelde? Pas aan waar nodig. Dit is checkpoint 1. - Voeg de Stop-hook uit het voorbeeld toe aan
.claude/settings.json. /clear. Zeg: "Build the feature described in SPEC.md, test-first. Show me the failing tests before implementing." Lees de tests: checkpoint 2.- Laat het bouwen. Vraag daarna: "use a subagent to review the diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style".
- Maak het kapot. Haal "and skip style" weg en vraag opnieuw om een review. Wat is het verschil in bevindingen?
Verwacht resultaat
Stap 1–2: meerkeuzevragen over bijvoorbeeld procentuele tegenover vaste korting, stapelen met de bestaande korting, hoofdlettergevoeligheid, ongeldige codes. SPEC.md bevat eisen en randgevallen.
Stap 4: nieuwe, falende tests vóór de implementatie. Je ziet ze eerst rood.
Stap 5: een korte lijst gaten ten opzichte van de spec (bijv. een randgeval zonder test), of "geen gaten". Tijdens het bouwen kon Claude zijn beurt niet afsluiten met falende tests: dat zie je aan de hook-meldingen in het transcript.
Stap 6: zonder "skip style" komen er meer bevindingen, vaak stijl en hypothetische randgevallen. Precies waarom de docs zeggen: een reviewer die iets moet vinden, vindt altijd iets.
Als het niet werkt, kijk naar …
- Claude interviewt niet, maar begint te bouwen. Herhaal dat je eerst vragen wilt, of zet plan mode aan (
Shift+Tab). - Stop-hook doet niets. Staat hij onder
"Stop"(nietPostToolUse)? Draaitpython3 -m unittest -qvanuit de projectroot? Bekijk/hooks. - Claude blijft hangen in de Stop-hook. Een test die niet groen kán worden, blokkeert elke stop. Na een aantal opeenvolgende blokkades grijpt Claude Code in; repareer de test of haal de hook tijdelijk weg.