How many examples is enough to start?

Twenty, chosen because they are the ones you would be embarrassed to get wrong. Coverage comes later; having any tripwire at all is the step that matters.

Put an eval in CI, not in your head

Give every LLM feature a golden set that runs in CI and fails the build.

EngineersVibe coderspythonnodeci-genericanthropicopenaigithub

A prompt is code with no type system, no compiler and no stack trace. The only way to know a change made it better is to have written down, in advance, what better means. Teams skip this because the output is fuzzy — but a fuzzy output with twenty fixed examples is a test, and twenty examples is an afternoon.

What goes wrong: A prompt edit that improves the case you were looking at and silently breaks four you were not, shipped because nothing checked.

What agents change: The agent will happily rewrite a prompt it does not have a way to score. The eval is what turns that from a coin flip into an experiment.

You are violating it when

You judge a prompt change by trying it once.
Nobody can say whether last month's version was better.
Your CI has no job that calls a model.

The usual objection: That you need a benchmark, a framework and a labelled dataset. You need twenty examples and an assertion.

Treat an LLM feature like behavior that can regress, not like copy that can be reviewed by feel. A small golden set is enough to start: fixed inputs, expected properties of acceptable outputs, and an automated check that runs whenever the prompt, retrieval, tool code, model, or agent instructions change. The important part is not perfection; it is that success was written down before the change was judged.

This works because prompts and agent instructions lack the normal safety rails of software. There is no compiler error when a wording change weakens an instruction, and often no stack trace when a model gives a plausible but wrong answer. A CI eval turns scattered human impressions into a repeatable regression signal, catching the cases that were not on the author’s screen during the edit.

The misconception is “we need a benchmark.” That is wrong because the first useful eval is usually not a research-grade dataset; it is a handful of representative examples plus an assertion, rubric, exact match, schema check, or model-graded judgment. A larger cheap set that runs automatically is often more useful to a product team than a tiny set of carefully hand-inspected examples that only runs when someone remembers.

When an agent is writing or editing the code, the eval becomes the agent’s scorecard. Without it, the agent can confidently change prompts, tools, and control flow with no objective feedback. With it, each change becomes an experiment: keep the diff if the golden set still passes, investigate it if the build fails.

Install it

npx klay practices add evals-are-tests

.github/workflows/klay-evals.ymlcreate

# Klay practice: evals-are-tests
# https://klaylearn.com/practices/evals-are-tests
#
# Runs your LLM evals in CI so a prompt change is measured rather than guessed.
#
# Two things about this file are deliberate.
#
# 1. It runs on pull_request, NOT on pull_request_target. Evals need an API key,
#    and pull_request_target hands repository secrets to code from a fork. That
#    is the single most exploited misconfiguration in GitHub Actions. The cost
#    is that evals do not run on fork PRs; that is the correct trade.
#
# 2. It skips cleanly when the key is absent instead of failing. A contributor
#    without access to the key should get a green, honest "skipped", not a red

evals/README.mdcreate

# Evals

Twenty examples and an assertion. That is the whole starting requirement.

An eval is a test for the part of your system that has no type checker. If a
prompt change makes one case better and four worse, nothing else in your
toolchain will tell you.

## Start here

1. Write down twenty inputs you would be embarrassed to get wrong. Real ones,
   from your logs, not invented ones.
2. For each, write what *has to be true* about the output. Not the exact text —
   the property. The JSON parses. The refusal happens. The number is in range.

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

npx klay practices audit reports these checks for this practice:

evals-present
evals-in-ci

Where this comes from

Demystifying evals for AI agentsAnthropic Engineering · Official docsFirst-party agent guidance tying automated evals to CI/CD regression protection.
Evaluation best practices | OpenAI APIOpenAI Developer Docs · Official docsAdds practical sizing and grading advice that counters overbuilding a benchmark first.
openai/evalsOpenAI Evals · Official docs · 19,174★First-party framework and registry for custom evals and model-change regression checks.
promptfoo/promptfoopromptfoo · Community tool · 24,244★Provides the build-enforcing mechanism: declarative prompt and agent tests in CI/CD.

Questions

How many examples is enough to start?: Twenty, chosen because they are the ones you would be embarrassed to get wrong. Coverage comes later; having any tripwire at all is the step that matters.
The output is not deterministic — what do I assert?: Assert the properties you actually care about: the JSON parses, the refusal happens, the number is in range, the cited id exists. Exact-match is rarely the requirement.