How to write your first eval suite

The most common reason a team has no eval suite is that starting feels like it requires a plan for the whole codebase. It does not. Here is the version that works, in the order we do it.

Step 1: pick the flow where a failure nobody notices is most expensive

Pick the one where a wrong answer that nobody notices for a week does the most damage, even if it is harder to test or has less code than others.

For most products that is one of five things: authentication and permissions, anything that moves money, anything that writes or deletes customer data, the export or report that customers make decisions from, or the integration that other systems trust. Pick one. Just one.

The reason to choose by cost rather than by convenience is that the first suite has to win support inside the team. A suite that catches something real in its first fortnight gets extended. A suite that proves your date formatter works gets abandoned.

Step 2: write the invariants as sentences

Before any code, write down what must always be true. Plain sentences, the kind you would say out loud to a colleague. For a permissions boundary that might be:

A user can only read records belonging to their own organisation. A revoked session cannot perform any write. An admin action on another organisation's data is refused and logged. A deleted user's tokens stop working immediately, rather than at the next refresh.

Four sentences. You now have four evals, and you have also done the more valuable thing, which is discover whether anyone actually knows the answer. Almost every time we run this exercise, at least one sentence produces a disagreement in the meeting. That disagreement was already in your codebase, undecided, being resolved differently by whoever last changed it. Finding it costs an hour here and costs an incident later.

If the sentences are hard to write, the problem is earlier, in the specification. Writing specs an agent can verify is about fixing that part.

Step 3: turn each sentence into a check that fails first

Write the check, then run it against the current code and watch what happens.

If it fails, good. You have found a real gap and you have proof the check works. If it passes immediately, break something on purpose and confirm it fails. A check that has never failed is a check you cannot trust, and a surprising share of assertions in real codebases cannot fail at all: the mock returns the expected value, the setup skips the branch, the assertion compares a variable to itself.

Keep each check at the level the sentence was written at. If the sentence is about a user reading records, drive it through the same entry point a user does: the API handler or the service function, rather than three private methods. Testing at the level of the promise is what keeps the suite working through refactors.

Step 4: use real data rather than invented data

The cases that break software in production are usually different from the cases people invent at a desk. Names with apostrophes, empty arrays where the code expects one item, a timezone offset that pushes a date into the previous month, a string long enough to hit a column limit, a unicode emoji in a field someone assumed was ASCII.

Anthropic's guidance on eval design says the same thing about model evals and it applies exactly: mirror the real task distribution and do not forget the unusual cases, including irrelevant or nonexistent data, over-long input, and cases where even a human would hesitate [1]. Pull your fixtures from real traffic where you can, with the sensitive fields replaced. Ten real cases are worth more than a hundred invented ones.

Step 5: make it block the merge on the same day

This is the step teams skip and it is the step that makes the difference. A check that runs when someone remembers is documentation. Put it in the pipeline, make a failure block the merge, and do it before you move on to the next flow, because a suite that has never blocked anything will not be maintained.

If your pipeline is slow, split it: the fast checks on every push, the slow ones before merge. What matters is that no change reaches the main branch without the relevant checks having passed. The mechanics are in evals in CI for coding agents.

Step 6: add checks after incidents rather than from a big plan

Once the first flow is covered, avoid planning the rest. Adopt one rule instead: every time something reaches a user that should not have, the eval that would have caught it gets written before the fix.

That rule does two useful things. It keeps the suite proportional to your product's actual failure modes rather than to someone's idea of good coverage. And it makes the suite a record of everything you have learned from real failures, which is the most valuable document a team owns and the one nobody ever writes deliberately.

Do the same when you work on an area of the codebase for other reasons. Adding a feature to a module with no checks? Write one invariant for what is already there before you touch it. The suite grows as part of your normal work instead of needing a project of its own.

What a good first suite looks like

Small. Between five and twenty checks. All of them on things that would cause harm. All of them fast enough that nobody resents running them. Every one has failed at least once in real use, so the team knows they are real. None of them flaky, because the first flaky check is when the team starts to ignore the suite.

That is the whole thing. It does not require a framework decision, a coverage tool, or a new job title. It requires picking the flow that matters and writing down what must be true about it, which is work nobody can do for you and which turns out to be most of the value.

Where to go next

What to check in an eval suite is the checklist for the second and third flows. Adding evals to an existing codebase covers the staged approach for a large system with years of untested code. And if you want the case for spending the time, the business case for evals is written for the person approving it.