Evaluate and improve Claude Code commands, skills, and agents. Use when testing prompt effectiveness, validating context engineering choices, or measuring improvement quality.

Evaluation Methods for Claude Code Agents Evaluation of agent systems requires different approaches than traditional software or even standard language model applications. Agents make dynamic decisions, are non deterministic between runs, and often lack single correct answers. Effective evaluation must account for these characteristics while providing actionable feedback. A robust evaluation framework enables continuous improvement, catches regressions, and validates that context engineering choices achieve intended effects. Core Concepts Agent evaluation requires outcome focused approaches that account for non determinism and multiple valid paths. Multi dimensional rubrics capture various quality aspects: factual accuracy, completeness, citation accuracy, source quality, and tool efficiency. LLM as judge provides scalable evaluation while human evaluation catches edge cases. The key insight is that agents may find alternative paths to goals—the evaluation should judge whether they achieve right outcomes while following reasonable processes. Performance Drivers: The 95% Finding Research on the BrowseComp evaluation (which tests browsing agents' ability to locate hard to find information) found that three factors explain 95% of performance variance: Factor Variance Explained Implication Token usage 80% More tokens = better performance Number of tool calls ~10% More exploration helps Model choice ~5% Better models multiply efficiency Implications for Claude Code development: Token budgets matter : Evaluate with realistic token constraints Model upgrades beat token increases : Upgrading models provides larger gains than increasing token budgets Multi agent validation : Validates architectures that distribute work across subagents with separate context windows Evaluation Challenges Non Determinism and Multiple Valid Paths Agents may take completely different valid paths to reach goals. One agent might search three sources while another searches ten. They might use different tools to find the same answer. Traditional evaluations that check for specific steps fail in this context. Solution : The solution is outcomes, not exact execution paths. Judge whether the agent achieves the right result through a reasonable process. Context Dependent Failures Agent failures often depend on context in subtle ways. An agent might succeed on complex queries but fail on simple ones. It might work well with one tool set but fail with another. Failures may emerge only after extended interaction when context accumulates. Solution : Evaluation must cover a range of complexity levels and test extended interactions, not just isolated queries. Composite Quality Dimensions Agent quality is not a single dimension. It includes factual accuracy, completeness, coherence, tool efficiency, and process quality. An agent might score high on accuracy but low in efficiency, or vice versa. An agent might score high on accuracy but low in efficiency. Solution : Evaluation rubrics must capture multiple dimensions with appropriate weighting for the use case. Evaluation Rubric Design Multi Dimensional Rubric Effective rubrics cover key dimensions with descriptive levels: Instruction Following (weight: 0.30) Excellent (1.0): All instructions followed precisely Good (0.8): Minor deviations that don't affect outcome Acceptable (0.6): Major instructions followed, minor ones missed Poor (0.3): Significant instructions ignored Failed (0.0): Fundamentally misunderstood the task Output Completeness (weight: 0.25) Excellent: All requested aspects thoroughly covered Good: Most aspects covered with minor gaps Acceptable: Key aspects covered, some gaps Poor: Major aspects missing Failed: Fundamental aspects not addressed Tool Efficiency (weight: 0.20) Excellent: Optimal tool selection and minimal calls Good: Good tool selection with minor inefficiencies Acceptable: Appropriate tools with some redundancy Poor: Wrong tools or excessive calls Failed: Severe tool misuse or extremely excessive calls Reasoning Quality (weight: 0.15) Excellent: Clear, logical reasoning throughout Good: Generally sound reasoning with minor gaps Acceptable: Basic reasoning present Poor: Reasoning unclear or flawed Failed: No apparent reasoning Response Coherence (weight: 0.10) Excellent: Well structured, easy to follow Good: Generally coherent with minor issues Acceptable: Understandable but could be clearer Poor: Difficult to follow Failed: Incoherent Scoring Approach Convert dimension assessments to numeric scores (0.0 to 1.0) with appropriate weighting. Calculate weighted overall scores. Set passing thresholds based on use case requirements (typically 0.7 for general use, 0.85 for critical operations). Evaluation Methodologies LLM as Judge Using an LLM to evaluate agent outputs scales well and provides consistent judgments. Design evaluation prompts that capture the dimensions of interest. LLM based evaluation scales to large test sets and provides consistent judgments. The key is designing effective evaluation prompts that capture the dimensions of interest. Provide clear task description, agent output, ground truth (if available), evaluation scale with level descriptions, and request structured judgment. Evaluation Prompt Template : Chain of Thought Requirement : Always require justification before the score. Research shows this improves reliability by 15 25% compared to score first approaches. Human Evaluation Human evaluation catches what automation misses: Hallucinated answers on unusual queries Subtle context misunderstandings Edge cases that automated evaluation overlooks Qualitative issues with tone or approach For Claude Code development, ask users this: Review agent outputs manually for edge cases Sample systematically across complexity levels Track patterns in failures to inform prompt improvements End State Evaluation For commands that produce artifacts (files, configurations, code), evaluate the final output rather than the process: Does the generated code work? Is the configuration valid? Does the output meet requirements? Test Set Design Sample Selection Start with small samples during development. Early in agent development, changes have dramatic impacts because there is abundant low hanging fruit. Small test sets reveal large effects. Sample from real usage patterns. Add known edge cases. Ensure coverage across complexity levels. Complexity Stratification Test sets should span complexity levels: simple (single tool call), medium (multiple tool calls), complex (many tool calls, significant ambiguity), and very complex (extended interaction, deep reasoning). Context Engineering Evaluation Testing Prompt Variations When iterating on Claude Code prompts, evaluate systematically: 1. Baseline : Run current prompt on test cases 2. Variation : Run modified prompt on same cases 3. Compare : Measure quality scores, token usage, efficiency 4. Analyze : Identify which changes improved which dimensions Testing Context Strategies Context engineering choices should be validated through systematic evaluation. Run agents with different context strategies on the same test set. Compare quality scores, token usage, and efficiency metrics. Degradation Testing Test how context degradation affects performance by running agents at different context sizes. Identify performance cliffs where context becomes problematic. Establish safe operating limits. Advanced Evaluation: LLM as Judge Key insight : LLM as a Judge is not a single technique but a family of approaches, each suited to different evaluation contexts. Choosing the right approach and mitigating known biases is the core competency this skill develops. The Evaluation Taxonomy Evaluation approaches fall into two primary categories with distinct reliability profiles: Direct Scoring : A single LLM rates one response on a defined scale. Best for: Objective criteria (factual accuracy, instruction following, toxicity) Reliability: Moderate to high for well defined criteria Failure mode: Score calibration drift, inconsistent scale interpretation Pairwise Comparison : An LLM compares two responses and selects the better one. Best for: Subjective preferences (tone, style, persuasiveness) Reliability: Higher than direct scoring for preferences Failure mode: Position bias, length bias Research from the MT Bench paper (Zheng et al., 2023) establishes that pairwise comparison achieves higher agreement with human judges than direct scoring for preference based evaluation, while direct scoring remains appropriate for objective criteria with clear ground truth. The Bias Landscape LLM judges exhibit systematic biases that must be actively mitigated: Position Bias : First position responses receive preferential treatment in pairwise comparison. Mitigation: Evaluate twice with swapped positions, use majority vote or consistency check. Length Bias : Longer responses are rated higher regardless of quality. Mitigation: Explicit prompting to ignore length, length normalized scoring. Self Enhancement Bias : Models rate their own outputs higher. Mitigation: Use different models for generation and evaluation, or acknowledge limitation. Verbosity Bias : Detailed explanations receive higher scores even when unnecessary. Mitigation: Criteria specific rubrics that penalize irrelevant detail. Authority Bias : Confident, authoritative tone rated higher regardless of accuracy. Mitigation: Require evidence citation, fact checking layer. Metric Selection Framework Choose metrics based on the evaluation task structure: Task Type Primary Metrics Secondary Metrics Binary classification (pass/fail) Recall, Precision, F1 Cohen's κ Ordinal scale (1 5 rating) Spearman's ρ, Kendall's τ Cohen's κ (weighted) Pairwise preference Agreement rate, Position consistency Confidence calibration Multi label Macro F1, Micro F1 Per label precision/recall The critical insight: High absolute agreement matters less than systematic disagreement patterns. A judge that consistently disagrees with humans on specific criteria is more problematic than one with random noise. Evaluation Metrics Reference Classification Metrics (Pass/Fail Tasks) Precision : Of all responses marked as passing, what fraction truly passed? Use when false positives are costly Recall : Of all actually passing responses, what fraction did we identify? Use when false negatives are costly F1 Score : Harmonic mean of precision and recall Use for balanced single number summary Agreement Metrics (Comparing to Human Judgment) Cohen's Kappa : Agreement adjusted for chance 0.8: Almost perfect agreement 0.6 0.8: Substantial agreement 0.4 0.6: Moderate agreement < 0.4: Fair to poor agreement Correlation Metrics (Ordinal Scores) Spearman's Rank Correlation : Correlation between rankings 0.9: Very strong correlation 0.7 0.9: Strong correlation 0.5 0.7: Moderate correlation < 0.5: Weak correlation Good Evaluation System Indicators Metric Good Acceptable Concerning Spearman's rho 0.8 0.6 0.8 < 0.6 Cohen's Kappa 0.7 0.5 0.7 < 0.5 Position consistency 0.9 0.8 0.9 < 0.8 Length score correlation < 0.2 0.2 0.4 0.4 Evaluation Approaches Direct Scoring Implementation Direct scoring requires three components: clear criteria, a calibrated scale, and structured output format. Criteria Definition Pattern : Scale Calibration : 1 3 scales: Binary with neutral option, lowest cognitive load 1 5 scales: Standard Likert, good balance of granularity and reliability 1 10 scales: High granularity but harder to calibrate, use only with detailed rubrics Prompt S

agent-evaluation