Deel D · Module 03
Evals & verificatie
Hoe weet je dat het werkt?
Leerdoelen
Na deze module kun je:
- een eval opbouwen uit taak, trials, graders en uitkomst, en per grader kiezen tussen code, model of mens;
- pass@k en pass^k berekenen en uitleggen welke van de twee bij een gegeven product hoort;
- een kleine eval-suite schrijven voor een skill of plugin, inclusief een baseline zonder plugin, en het resultaat kritisch lezen.
Voorkennis-check
Twee vragen over sampling en skills. Fout? Lees A4 Sampling en C1 Sturen eerst terug.
Waar zitten we?
Evals zijn een organisatievraag (laag 5): wanneer is een agent, skill of plugin goed genoeg om uit te rollen, en blijft hij dat na een modelwissel? Je meet daarvoor het geheel: model (1) en harness (4) samen.
De stof in drie lagen
Kern ± 5 min lezen, daarna schuiven met p en k
Gewone software test je met unittests: zelfde invoer, zelfde uitvoer. Een agent is niet deterministisch (A4): dezelfde taak kan de ene keer slagen en de andere keer niet. En de vraag "werkt het?" is vaak niet met één assert te beantwoorden. Daarvoor zijn evals.
An evaluation (“eval”) is a test for an AI system: give an AI an input, then apply grading logic to its output to measure success.
| Begrip | Betekenis |
|---|---|
| Taak | één test met invoer en succescriteria |
| Trial | één poging; je draait meerdere trials omdat de uitkomst varieert |
| Grader | logica die een aspect beoordeelt; een taak kan meerdere graders hebben |
| Transcript | het volledige verslag van een trial: output, tool calls, tussenresultaten |
| Uitkomst | de eindtoestand in de omgeving. "Uw vlucht is geboekt" in het transcript is geen uitkomst; een reservering in de database wel |
Omdat je meerdere trials draait, moet je kiezen hoe je ze samenvat. Twee maten lopen sterk uiteen. Schuif hieronder met de slagingskans per poging (p) en het aantal pogingen (k).
Samengevat: pass@k vraagt "lukt het minstens één keer?", en dat is relevant als een mens of test de beste poging kiest. pass^k vraagt "lukt het elke keer?", en dat is relevant als gebruikers elke keer goed gedrag verwachten. Een agent die "meestal werkt", is bij pass^k vaak minder betrouwbaar dan het voelt.
Verdieping graders, capability en regressie, een stappenplan
Drie soorten graders
| Soort | Voorbeelden | Sterk | Zwak |
|---|---|---|---|
| Code | string- of regex-match, tests die van rood naar groen gaan, lint en typecheck, de uitkomst in de omgeving, welke tools met welke parameters | snel, goedkoop, reproduceerbaar | breekbaar bij geldige alternatieven; mist nuance |
| Model | rubric-scores, uitspraken in natuurlijke taal, paarsgewijs vergelijken, meerdere judges | flexibel, kan open antwoorden beoordelen | niet deterministisch; moet gekalibreerd worden tegen mensen |
| Mens | experts, steekproeven, A/B-tests | de gouden standaard | duur en traag; gebruik ze om modelgraders te kalibreren |
We recommend choosing deterministic graders where possible, LLM graders where necessary or for additional flexibility, and using human graders judiciously for additional validation.
Beoordeel bij een agent het liefst twee dingen: de uitkomst (staat het juiste in de database, slagen de tests?) en het proces (gebruikte hij de juiste tool, op een redelijke manier?). Het artikel waarschuwt ook andersom: een slim model vond eens een betere oplossing via een maas in het beleid en "faalde" daardoor de eval. Lees de transcripts.
Capability tegenover regressie
- Capability-evals vragen "kan het dit al?": ze beginnen met een lage score en geven richting aan verbetering.
- Regressie-evals vragen "kan het nog alles wat het kon?": ze horen bijna 100% te scoren; een daling betekent dat er iets stuk is.
Een capability-eval die steeds slaagt, kan "afstuderen" tot regressie-eval. Eval-driven development werkt de andere kant op: schrijf eerst de eval voor wat de agent nog niet kan, en verbeter tot hij slaagt. Draai je suite opnieuw bij een nieuwe modelversie, dan zie je meteen wat beter of slechter werd.
Van nul naar een eerste suite
- Begin vroeg en klein. "20-50 simple tasks drawn from real failures is a great start." Vroeg in de ontwikkeling zijn effecten groot, dus volstaan kleine aantallen.
- Maak taken eenduidig. Een goede taak is er een waarbij twee experts los van elkaar hetzelfde oordeel geven. Vaagheid in de taak wordt ruis in je metingen.
- Kies graders bewust, deterministisch waar het kan.
- Lees de transcripts. Faalt een taak, dan vertelt het transcript of de agent een fout maakte of de grader een geldige oplossing afkeurde.
- Let op verzadiging. Een eval op 100% meldt regressies, maar geeft geen signaal meer voor verbetering.
You won't know if your graders are working well unless you read the transcripts and grades from many trials.
Onder de motorkap claude plugin eval: layout, graders, baseline, CI
Claude Code heeft een ingebouwde eval-runner voor plugins en skills. Elke case is een realistische prompt plus een of meer graders.
Layout van een suite
team-tools/
├── .claude-plugin/plugin.json
├── skills/review/SKILL.md
└── evals/
└── review-vindt-print/
├── prompt.md # frontmatter: max_turns, allowed_tools, …; body: de prompt
└── graders/
├── skill-gebruikt.md # type: tool_used
├── kopregel.md # type: regex
└── vindt-print.md # type: llm (body = rubric)
| Type | Slaagt als |
|---|---|
regex | het patroon in het doel voorkomt (of met match: not_contains juist niet) |
tool_used | het aantal calls naar een tool (optioneel met passende input) tussen min en max ligt; min: 0, max: 0 betekent "nooit aangeroepen" |
tool_order | tool A vóór tool B werd aangeroepen |
file_exists | Claude in de run een bestand maakte dat bij het patroon past |
llm | een judge-model in minstens twee van drie stemmen PASS geeft op de rubric |
baseline | de run minstens zo goed is als een referentietranscript |
- Drie runs per case standaard, elk in een verse, geïsoleerde niet-interactieve sessie met alleen jouw plugin. De score van een run is het (gewogen) aandeel geslaagde graders; de case-score is het gemiddelde.
- Baseline: elke case draait ook zonder plugin. Je krijgt
WITH,W/OUTen het verschilΔ. - Stabiele graders: lange output met
regex, korte metllm; per case één grader op het resultaat en één op het proces (tool_used). Er bestaan geen graders met eigen code. - Kosten: elke run en elke judge-call is een echte modelcall op je account. Ruwweg cases × runs × 2 agentruns, plus judge-calls.
- CI: de suite kan een merge tegenhouden op basis van de score (
--threshold, standaard 1.0).
A high score on its own doesn't tell you the plugin helped, because Claude might do as well without it.
Uitgewerkt voorbeeld: één case, drie graders
Testen of de review-skill uit C5 triggert en het juiste vindt. Uit oefenrepo/d3-evals/:
evals/review-vindt-print/prompt.md
---
max_turns: 6
allowed_tools: [Skill]
---
Kun je deze functie reviewen voordat ik een PR maak?
```python
def zoek_klant(db, naam):
print("zoeken naar", naam)
return db.execute("SELECT * FROM klanten WHERE naam = ?", (naam,)).fetchall()
```
- Alleen de Skill-tool: de code staat in de prompt, Claude hoeft niets te lezen. Minder tools betekent minder variatie tussen runs.
- Geformuleerd zoals een gebruiker het zou typen, niet "gebruik de review-skill". Je test of de description de skill laat triggeren.
De drie graders
# graders/skill-gebruikt.md (proces)
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?review"'
---
# graders/kopregel.md (deterministisch resultaat)
---
type: regex
pattern: 'REVIEW \(team-richtlijnen v1\)'
---
# graders/vindt-print.md (inhoud, model als judge)
---
type: llm
---
PASS if the review flags the print statement as something that should not be in
production code, and mentions the missing docstring.
FAIL if it does not mention the print statement, or only comments on style.
- Proces: is de skill aangeroepen, ook in de namespaced vorm
team-tools:review? - Herkenbaar resultaat: de skill laat het antwoord met een vaste kopregel beginnen. Zonder plugin faalt deze grader per definitie, en dat zie je terug in
Δ. - Rubric met concrete PASS- en FAIL-voorwaarden. Vage rubrics geven wisselende oordelen.
Draai een eval-suite en maak hem beter
Starter: oefenrepo/d3-evals/team-tools/, de review-plugin uit C5 met twee cases. Je hebt Claude Code v2.1.269 of nieuwer nodig. Elke run is een echte modelcall: een volledige run van deze suite kost een handvol requests.
Opdracht
cd oefenrepo/d3-evals/team-tools && claude plugin eval .Lees per caseWITH,W/OUTenΔ. Open het HTML-rapport.- Verklaar de baseline van
review-niet-bij-rename: waarom slaagt die altijd zonder plugin, en wat zegtΔdan? - Maak het kapot. Verander de description van de skill in "Helpt met code." en draai opnieuw. Wat gebeurt er met beide cases?
- Herstel de description. Voeg een derde case toe op basis van een echte fout: een review van code met een SQL-string die met een f-string wordt opgebouwd. Schrijf een
llm-rubric die SQL-injectie eist. - Lees de transcripts van een gefaalde run. Lag het aan de agent of aan de grader?
Verwacht resultaat
Stap 1: review-vindt-print scoort hoog met plugin en laag zonder (de kopregel en de skill-grader kunnen zonder plugin niet slagen), dus een duidelijk positieve Δ. review-niet-bij-rename slaagt in beide armen.
Stap 2: zonder plugin bestaat de skill niet, dus "niet aangeroepen" is gratis waar: Δ ≈ 0. Deze case beschermt tegen een te gretige description, maar laat geen bijdrage van de plugin zien. Dat is ook niet de bedoeling.
Stap 3: met een vage description triggert de skill minder betrouwbaar bij de review-vraag (lagere score, kleinere Δ), en kan hij juist bij de naamvraag wél triggeren. Dit is C1 gemeten in plaats van gegokt.
Stap 4–5: een nieuwe case die je vanuit een echte fout schrijft. Faalt hij, dan laat het transcript zien of de skill de injectie miste of dat je rubric te streng of vaag was.
Als het niet werkt, kijk naar …
claude plugin evalbestaat niet. Update Claude Code (claude update); controleerclaude --version.- Git te oud. De runner vraagt git 2.31 of nieuwer (zonder git werkt hij ook).
- Judge-oordelen springen heen en weer. Maak de rubric concreter, of kies een sterkere judge met
--judge-model sonnet.