Eval-driven agentic development

Every AI feature ships through a series of small decisions, and almost all of them change behavior without changing the part of the code a reviewer reads. You reword a system prompt to fix one bad answer. You switch from one model to a cheaper or newer one. You add a tool, widen a retriever's index, or rearrange the order of steps in an agent. Each of these is a deliberate edit you made for a reason — and each one moves the product somewhere you have not looked yet. Eval-driven agentic development is the practice of attaching a check to those moments, so the move is measured before it quietly becomes how the product behaves.

The discipline is not new in spirit. OpenAI's evaluation guidance recommends setting up continuous evaluation that runs on every change, monitoring for new cases of variability and growing the eval set over time.¹ What eval-driven development adds is who runs the check and when. You are already building with a coding agent — Claude Code is the primary runtime, with Codex supported and its public listing still to come. That agent is sitting in the same conversation where you make the edit, with full repo context. So the natural place for the check is right there, in the loop, the moment the change lands — not in a separate dashboard you remember to open a week later. The sibling guide on coding-agent-operated AI quality control covers who operates the work and the authority boundary around it; this guide is about the concrete rhythm — the change moments, what each check actually reads, and where the practice stops short of claims it cannot make.

The change moments worth a check

It helps to name the moments precisely, because each one fails differently and a check is only useful if it watches the behavior that particular change can move. There are six that recur in every AI codebase, and they map one-to-one onto things EvalGlass already has language for.

A prompt edit is the most common and the most deceptive: you change wording to fix one case, the demo improves, and the long tail of cases the demo never touches regresses silently. This is the bread and butter of prompt optimization, where the only honest way to know you improved things is to re-measure the whole example set, not the one case you were staring at. A model switch changes everything at once — tone, tool-calling behavior, refusal patterns, cost — and a switch that improves the headline answer can quietly regress tool selection underneath it; model switching is where comparing two runs side by side earns its keep. A retriever change — re-indexing, a new chunking strategy, a different embedding — moves grounding without touching a prompt at all. A tool update changes the shape of what the agent can call, and therefore which tool it reaches for and what arguments it passes. A drift investigation is the change moment you did not make: the model the vendor updated under you, or live traffic that shifted, surfaced by re-running the same examples over time (drift investigation). And a feature launch is the broadest of them — a new capability whose whole behavior is unexamined until you exercise it, the home ground of feature testing.

The point of the list is not completeness; it is that each entry is a moment where behavior moved and the diff did not say how. Eval-driven development treats every one of them as a cue: a change of this kind is exactly the thing a scorecard exists to catch.

The rhythm: change, evaluate, scorecard, decide

Inside the coding-agent loop, each change moment runs the same short cycle, and the discipline is in keeping the cycle honest rather than in any one step being clever. You make the change. You ask the agent, in plain language, to evaluate it against your project's examples. The runtime measures the behavior locally and returns a bounded scorecard — values, deltas, and the things it could not measure. Then you read the scorecard and decide what, if anything, the result licenses. Change, evaluate, scorecard, decide — and the last step never belongs to the agent.

That ordering matters more than it looks. The agent is the operator: it scaffolds the checks, runs them, and explains the output, all faster than you would by hand. But the actor that produces the evidence is structurally not the actor that authorizes it. EvalGlass enforces this by having no gate, approve, or certify verb for the agent to call. A passing scorecard at a change moment is information, not permission; it licenses only what the run actually checked, on the examples you supplied, against thresholds you set. The decision to let a change through stays a human one, anchored in reviewed records in your repo.

A scorecard at a change moment tells you what moved. It does not tell you the change is safe to ship — only you, reading it against what you required, can say that.

Observable behavior, not narrated progress

Here is the part of eval-driven development that is easiest to get wrong, and it is the spine of the whole practice: a check must read what the run actually did, never what the agent said it did. A capable model is a capable narrator. It can write “I have now verified the data and everything checks out” in a tone of total confidence while the trace of that same run shows it called the wrong tool, ignored the context it retrieved, and recovered only by luck. If your eval scores the narration, it scores the confident sentence and learns nothing. If it scores the record, it sees the broken path.

So EvalGlass evaluates exported, recorded behavior — not a model's private reasoning or hidden chain-of-thought; it cannot see inside the model, only the spans you exported. This is a deliberate design choice, not a limitation it apologizes for: agent-claimed progress is treated as untrusted input, and the score comes from the observable record instead. To be exact about the boundary, EvalGlass does not do chain-of-thought monitoring and does not try to read intent. It reads which tool was actually called, the arguments actually passed, what retrieval actually returned, and the actual end state — artifacts you can point at, sharing a trace_id. The same instinct that makes a trace evidence to be validated rather than a verdict to be believed is the instinct that makes a model's self-report something to check against, never something to record as the result.

