Deel D · Module 02

Werkwijzen

Hoe werk je met agents: TDD, spec-first, plan-driven?

Zone: mens Zone: organisatie ± 15 min kern

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:

  1. Claude bouwde iets anders dan je bedoelde: het mist informatie die niet in de repo staat. Vertel het wat het niet kan zien.
  2. 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.
  3. Claude deed iets wat nooit mag, of sloeg iets over wat altijd moet. Dwing het af (C2).
  4. 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 tegenover Claude Code dwingt af (uit de best practices)
Claude beslistClaude Code dwingt af
Wat te doenprompt, CLAUDE.md, skills die Claude zelf kiesthooks, skills die alleen jij kunt starten
Wat het mag aanrakende classifier van auto modedeny-regels, sandbox, managed settings
Wanneer het klaar isvragen om bewijs, /goal, /code-reviewtests, typecheck, een Stop-hook, CI
Hoeveel het uitgeefteffort-niveau, eigen tempo--max-turns, --max-budget-usd met -p, een spend limit
Wie het laatste woord heeftClaudes samenvatting van wat het deedbranch 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.md line 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.

Claude Code docs, Best practices

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 Code docs, Best practices

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.

Specifieke prompts (voorbeelden uit de docs)
In plaats vanProbeer
"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":

  1. In de prompt: "draai de auth-tests en ga door tot ze slagen". Werkt meteen, zonder setup.
  2. 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.
  3. Als Stop-hook: de beurt eindigt pas als je script met 0 afsluit (bij exit 2 werkt Claude door). Afgedwongen.
  4. Door iemand die niet meeschreef: /code-review laat 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 style part of that prompt. A reviewer that's asked to find problems will always find something.

Claude Code docs, Best practices, sectie "Review against your spec"
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-turns en --max-budget-usd begrenzen 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 dat de huidige modellen overbodig maakten
Oud adviesWaarom het weg kan
IMPORTANT of HOOFDLETTERS bij instructies die Claude misthuidige 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 prompteffort 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 beschrijvenClaude leest de repo zelf
delegeren aan een subagent voor een beter antwoorddelegeren 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.
  1. Eerst de test: die legt vast wat "goed" is, in code die pass of fail teruggeeft.
  2. 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" } ] } ] } }
  1. 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
  1. 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.
Doe-opdracht

Spec-first: van vaag idee naar een geverifieerde feature

Gebruik oefenrepo/c4-subagents/ (prijsmodule met tests). Je voegt een feature toe: kortingscodes.

Opdracht

  1. Start claude en 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.
  2. Lees SPEC.md. Klopt het met wat je bedoelde? Pas aan waar nodig. Dit is checkpoint 1.
  3. Voeg de Stop-hook uit het voorbeeld toe aan .claude/settings.json.
  4. /clear. Zeg: "Build the feature described in SPEC.md, test-first. Show me the failing tests before implementing." Lees de tests: checkpoint 2.
  5. 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".
  6. 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" (niet PostToolUse)? Draait python3 -m unittest -q vanuit 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.

Zelftoets