Evaluating, Testing, and Debugging Claude Applications

When a Claude application fails, first preserve the failing case and identify the earliest boundary where observed evidence diverges from a defined success criterion. Reproduce the case under a recorded model, prompt, context, application, API, and tool configuration; inspect the trace from input assembly through the final effect; classify the failure layer; change the smallest responsible component; and rerun both the failing case and the representative regression set. Do not begin by rewriting the prompt simply because the final answer looks wrong.

The key diagnostic distinction is ownership. A response can expose a model limitation, an ambiguous prompt, missing or polluted context, an application or Claude API integration defect, a tool-selection or execution failure, or a test that measures the wrong outcome. Evaluations provide evidence for that distinction, but passing tests do not prove universal correctness, security, or safety. Test cases sample expected conditions; production controls, monitoring, human review, and incident response remain necessary.

Define Success Before Investigating Failure

Anthropic's current evaluation guidance starts with task-specific success criteria. A useful criterion names the behavior, evidence, and acceptance rule closely enough that two reviewers can distinguish success, partial success, and failure.

Separate criteria by responsibility:

Outcome quality: factual correctness, task completion, relevance, or groundedness against approved evidence.
Contract compliance: required fields, formats, citations, completion states, and downstream invariants.
Process behavior: appropriate tool choice, bounded iteration, required approval, and valid state transitions.
Operational behavior: latency, error rate, cost, retry count, and resource use under the application's service objectives.
Control behavior: authorization, data boundaries, prohibited effects, and escalation when confidence or evidence is insufficient.

No universal metric or threshold fits every Claude application. Exact-match accuracy may suit a closed classification task but fail to capture a useful explanation. A rubric may capture answer quality but miss an authorization violation. Define thresholds from the use case, risk, baseline evidence, and cost of false acceptance or false rejection.

Make every criterion observable

Connect each criterion to evidence the system can retain safely. If the requirement is “use only authorized customer records,” the trace needs resource and policy decisions, not only the final prose. If the requirement is “ask before sending,” the evaluation needs the proposed action, approval state, and execution record. A criterion that cannot be observed is difficult to test and nearly impossible to debug.

Build a Representative Test Set

A representative set should reflect how the application is expected to operate, not just examples on which the current prompt already performs well. Include:

routine cases in realistic proportions;
boundary and ambiguous inputs;
missing, conflicting, stale, or irrelevant context;
valid and invalid tool results;
permission, dependency, and API failures;
long-running or multi-step cases when the architecture supports them;
adversarial cases appropriate to the application's threat model; and
historical failures preserved as regression cases.

Record the input, expected evidence, evaluation rule, relevant data snapshot, and configuration identity for each case. Protect personal or confidential data through approved test-data controls; a debugging corpus must not become an ungoverned copy of production content.

Model output is non-deterministic, so distinguish stable invariants from variable presentation. A required authorization check should pass every time. Wording may vary while remaining acceptable. Where variability matters, run enough repeated trials to estimate the observed distribution for that workload, but do not turn a small sample into a timeless guarantee.

Keep development and release evidence distinct

Use rapid development cases to diagnose and refine, then evaluate the selected candidate against a held-back or separately governed regression set. If the same examples repeatedly guide prompt edits, they become less persuasive as evidence of generalization. Production observations can generate new cases, but add them through a reviewed process that preserves their source, privacy boundary, and failure label.

Choose Evaluators That Match the Criterion

Anthropic's agent evaluation guidance emphasizes that agent outcomes and trajectories can require several forms of evidence. Select evaluators by what they can establish:

Evaluator	Strong use	Main limitation
Deterministic assertion	Schema, status, exact value, allowed tool, state transition	Cannot judge every semantic quality dimension
Reference or source check	Required facts or evidence against a controlled source	Depends on reference quality and coverage
Human rubric	Nuanced correctness, usefulness, policy interpretation	Costly and subject to reviewer consistency
Model-based evaluator	Scalable judgment against a specific rubric	Needs calibration and can share model biases or blind spots
Operational measurement	Latency, tokens, errors, calls, and resource use	Measures system behavior, not semantic correctness by itself

Combine evaluators when a decision has several independent requirements. A tool-using answer might need a deterministic authorization assertion, a task-completion check, a semantic rubric, and a latency measurement. Do not average a severe control failure into an acceptable aggregate score; define hard gates separately from optimization metrics.