The checkable surface of a run

When a change moment fires and the agent evaluates the run, the checks distribute across the trajectory — an ordered sequence of units sharing a trace_id. Each one reads a recorded artifact at a specific point on the path. Five of the six are about the path; only the last is about the destination. That ratio is the whole argument for path-aware evaluation: a score on the final answer alone throws away most of what the run made visible.

1. 01 · plan / route

   Tool selection

   Reads which tool was actually called — the search tool, not the calculator — not which the agent claims it chose.

2. 02 · tool call

   Arguments

   Reads the parameters actually passed, scoped to the question the run was actually asked.

3. 03 · retrieval returns

   Grounding

   Reads whether the answer cites what retrieval returned, or ignores the context and answers from prior knowledge.

4. 04 · a call errors

   Recovery

   Reads whether the run retried or replanned, or fabricated past the gap as if nothing had failed.

5. 05 · outcome

   Session outcome

   Reads the actual end state, in full run context — the only destination-level check; the rest are path-level.

Laid out as a table, the surface is concrete enough to author against. Each row is a check you shape for your application's real behavior; EvalGlass scaffolds and measures them and reports what it found, never a packaged benchmark standing in for your product.

The most useful thing this surface produces is disagreement. The outcome check can pass on the same run where a process check fails — the answer was right, but the tool selection was wrong — and that disagreement is the signal. A final-answer-only score averages it away and tells you the run was fine; a path-aware score keeps it and tells you the run got lucky. As Anthropic's engineering team puts it, absent evals debugging is reactive and teams cannot distinguish real regressions from noise² — and the disagreement between path and destination is exactly the distinction a destination-only eval cannot draw. For the deeper model of these units and check families, see evaluating agentic workflows; this guide leans on it rather than re-teaching it. A note on resolution: today the honest ceiling is per-call detail — view --by-call — and a finer per-source-function score mapping is planned, not yet built. Read the scorecard for what it measured, not what it might one day.

Why this is not test-driven development

The name invites a comparison to test-driven development, and the rhythm does rhyme — measure at the moment of change, let the result inform the next move. But the comparison breaks on what the measurement is, and conflating the two is how eval-driven development gets oversold. A unit test asserts equality: this input must produce exactly this output, and a single green run is proof the code is correct for that case. An eval does none of that. It is non-deterministic — the same examples can score slightly differently across runs. It is graded, not binary — behavior is measured and bounded against examples, not asserted equal to a fixed expected value. And a single green run on examples no human has reviewed has earned no authority to gate anything.

So borrow TDD's rhythm and refuse its proof claim. The discipline of checking at every change moment is sound; the idea that a passing check proves the change correct is exactly the false confidence the practice exists to avoid. An eval bounds and reports. It surfaces what moved and separates a real regression from noise across the example set. It does not certify the feature, and a green scorecard is a measurement to read, not a verdict to trust.

Informational first runs versus approved gates

The natural endpoint of eval-driven development is wiring a check into CI, so a regression at a change moment shows up in the pull request rather than in production. EvalGlass supports this — see CI for AI and the CI exit-code contract — but the order of operations is deliberate and worth stating plainly, because getting it backward is how a tool ends up manufacturing confidence.

A fresh setup starts with empty authority. Nothing gates by default, so the first run is informational: it reports what it measured and what it could not, and it exits cleanly — exit 0 covers a pass and an informational run, and CI reads the typed verdict rather than guessing from the exit code. A gate fires only after you, the host owner, deliberately approve a threshold in your own config. The agent can type that edit at your direction, but it cannot grant the authority behind it; there is no verb for it to do so. This is the difference between a check that informs your decision and a check that makes the decision for you — and eval-driven development only stays honest if the first kind comes before the second.

Sources

Field context for evaluating at every change moment and distinguishing regressions from noise. Neither source describes EvalGlass; the observable-over-narrated stance, the empty-authority default, and the no-self-approval boundary are EvalGlass's own design choices, presented as such.

1. OpenAI — Evaluation best practices: set up continuous evaluation to run on every change, monitor for new cases of nondeterminism, and grow the eval set over time.
2. Anthropic — Demystifying evals for AI agents (2026): absent evals, debugging is reactive and teams can't distinguish real regressions from noise.