EVALS

Plain English. Five minutes.

WTF is an eval?

A repeatable way to find out whether your AI does the thing you need—well enough to make a decision.

No benchmark worship. No judge model required. Start with one failure you actually care about.

Build one now → Just explain it ↓
01 / Input A real case
02 / Expectation What should happen
03 / Check Evidence, not vibes
04 / Result [ Pass / Fail ]
05 / Decision Ship, fix, or learn

01The answer

You are not measuring “AI quality.”

You are collecting repeatable evidence about one behavior so you can make one decision.

Question+ Real cases+ Grader+ Decision rule= Eval

02One example

Turn a vibe into something testable.

Too vague
“Is our coding agent good at Python?”
Useful
“When the agent changes an authenticated endpoint, does it preserve the existing unauthorized-user behavior and tests?”
Decision

Should agent v7 replace v6?

Cases

12 ordinary backend tasks involving authenticated endpoints.

Grader

Original tests, hidden authorization checks, and a protected-file diff.

Rule

Any validated weakening of authorization blocks release.

10 / 12 tasks passed Decision: do not ship

v7 deleted a protection test in one case. An 83% score can still mean “no.” Averages do not erase critical failures.

03The loop

Build the smallest eval that can teach you something.

  1. 01

    Name the failure.

    Describe observable behavior: “invents a refund policy,” not “is unreliable.”

  2. 02

    Name the decision.

    Ship it, keep the baseline, investigate, or fix and rerun. If nothing could change, you may not need an eval.

  3. 03

    Collect cases you can inspect.

    Include normal use, costly failures, and meaningful edge cases. A small set is for learning—not proving universal quality.

  4. 04

    Define “pass” before running.

    Write what must happen, what must remain true, and what evidence will establish it.

  5. 05

    Run, inspect, decide.

    Keep failures, timeouts, and invalid runs. Inspect individual cases before averaging anything.

04Pick a grader

Use the least-fancy check that works.

Software can prove it Use code. Tests, assertions, schemas, parsers, runtime checks, or exact rules.
People could disagree Use humans. Give reviewers a specific rubric, examples, and room to preserve disagreement.
You need judgment at scale Use an LLM judge carefully. Calibrate it against independent human labels before trusting it.
You need both Use a hybrid. Let direct checks cover correctness and humans cover ambiguous qualities.

A grader is not truth. It is an instrument. Every instrument can be wrong.

05Common traps

Six easy ways to fool yourself.

  • ×1

    Starting with a metric

    “We need 90% accuracy” is not a failure definition.

  • ×2

    Running once

    One lucky output does not prove reliability.

  • ×3

    Trusting the average

    A 92% score can still hide a security regression.

  • ×4

    Trusting automation

    Tests can be wrong. Humans disagree. Model judges have biases.

  • ×5

    Calling convenient cases representative

    Ten prompts can teach you plenty. They cannot describe your whole product.

  • ×6

    Installing a framework first

    Your first eval can be a spreadsheet and a script.

06Build one

Start with one failure.

Fill in five blanks. You will leave with the bones of an eval—not a platform, dashboard, or mysterious score.

Your eval sketch v0.1 
# My first eval

Decision
What choice should this evidence change?

Failure
What observable behavior is going wrong?

Cases
Where does that behavior show up?

Evidence
What can directly establish pass or fail?

Rule
What result changes the decision?

07Behind the page

Simple up front. Serious underneath.

The page is short because the research was not.

59 inspected sources
70 confidence-graded claims
3 runnable examples