Why evals come first

What it isCopy Anchor Link

You collect example inputs, decide what a good output looks like, and score the system's outputs automatically or with a rubric. Run it before and after every change to a prompt, model or tool. Google's agentic engineering paper puts it as setting the bar at the eval, not the demo. A demo shows the system can work once. An eval shows how often it works.

Two kinds of checkCopy Anchor Link

Code-based checks cover what is deterministic: valid JSON, the right field, the tests pass. Judgment-based checks cover what is not: is the summary accurate, is the tone right. Those use human review, a labeled dataset or a model acting as the grader. Use code checks wherever you can, since they are cheap and exact.

Start smallCopy Anchor Link

Ten to fifty real examples, including the failures you have already seen, are enough to begin. Add every new bug you find as a new test case. The set grows with the product.

A worked example: your first test setCopy Anchor Link

Collect 30 real or realistic questions. For each, write what a good answer must contain (the refund window is 30 days) and what it must not (a promise of free shipping). Run the bot. Score each answer pass or fail. You now have a number: 22 of 30, 73 percent. Change the prompt, rerun, and see if it moved. That is the whole loop.

Where evals pay offCopy Anchor Link

Choosing between models, changing a prompt without fear, catching regressions when a provider updates a model, and persuading others with data instead of opinions.

How to read a small changeCopy Anchor Link

Say 22 of 30 cases pass before your edit and 24 of 30 pass after. That is 73 percent against 80 percent. It looks like progress, but one case flipping moves the score 3.3 points. With only 30 cases, the score has a sampling error of roughly 8 points, before counting any variation between runs of a non-deterministic system. A 7 point gain is inside that noise.

To check, run the unchanged system twice and compare. If it passes 22 once and 25 the next time, a gain of two cases means nothing. Trust a change when the gain is clearly larger than that gap, or when you add more cases until it is.

What goes wrong: tuning to the testCopy Anchor Link

You rewrite the prompt until all 30 cases pass, one failing case at a time. The prompt now quietly contains fixes for those exact questions. Symptom: the set scores 29 of 30 while real users still complain.

To confirm, hold back 10 cases and never look at them while editing. Invented numbers for illustration: 29 of 30 on the cases you tuned against, but 6 of 10 on the held-back ones. That 60 percent is closer to what users will see.

Common mistakeCopy Anchor Link

Waiting for a perfect test set. Start with ten cases, add every new failure you meet.