Calibrate rubric and model-based evaluators against reviewed examples, document disagreement handling, and retain evaluator versions. When the evaluator changes, treat the resulting score movement as ambiguous until the old and new evaluators have been compared on the same cases.

Capture a Trace That Can Localize Failure

A trace is the ordered evidence of what the application observed and decided. It should reconstruct the execution without indiscriminately logging sensitive prompts, credentials, or tool payloads.

Useful trace fields include:

case or operation identifier, attempt, time, and environment;
code, model, prompt, schema, policy, and evaluator versions;
sanitized input and context-source identities;
Claude API request identifier, completion state, usage, and normalized error details;
ordered content and tool-call boundaries;
tool name, validated argument summary, authorization and approval decision;
bounded tool result, retry or stop reason, and final application state; and
evaluator results with the evidence each judgment used.

Record identities and safe digests when raw content is unnecessary. Logging everything can create a privacy and secret-management defect; logging only the final answer removes the evidence needed to distinguish a context failure from a parser or tool failure.

Use an Evidence-Driven Diagnostic Workflow

Apply the same sequence to an offline test failure, production anomaly, or refactoring regression:

Freeze the symptom. Preserve the exact case, environment, configuration identities, observed result, expected criterion, and impact without exposing protected data.
Confirm the evaluator. Check that the criterion applies, the expected result is correct, and the evaluator consumed the intended evidence.
Reproduce under the recorded bundle. Separate a repeatable defect from intermittent model variation, service behavior, or mutable external state.
Find the earliest divergence. Walk the trace from request construction, prompt and context assembly, and Claude API response through parsing, tool dispatch, and downstream effect.
Classify the owning layer. Assign the failure to model behavior, prompt, context, application/API integration, tool, configuration/version, external dependency, or evaluation logic.
Form one falsifiable hypothesis. State which evidence should change if the proposed cause is correct.
Apply the smallest correction. Change one responsible boundary when practical and preserve the prior configuration for comparison or rollback.
Verify and compare. Rerun the original case, relevant neighboring cases, the regression set, and applicable control gates before release.

If evidence cannot establish the execution state or authority for a consequential action, stop and escalate. Uncertainty is a diagnostic result, not permission to retry or continue.

Isolate the Failure Layer

Model behavior

Suspect a model-level limitation or variability only after confirming that the intended request, context, and response reached the application intact. Evidence can include repeated failures across clear prompt variants, correct context, valid tool results, and multiple representative cases. A single poor answer does not establish a general model defect.

Possible responses include narrowing the task, adding a deterministic workflow stage, selecting an evaluated model configuration, requiring human review, or declaring the use case unsupported. Model selection and inference controls require their own quality, latency, and cost comparison.

Prompt or instruction weakness

Prompt failures include ambiguous objectives, conflicting roles, missing constraints, poorly placed examples, and unclear output expectations. Compare the rendered prompt—not only its template—with a known case. Change one instruction or example set at a time and verify that the correction does not damage other cases.

Do not use prompt changes to conceal an authorization, parser, or tool-execution defect. A clearer instruction can improve behavior; it cannot replace deterministic enforcement.

Context or memory weakness

Context failures include missing evidence, irrelevant retrieval, stale memory, cross-task contamination, excessive tool output, compaction loss, and source-authority confusion. Inspect which sources were selected, their trust and authorization scope, their placement, and what survived pruning or compaction.

Replay the same prompt with a controlled context snapshot. If the failure follows the context rather than the model configuration, correct retrieval, selection, lifecycle, or isolation. The full context and durable-memory architecture is covered in Context and Memory Management for Claude Applications and Agents.

Application or Claude API integration defect

Integration failures occur when application code sends the wrong fields, loses message history, misreads content blocks, ignores completion state, selects an unsupported configuration, mishandles an API error, or corrupts the result before evaluation. Replay recorded model output through the adapter and parser without another model call. A deterministic reproduction there points to application code, not model quality.

Use the current API error documentation to normalize service errors before choosing recovery. Invalid requests, authentication failures, overload, rate limits, and connection or streaming failures have different owners and retry properties. Detailed request-level streaming state, backpressure, retry, and partial-output recovery remain in Reliable Claude API Streaming, Asynchronous Work, and Error Handling; this article uses their normalized outcomes as diagnostic evidence rather than repeating that procedure.

