Automating eval design and hillclimbing with Claude

來源原標題

Automating eval design and hillclimbing with Claude

機構

Anthropic

原始標籤

Best practices

原始連結

https://claude.dev/blog/automating-eval-design-and-hillclimbing/

摘要原文

Evaluations provide a signal on how your app or skill is performing on specific tasks. But designing evaluations, and improving performance on them without fooling yourself, is hard. We've added guidance for both to the claude-api skill . With the skill, you can run /claude-api build-eval to build an evaluation inside your codebase, and run /claude-api hillclimb to improve your application against it, one change at a time, with a held-out set of examples to catch overfitting. In this article, we highlight the principles of good eval design and hillclimbing first, then show how Claude Code with the claude-api skill applies those principles. We’ll close by showing a few examples of these commands. EVAL DESIGN Well designed evaluations have a few common elements (Figure 1): Eval tasks mirror production. Sample tasks that you care about in “production,” or the setting in which the capability or application you are testing will be used. Sometimes tasks are picked because they are easy to generate or they are easy to grade. But it’s important to ensure that the task distribution represents what you actually care about. Performance improves with stronger models and more thinking . More capable models and higher effort levels typically should perform better on an evaluation. If they don’t, ambiguous tasks or a miscalibrated grader often are hobbling performance. There is “passable” headroom at the frontier . The most capable model at the highest effort should be well below 100% on the evaluation, otherwise you can’t reliably judge how changes impact performance. Importantly, the gap should not be explained by impossible or ambiguous tasks: a common tell is that a task fails every evaluation run, regardless of the number of replicates. A good task is one where two domain experts would reach the same verdict and everything the grader checks is stated in the task. Low run-to-run variance . High variance is often due to poorly designed, ambiguous tasks or a grader that produces different verdicts on identical output. Variance can also hide in the configuration. For example, effort may not be applied consistently. Also, the environment can affect the results of the evaluation: leftover state from an earlier trial (a file, a git history) can hand the agent the answer. Score against tokens spent png Three model sizes at three effort settings, illustrative Perfect score low effort medium effort high effort Action tokens per attempt, log scale Score Frontier model Mid-size model Smaller model 1 2 3 4 1 A more capable model scores higher 2 More effort scores higher 3 Headroom below a perfect score 4 Low run-to-run variance Perfect score low medium high Action tokens per attempt, log scale Score Frontier model Mid-size model Smaller model 1 2 3 4 1 A more capable model scores higher 2 More effort scores higher 3 Headroom below a perfect score 4 Low run-to-run variance FIG 1 The four elements of a good eval Adversarial sampling Model capability is jagged. If you pick cases because today's model fails them, you are sampling the valleys of one model's capability surface (Figure 2). The evaluation can end up measuring that model's failure fingerprint rather than what is intrinsically hard or valuable for your application to do. FIG 2 Adversarial sampling Pick hard cases because a human judged them hard: a useful test is to be able to say why a task is hard before you include it. Include cases that are specific failures in your application derived from production traffic, bug reports, or tickets. However, don’t blindly trust user traffic: users sometimes try what they expect to work, so a task distribution drawn strictly from user traffic may skew easy. /CLAUDE-API BUILD-EVAL The build-eval command in the claude-api skill turns these principles into a guided workflow. When you run /claude-api build-eval in Claude Code, Claude interviews you, builds the eval inside your codebase, and pauses for approval at specific points. Designing examples Claude helps you sample inputs to build evaluations in this order: Production transcripts, after asking about retention and sensitive data. Bug reports and support tickets. Five to ten cases you write by hand. Cases synthesized from your codebase. The skill prioritizes production traffic, but it can also generate synthetic data anchored in a few real examples that you provide. The skill instructs Claude to generate a simple page that shows you every input and waits until you confirm them. As an illustration, below we show an example set of inputs for an e-mail router application that the skill may ask the user to review (Figure 3). FIG 3 Example inputs review generated by the skill Validating the grader After the inputs, Claude proposes the cheapest grader that fits your application’s output: Programmatic verification : If the output possibilities are constrained, it uses a code based check (exact match, a label from a fixed set, JSON that matches a schema, tests that pass). LLM-as-judge : It will default to this type of check if the output space is open-ended, with many valid answers but clear quality criteria. In this case, a second model reads the input, the output and a rubric written as checkable claims (not a 1-to-5 scale), and returns a score with its reasoning. If you have a baseline to compare against, the judge instead reads both inputs in random order, without being told which is the baseline, and picks the better one. You pick the judge model, and it should not be the model you are testing. Claude grades a handful of cases and asks whether you would have scored any of them differently (Figure 4). In general, it is important to read a sample of scored transcripts before believing your evaluator; scoring failures are among the most common ways an evaluation is misconfigured. When you’ve validated the grader, the skill tells you the size of the evaluation set (cases × repeats × model, and roughly how long it will take), runs the baseline, and prints the score with a confidence interval. What you get back: the cases, the grader, the runner, one JSON line and one full transcript per case, and a plain page that lists each case's score with a link to its transcript. If you want more than that page shows (e.g., a chart), just ask and Claude will build it as an extra page next to it. By default, these extra pages are static files that open locally and load nothing from the network. FIG 4 Schematic of the results page generated with suggested grades for each input. Diagnostic checks During the baseline runs mentioned above, Claude checks a number of things: Grader : Claude runs the grader twice on the same output, and reports whether the verdict changed. Plumbing : Claude checks for timeouts, API errors, and cut-off answers to ensure infrastructure noise doesn't pass as model variance. Headroom : if the baseline already scores about 95% or higher, the skill warns the user and alerts that the hillclimb should aim to explore cost or latency rather than quality. HILLCLIMBING Now that you have a reliable means of grading your application’s performance on a task, you can try to improve it. Hillclimbing is an effective way to tune parameters like effort or prompts, which trade-off cost and performance. Some general tips for choosing where to apply it: Cheap iteration - It should be inexpensive (in terms of time, cost, and effort) to modify whatever surface you are focused on for hillclimbing. Many internal efforts and customers have focused hillclimbing on text, such as prompts and skills. These are easy to change and revert. In contrast, open-ended modifications to an agent harness during hillclimbing may involve extensive code changes. Attributable - Changes in the score on your evaluation should be attributable to the surface you are modifying during hillclimbing. For example, several successful applications of hillclimbing have focused on skill triggering.