Agent Evaluation

Why Evaluation Matters More Than Training

Building an Agent without evals is like flying blind. Evaluation is core infrastructure that spans the entire development lifecycle — far more than a pre-launch checklist.

Consequences of Skipping Evaluation
Flying Blind: Fix One Bug, Create Three More
Teams without an evaluation system are gambling with every change. You fix User A's reported issue, but may silently break features that Users B, C, and D depend on. Worse: you have no idea what you broke — until the next wave of user complaints rolls in.
Real-World Scenario
Users report "the Agent has clearly gotten worse this week." The team spends three days combing through commit history and trying a dozen rollback strategies, only to discover it was caused by a seemingly harmless Prompt tweak two weeks ago. With evals, this would have been caught before the code was merged.
Guess-and-Check Loop
Debugging without evals looks like: guess where the problem is → make a change → manually test a few cases → feel like it's probably fine → ship it → discover it's broken again. This loop can run for weeks, consuming massive engineering resources with zero confidence to show for it.
The Timeline of Value in Evaluation
Early Stage — Define Success
The first value of evaluation is forcing the team to define what success looks like — testing is actually secondary. When you can't write an eval, it often means your understanding of the task isn't clear enough yet. The process itself helps product managers better understand requirements.
Mid Stage — Regression Testing & Change Validation
Every time you modify a Prompt, swap a model, or tune parameters, you'll know within minutes how the change affects overall performance. Regression testing prevents you from accidentally breaking other dimensions while optimizing one; change validation gives you data to back every decision.
Late Stage — Fast Adoption of New Models
When a new model launches (e.g. Claude Opus 4.6, GPT-5), teams with solid evals can complete migration in days: run the eval suite, confirm no performance regression, and switch. Teams without evals need weeks or months of manual validation and miss the optimal window.
Core Concepts in Evaluation

Master these 7 terms and you'll speak the language of the entire evaluation system.

Task
A single test case. Contains an input (the instruction given to the Agent) and a success criterion (what counts as completion).
Trial
A single execution attempt of the same Task. Because model output is stochastic, you need to run multiple Trials of the same Task to have statistical significance.
Grader
The scoring logic. Can be code rules, LLM review, or human scoring. Determines whether a Trial's result is pass or fail.
Transcript
The complete execution trace: every reasoning step, every tool call, and every intermediate result of the Agent, all recorded.
Outcome
The final state of the environment. Not just what the Agent said, but what it actually did: were files correctly modified, were APIs correctly called.
Harness
The infrastructure that runs evaluations. Responsible for creating sandbox environments, launching the Agent, collecting results, and calling the Grader to score.
Suite
A collection of related Tasks. For example, a "File Editing Capability Suite" might contain 20 file editing tasks of varying difficulty.
The Evaluation Evolution Story of Claude Code
From Dogfooding to Systematic Evaluation
Initially Relying on daily use by internal engineers (dogfooding) to collect feedback. "It feels like the code quality lately is worse than last week" — this intuition is useful, but imprecise and unscalable.
First Step Added evals for conciseness and file editing. Finally able to quantify "Is the generated code too verbose?" and "Is file editing accurate?"
Advanced Discovered users were complaining about "over-engineering," so a dedicated over-engineering eval was added: measuring whether the Agent introduces unnecessary complexity on simple tasks.
Results Evals helped the team focus improvement efforts: judgment upgraded from "something feels off" to "conciseness improved from 72 to 85, but the over-engineering metric degraded from 3% to 7% — needs rollback."
Key Recommendations
Start with 20
Don't wait until you have hundreds of test cases to start evaluating. 20 carefully designed Tasks can cover your most critical scenarios. The key is to start — quantity is secondary. A team with 20 evals is an entire era ahead of a team with 0 evals but "plans to do 500."
Evaluation Is Also a Tool for Product Understanding
The process of writing eval cases forces you to answer the hardest product questions: "What result does the user actually want?" "What counts as good, what counts as bad?" "How do edge cases get handled?" Many teams find that writing evals clarifies product definitions that have been fuzzy for a long time.
The value of evaluation is compounding: every minute invested upfront continues to yield returns in regression testing, model migration, and team collaboration. The best time to start was three months ago; the second best time is now.