Tool selection, execution, or result defect

A tool-related symptom can originate at several boundaries:

wrong tool selection suggests an unclear description, an overly broad visible tool set, or missing task context;
invalid arguments suggest a schema, description, example, or model-output problem;
rejected authorization or approval is a controlled denial, not a model failure;
handler or dependency errors belong to execution and recovery logic;
malformed, missing, or oversized results belong to the application tool loop; and
a valid result that Claude misuses may expose unclear result semantics, untrusted content, or a model/context weakness.

The current tool-use troubleshooting guidance supports investigation of definition, argument, and result-contract failures. Stub the handler to test selection and arguments without side effects; separately replay known tool results to test continuation behavior. Do not weaken authorization or fabricate success to make an evaluation pass.

Compare Regressions and Version Changes Fairly

Run the baseline and candidate against the same governed case set, data snapshot, evaluator versions, and operational conditions where practical. Record model identity or alias policy, prompt and context versions, application code, schemas, tools, and feature settings for both.

Compare per-case outcomes before relying on one aggregate. A candidate can improve average quality while introducing a severe failure for a small but important class. Report hard-gate violations, newly failing cases, fixed cases, evaluator disagreement, operational tradeoffs, and observed variability.

When several components change together, attribution becomes weak. Use staged comparisons or controlled ablations when the cost and risk justify them. Configuration bundling, rollout, rollback, and refactoring governance are covered in Configuration and Version Management for Claude Applications.

Select Recovery from the Evidence

Recovery should match the failure class:

correct a deterministic request, parser, schema, state, or configuration defect before retrying;
improve a prompt only when trace evidence identifies instruction ambiguity or incompleteness;
repair retrieval, pruning, compaction, or isolation when the context is wrong;
retry only qualified transient API or dependency failures under the owning operation's safety policy;
reconcile uncertain tool effects through authoritative application state before another execution;
fall back only to an already evaluated path with compatible contracts and controls;
require human review when judgment, authority, or impact exceeds the automated boundary; and
stop or narrow the use case when no candidate meets the defined gates.

Feed each confirmed defect back into the lifecycle. Add a regression case, improve the trace field that exposed the cause, update the responsible owner or runbook, and record the correction with its evidence. For a refactor intended to preserve behavior, the same tests and traces should confirm contract equivalence; unexplained behavioral movement turns the change into a product change requiring explicit review.

Common Evaluation and Debugging Mistakes

Editing the prompt before inspecting the trace. The defect may be in context, parsing, configuration, the API adapter, or a tool.
Testing only happy-path examples. Boundary, failure, adversarial, and historical cases reveal different risks.
Using one score for every requirement. Hard safety or authorization gates should not disappear inside an average.
Treating a model-based evaluator as ground truth. Calibrate it, version it, and retain human or deterministic evidence where appropriate.
Comparing versions on different cases. Dataset or evaluator drift can look like model or prompt improvement.
Logging raw sensitive content by default. Preserve sufficient evidence through minimized and access-controlled traces.
Retrying an uncertain tool effect. Reconcile the operation before another attempt.
Calling passing tests proof of safety. A test set samples known conditions and cannot establish universal absence of failure.
Fixing a symptom at the wrong layer. Assign ownership from the earliest divergence, then change the smallest responsible boundary.

Relevance to Claude Certified Developer – Foundations

The Claude Certified Developer – Foundations Exam Guide includes Debugging and Error Handling together with software-development lifecycle evaluation practices. Its public scope requires developers to classify errors, choose recovery strategies, analyze traces, and separate integration defects from model-output weaknesses.

The durable skill is evidence-based localization. Define what success means, preserve representative failures, trace the complete path, identify the first incorrect boundary, correct the owning layer, and prove the change against both the original case and the regression set.

Conclusion

Evaluate and debug a Claude application as a layered system, not as a prompt in isolation. Begin with observable success criteria and representative tests, retain a safe end-to-end trace, verify the evaluator, and locate the earliest divergence across model, prompt, context, application/API, tool, configuration, and external-dependency boundaries.

Apply the smallest evidence-supported correction, then compare the candidate with the recorded baseline on the same cases and control gates. Tests reduce uncertainty and prevent known regressions; they do not prove universal safety. Keep production monitoring, human control, secure deployment, and incident response as independent layers described in Securing Claude Applications with Guardrails, Hooks, and Secret Management.