eval-driven-development

name	eval-driven-development
description	Use when reasoning about building language-model-integrated systems by writing evaluations before and alongside the system: the statistical (not binary) nature of LLM evals, the five primitives (dataset, evaluation function, aggregation, iteration loop, regression budget), the judgment-mechanism taxonomy (programmatic, model-graded, human-graded, preference comparison), the difference between system-specific evals and canonical benchmarks (MMLU, HumanEval, BIG-bench, GAIA), how evals drive prompt/model/scaffolding/tooling changes, why Goodhart's Law means higher eval scores are not always improvements, and the offline-eval-vs-production-telemetry distinction. Do NOT use for deterministic unit testing (use testing-strategy), production monitoring (use evaluation or error-tracking), general-software TDD (use testing-strategy), or the construction of individual eval rubrics and task sets (use agent-eval-design — it owns construction; this skill owns the iteration discipline).
license	MIT
allowed-tools	Read Grep
metadata	{"metadata":"{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/evaluation\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"eval-driven development\\\\\\\",\\\\\\\"LLM evals\\\\\\\",\\\\\\\"evaluation harness\\\\\\\",\\\\\\\"benchmark\\\\\\\",\\\\\\\"HumanEval\\\\\\\",\\\\\\\"MMLU\\\\\\\",\\\\\\\"BIG-bench\\\\\\\",\\\\\\\"GAIA\\\\\\\",\\\\\\\"LLM-as-judge\\\\\\\",\\\\\\\"model-graded eval\\\\\\\",\\\\\\\"pass rate\\\\\\\",\\\\\\\"regression budget\\\\\\\",\\\\\\\"Goodhart's law\\\\\\\",\\\\\\\"golden dataset\\\\\\\",\\\\\\\"reference-free eval\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do we know this prompt change improved things\\\\\\\",\\\\\\\"should this be an eval or a unit test\\\\\\\",\\\\\\\"the model passes the benchmark but fails in production\\\\\\\",\\\\\\\"what should we measure\\\\\\\",\\\\\\\"the LLM-as-judge gives different scores each run\\\\\\\"]\",\"examples\":\"[\\\\\\\"design an offline eval suite for an LLM-integrated summarization feature before writing the prompt\\\\\\\",\\\\\\\"decide between programmatic grading, model-graded judgment, and human review for a freeform-output eval\\\\\\\",\\\\\\\"explain why MMLU score is a poor predictor of a domain-specific assistant's quality\\\\\\\",\\\\\\\"structure an iteration loop where each prompt change is gated by a regression budget\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"write unit tests for a deterministic data transformation (use testing-strategy)\\\\\\\",\\\\\\\"set up production alerting on API error rates (use observability)\\\\\\\",\\\\\\\"interpret a specific benchmark's leaderboard (use benchmarking-engine)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"prompt-injection-defense\\\\\\\",\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"agent-eval-design\\\\\\\",\\\\\\\"evaluation\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"testing-strategy owns deterministic-software testing where every run is binary pass/fail; this skill owns LLM evaluation where every run is a sample from a distribution and pass-rate is the unit of judgment. The disciplines share vocabulary (suite, gate, regression) but the math underneath differs.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-flow\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-flow owns the protocol cycle by which a model invokes tools; this skill owns the discipline of measuring whether that cycle produces correct behavior. Tool-call evals are a specialization of the general pattern.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-injection-defense\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-injection-defense owns the security property; this skill owns the measurement of whether the property holds. Red-team evals against an injection corpus are one application of eval-driven-development.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"agent-eval-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"agent-eval-design owns the construction of evals — task sets, rubrics, graders, hard negatives, traces; this skill owns the development discipline that uses constructed evals to gate every change to prompt, model, retrieval, scaffolding, or tooling. The two compose: agent-eval-design produces the suite; this skill applies it.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety owns the compile-time property of programs; this skill owns the runtime-distributional property of LLM outputs. They are both validate-at-the-boundary disciplines with different threat models.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"agent-eval-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Eval-driven development is to LLM system engineering what crash-test ratings are to automotive safety — you do not ship a car based on how well it parked in your driveway; you ship it after a battery of standardized tests on representative crash scenarios, with the pass-rate against named criteria as the gating signal. A score of 4.3 stars across the suite is the only defensible claim of 'safer'; a developer's intuition that 'the new model feels smarter' is the unmeasured equivalent of 'I drove it home, it seem…","skill_graph_source_repo":"https://github.com/jacob-balslev/skill-graph","skill_graph_protocol":"Skill Metadata Protocol v4","skill_graph_project":"Skill Graph","skill_graph_canonical_skill":"skills/eval-driven-development/SKILL.md"}

Eval-Driven Development

Coverage

The practice of building language-model-integrated systems by writing evaluations before and alongside the system, and using the eval suite's aggregated pass-rate signal to gate every change. Covers the statistical (not binary) nature of LLM evaluation, the five primitives (dataset, evaluation function, aggregation, iteration loop, regression budget), the judgment-mechanism taxonomy (programmatic / model-graded / human-graded / hybrid), the distinction between system-specific evals and canonical public benchmarks (MMLU, HumanEval, BIG-bench, GAIA, MT-Bench), why higher scores are not always improvements (Goodhart's Law), the difference between offline evals and production telemetry, and the eval-lifecycle archetypes (acceptance, regression, calibration, red-team, cross-model).

Philosophy

Building LLM-integrated systems without evals is shipping airplanes based on how good the model feels at the desk. The system's behavior is stochastic, the input space is open-ended, and the developer's pet examples are not a representative sample of what users will throw at it. An eval suite is the empirical measurement instrument that lets a team distinguish "the new prompt works better" from "the new prompt works better on the five examples I happened to try."

The discipline's hard part is not writing evals. It is choosing what to measure, encoding the choice into a grader the team agrees with, sampling a dataset that represents production, and resisting the gravitational pull of Goodhart's Law as the eval suite becomes the optimization target. Teams that get this right ship systems whose quality matches their team's stated definition of "good." Teams that get this wrong ship systems that ace evals and disappoint users.

Eval-driven development is not test-driven development with extra noise. It is empirical engineering applied to systems whose behavior is a distribution rather than a value. The vocabulary overlaps; the math underneath does not.

The Five Primitives In Practice

Primitive	What it is	Common encoding	Failure mode if neglected
Eval dataset	Curated input examples that represent production	JSONL of {input, reference} records; checked into version control	"It works for me" with no shared evidence
Evaluation function	Per-example grader producing a score	Python function, model-graded prompt template, or human-review UI	Implicit, undocumented definition of "good"
Aggregation	Statistical summary across the dataset	Pass-rate, weighted pass-rate, stratified pass-rate, distribution