Evals: Prove Your Prompt Works
A five-step test routine you can run in an afternoon, with good habits from both docs.
An eval is a test for AI output. Define what good means, collect real test cases and choose how to grade. Run it, study the failures and fix one cause at a time. Rerun the eval whenever the prompt or the model changes.
- Eval
- A repeatable test of how good AI output is.
- Grader
- The check that marks each answer pass or fail.
- Judge model
- A second model that scores answers.
How do you know a prompt works? Many people try it twice and move on. Both companies say to do better. The OpenAI docs call the answer evals. An eval is a test for AI output. The Claude docs agree: write down what success is, and test against it. This lesson gives you a small version you can run in an afternoon.
The five steps
Step by step
- Say what good means. For a support reply: polite, correct and under one hundred words.
- Collect test cases. Start with twenty real examples. Add a few tricky ones and a few where the right answer is I do not know.
- Choose graders. Use code for things you can check exactly, such as length or a required word. Use a person or a judge model for style and meaning.
- Run it. Send each case through your prompt and score the result.
- Study failures. Group them by cause. Fix one cause, then run all the cases again.
A tiny test sheet
case 1 input: Where is my order? must: asks for order number pass case 2 input: I want my money back must: sends to a person FAIL case 3 input: (empty message) must: asks what they need pass
Good habits from the docs
- Write the tests before you finalize the prompt.
- Use cases that look like real traffic, with correct answers checked by a person.
- Run the eval every time you change the prompt or switch the model.
- Start small, then add cases as new failures appear.
- Pin the model version in production, so behaviour does not shift under you.
Common traps
- Testing on the same few cases you used to write the prompt. Keep some cases hidden.
- Trusting a judge model without checking it against a person.
- Making one big score. Track a few dimensions, so you see what broke.
A worked example
Say your prompt writes short answers for a help centre. You decide that a good answer is correct, polite and under one hundred words. You collect twenty real questions and the right answer for each. You run the prompt on all twenty. Two answers are too long and one is wrong.
You change one thing: you add a length rule. You run all twenty again. The long answers are fixed, but one new answer is now too short. That is useful news. You learned it in minutes, before any customer saw it.
This is the heart of an eval. Small, steady, repeatable checks beat a vague feeling that it seems fine.
Keep the sheet small at first. Twenty good cases beat two hundred careless ones. You can always add more later.
- ✓An eval is a test for AI output, with cases and a way to grade each one.
- ✓Five steps: define good, collect cases, choose graders, run, study failures.
- ✓Run the eval after every prompt or model change.
- ✓Add each real failure as a new test case.
- ✓Keep your test cases in your own files, not only in a vendor tool.
Build a twenty-case test sheet
- Pick a prompt you rely on.
- Write three must-haves that define a good answer.
- Collect twenty real inputs, including three tricky ones, and write what a good answer must include.
- Run all twenty, mark pass or fail, and find the most common cause of failure.
Q1Why run the eval after a model change?show answer
A new model can behave differently. The eval shows what got better or worse.
Q2When should code do the grading?show answer
For exact things, such as length or a required word. Use people or a judge for style and meaning.
Q3Where should you keep your test cases?show answer
In your own files. Vendor tools can change or close.