Anthropic's own prompt-engineering documentation is blunt about the order of operations: before you tune a single word, you need clear success criteria and empirical tests against those criteria. Most teams invert this — they iterate on wording first and decide what "good" means never. An evaluation framework is the fix, and it doesn't need to be elaborate. It needs four parts: a test set, criteria, a scoring method, and a habit.
Part 1: A test set that looks like production
Collect 30–100 real inputs for the task — anonymized tickets, actual contracts, genuine user questions. Deliberately include the awkward cases: ambiguous requests, inputs missing key information, edge-of-scope questions, and a few inputs the prompt should refuse or escalate rather than answer. A test set of only clean, typical inputs will certify prompts that fall over in week one. Version the test set alongside the prompts it evaluates, and grow it every time production surfaces a failure you didn't anticipate.
Part 2: Criteria, then rubrics
Criteria answer "what does this output have to get right?" — and they differ by task. A summarization prompt might be judged on factual fidelity, coverage of key points, length compliance, and tone. An extraction prompt lives or dies on field accuracy and valid formatting. Write the criteria down before scoring anything, and split them into two families:
| Family | Examples | How to score |
|---|---|---|
| Objective — code can check | Valid JSON, required fields present, length limits, banned phrases absent, correct label | Automated pass/fail, every run |
| Judgment — a reader must assess | Faithfulness to source, helpfulness, tone, reasoning quality | Rubric-scored, sampled |
For judgment criteria, a rubric converts opinion into a score: for each criterion, define what a 1, 3, and 5 look like in one concrete sentence each, ideally with a real example of each level. Rubrics are what make two reviewers — or the same reviewer on different days — produce comparable numbers. Keep the scale small; five points is plenty, and pass/fail is often better.
Part 3: Scoring — humans, code, and model graders
Run the objective checks in code on every output; that's cheap and non-negotiable. For judgment criteria you have two options. Human scoring against the rubric is the gold standard — sample 20–30 outputs per prompt version rather than scoring everything. Model-graded evaluation ("LLM-as-judge") scales further: you prompt a model, given the rubric, the input, and the output, to assign scores. It works, with caveats — calibrate the grader by comparing its scores to human rubric scores on a sample first, and keep spot-checking it, because an uncalibrated judge produces confident nonsense at scale. Structured outputs help here: constrain the grader to a JSON schema (output_config with a json_schema format) so scores parse reliably into your dashboard.
Evaluation runs are a natural fit for the Message Batches API where your platform has it (the Claude API and Claude Platform on AWS; not Amazon Bedrock or Vertex AI, though both offer their own cloud-native batch mechanisms): batch usage bills at 50% of standard prices and most batches complete within an hour, which makes "re-run the full eval suite on every prompt change" affordable rather than aspirational.
Part 4: The habit — and the escape hatch
Wire the framework into your workflow: every prompt change gets an eval run before merge, results land in the change log next to the version bump (see prompt versioning), and a score drop blocks the release until explained. Set thresholds in advance — "field accuracy ≥ 95%, zero invalid JSON" — so the pass/fail decision is mechanical, not political.
And keep Anthropic's caveat from the overview docs in view: not every failing eval is a prompting problem. If a prompt has plateaued below threshold after honest iteration, the cheaper fix may be a different model tier, a latency-versus-quality trade, or restructuring the task itself. An evaluation framework's job is to tell you that you have a problem and where; deciding whether the fix is wording, model choice, or product scope is still engineering judgment.
Where to go next
This framework is the foundation two other practices build on: A/B testing prompts in production and regression testing after model upgrades. For why your own numbers beat published ones, read run your own evals, not just benchmarks.