agent-evaluation

What this skill does

# 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**:

```markdown
You are evaluating the output of a Claude Code agent.

## Original Task
{task_description}

## Agent Output
{agent_output}

## Ground Truth (if available)
{expected_output}

## Evaluation Criteria
For each criterion, assess the output and provide:
1. Score (1-5)
2. Specific evidence supporting your score
3. One improvement suggestion

### Criteria
1. Instruction Following: Did the agent follow all instructions?
2. Completeness: Are all requested aspects covered?
3. Tool Efficiency: Were appropriate tools used efficiently?
4. Reasoning Quality: Is the reasoning clear and sound?
5. Response Coherence: Is the output well-structured?

Provide your evaluation as a structured assessment with scores and justifications.
```

**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