Evals de Claude Code: cómo medir el aporte real de un plugin

El momento de esta incorporación importa. Claude Code 2.1.269 añadió los evals de plugins el 11 de septiembre de 2026. El tutorial fechado que encabeza esta búsqueda todavía explica cómo usar un runner personalizado en Python. Para quien mantenga hoy un plugin local, la ruta más corta ya es nativa: inicializar un caso de comportamiento, ejecutarlo frente a un control, revisar el informe y hacer que CI rechace la misma regresión que se acaba de provocar a propósito.

Qué miden realmente los evals de Claude Code

Un eval de plugin es una prueba A/B del comportamiento de un agente. Imagine dos talleres idénticos que reciben la misma orden de trabajo. Uno tiene instalado el plugin; el otro no. Claude Code repite la tarea en ambos, califica el resultado e informa WITH, W/OUT y Δ: la puntuación con plugin menos la puntuación sin plugin.

Ese delta es el dato que importa. Obtener 1.0 en ambos grupos puede parecer excelente, pero significa que Claude ya podía completar la tarea sin el plugin. Un delta positivo demuestra una contribución medible. Uno negativo indica que el plugin empeoró el comportamiento evaluado.

De forma predeterminada, un caso genera tres sesiones nuevas con el plugin y tres sin él. Cada sesión recibe un directorio personal, un directorio de trabajo y una configuración de Claude Code aislados. La configuración personal, el CLAUDE.md del proyecto, otros plugins, la memoria y los servidores MCP personales quedan fuera. Este aislamiento hace más limpia la comparación, pero también consigue que un plugin que dependa en secreto de la configuración de su equipo falle por el motivo correcto. La documentación de Anthropic sobre evals de plugins detalla el contrato completo de aislamiento y seguridad.

Parta de un plugin local que ya funcione

Los evals de comportamiento son la segunda comprobación, no la primera. El directorio del plugin debe contener un plugin.json, un .claude-plugin/plugin.json o una estructura válida de directorio de skills. Use claude plugin validate para detectar problemas de archivos y esquema. Reserve claude plugin eval para preguntas como: «¿La skill se activó ante una solicitud natural y generó el formato del equipo?».

También necesita Claude Code v2.1.269 o una versión posterior, además de la misma autenticación que utiliza en sesiones normales. Las sesiones del eval, los evaluadores basados en un modelo juez y el inicializador interactivo consumen la asignación del plan o generan cargos en la API. Si la configuración general de Claude Code todavía es reciente, empiece por el flujo local básico antes de añadir una puerta de lanzamiento.

Desde la raíz de un plugin de confianza, compruebe la versión y cree un caso vacío:

claude --version
claude plugin eval init --bare release-note

La alternativa interactiva es claude plugin eval init. Este comando lee el plugin, pregunta qué aspecto tiene un buen resultado, propone casos y evaluadores, los prueba una vez y escribe la suite. La ruta con --bare es mejor para aprender el contrato, porque crea los archivos sin ejecutar nada.

Diseñe un caso de comportamiento fácil de interpretar

Suponga que el plugin funcional contiene una skill llamada release-notes. Su valor no consiste únicamente en redactar texto. Debe reconocer una solicitud natural sobre un cambio de producto y responder con la estructura de tres partes que usa el equipo para sus notas de versión: Summary, Impact y Risk.

Coloque la solicitud realista del usuario en prompt.md. Después, añada un evaluador determinista para el resultado y otro para el mecanismo. «Determinista» significa que la CLI comprueba directamente la traza o el texto, sin llamar a un modelo juez.

# evals/release-note/prompt.md
---
name: release-note
tags: [smoke]
runs: 3
max_turns: 8
timeout_seconds: 180
allowed_tools: [Skill]
---

Turn this change into a customer-facing release note: checkout now retries a failed payment once before showing an error.

# evals/release-note/graders/format.md
---
type: regex
target: last_message
pattern: 'Summary[\s\S]*Impact[\s\S]*Risk'
flags: i
---

# evals/release-note/graders/skill-fired.md
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?release-notes"'
---

Sustituya release-notes por el valor real de name en el archivo SKILL.md de la skill. El prompt evita deliberadamente mencionar la skill o imponer los tres encabezados. De ese modo, la prueba determina si el plugin reconoce la tarea y aporta su formato. Si el propio prompt incluye todas las respuestas, el grupo sin plugin puede aprobar y el delta revelará que el plugin añadió muy poco.

El frontmatter anterior corresponde al esquema nativo actual. En prompt.md, campos como runs, max_turns, timeout_seconds, model, tags y allowed_tools permanecen en el nivel superior. Si necesita fixtures, historial de conversación o directorios, añada case.yaml; ese archivo requiere schema_version: "1.1" y name, y coloca los campos de ejecución dentro de execution:.

Ejecute el caso y aprenda a leer el informe

Desde la raíz del plugin, ejecute claude plugin eval .. Con este único caso, el comando inicia tres sesiones con plugin y tres sesiones de referencia. Las líneas de progreso muestran los resultados de los evaluadores a medida que termina cada sesión. Al final, el resumen presenta WITH, W/OUT, Δ, RUNS, COST y NOTES.

Conviene leerlos en este orden:

1. WITH indica si las sesiones equipadas con el plugin cumplieron los criterios de los evaluadores.
2. W/OUT indica con qué frecuencia Claude obtuvo el mismo resultado por sí solo.
3. Δ mide la contribución del plugin. Un valor positivo es útil; uno cercano a cero exige investigar; uno negativo señala una regresión.
4. COST es una estimación basada en precios de lista, no necesariamente el importe cobrado dentro de una suscripción.
5. NOTES señala el fallo de mayor peso o el error de ejecución más relevante del grupo con plugin.

Toda suite con al menos un caso escribe aggregate-result.json y un report.html autocontenido dentro de un directorio de resultados con marca de tiempo. El informe HTML permite abrir cada ejecución, consultar el veredicto y la explicación de cada evaluador, y comparar el prompt y las definiciones de los evaluadores con lo que Claude hizo realmente. El JSON contiene campos estables para CI, entre ellos la puntuación global, los casos aprobados, el delta medio, el estado parcial, el costo estimado, la duración y la versión de Claude Code.

Provoque una regresión antes de confiar en la prueba

Ahora demuestre que la prueba puede fallar. Sustituya temporalmente la descripción de la skill release-notes por otra vaga que ya no mencione la tarea que debe reconocer. No cambie el caso del eval. Vuelva a ejecutar el mismo comando, examine el nuevo informe y restaure después la descripción real.

El fallo que interesa es de comportamiento: el evaluador de Skill deja de aprobar, el formato esperado se vuelve menos fiable o se reduce la ventaja del grupo con plugin. No intente predecir una puntuación exacta; las ejecuciones de agentes varían. Si el fallo deliberado apenas cambia el informe durante las tres ejecuciones predeterminadas, el caso todavía no protege el plugin. Haga la solicitud más representativa, endurezca el evaluador del resultado o añada un caso negativo en el que la skill no deba activarse.

Provocar esta falla equivale a pulsar el botón de prueba de un detector de humo. Un panel verde no vale nada hasta comprobar que un defecto relevante puede volverlo rojo.

Defina el presupuesto antes de sumar más casos

Un solo caso predeterminado ya crea seis sesiones de agente. Si añade un evaluador LLM, ese mismo caso incorpora dieciocho votos del modelo juez: tres votos para cada una de las seis sesiones. Además, las propias sesiones pueden ocupar varios turnos. Por eso, una suite pequeña puede consumir mucho más de lo que su número de casos sugiere.

Use tres presupuestos para tres decisiones distintas:

El ciclo de una ejecución es deliberadamente ruidoso. Úselo para encontrar errores evidentes y, antes de aceptar un cambio, confirme con las tres ejecuciones predeterminadas. Para las comprobaciones frecuentes, dé prioridad a regex, tool_used, tool_order y file_exists, ya que no añaden llamadas al juez. Reserve un evaluador LLM para resultados breves cuya calidad no pueda expresarse mediante una regla estable.

La opción de costo requiere una aclaración. --max-cost-usd limita la estimación de precios de lista de la CLI antes de que comience cada ejecución. Las ejecuciones que ya están en curso terminan, así que la estimación informada puede superar el límite. Alcanzar ese techo deja resultados parciales y devuelve el código 2. Es una barrera de protección, no una cartera prepagada.

Lleve la comprobación de regresiones a CI

Cuando la regresión deliberada sea visible y el plugin restaurado vuelva a aprobar, incorpore esa misma suite al control de versiones. El ejemplo de CI de Anthropic fija los modelos de agente y juez, escribe results.json, aplica un umbral de 0.8, conserva el informe en local y establece un techo de costo estimado de $20. También utiliza --trust-plugin, algo apropiado únicamente cuando el plugin y la suite extraídos son código que usted mismo ejecutaría.

El comando exacto para el traspaso es claude plugin eval . --trust-plugin --json results.json --threshold 0.8 --model claude-sonnet-5 --judge-model claude-haiku-4-5 --no-publish --max-cost-usd 20. Colóquelo en el job después de instalar y autenticar Claude Code; luego archive los dos archivos de resultados.

El estado de salida del comando basta para bloquear una compilación. La salida 0 significa que todos los casos se cargaron y alcanzaron el umbral. La salida 1 abarca una puntuación inferior al umbral y varios errores de configuración. La salida 2 indica una ejecución parcial causada por el límite de costo o por un rechazo inicial de credenciales. Archive results.json y report.html incluso cuando haya un fallo, para que la persona responsable pueda distinguir entre una regresión del plugin, un timeout y una interrupción por presupuesto.

Fijar los modelos es importante. De lo contrario, el despliegue de una nueva versión del modelo puede parecer una regresión del plugin. Aplique la misma disciplina al esfuerzo de razonamiento: pruebe la calidad y el esfuerzo por separado, de modo que un cambio de costo no quede oculto dentro de una puntuación de comportamiento.

Siete comportamientos de plugins que conviene probar primero

Los equipos que más se benefician son los que distribuyen plugins a otras personas. Un asistente privado puede tolerar una comprobación manual. En cambio, en un plugin de marketplace o de una organización, una descripción débil, un permiso de herramientas incorrecto o un cambio en la salida se traduce en solicitudes de soporte repetidas.

Empiece por los dos comportamientos que sus usuarios notarían primero si desaparecieran. Diez casos vagos aportan menos que una prueba de activación y otra de resultado capaces de exponer un defecto reproducible.

Dos productos que vale la pena crear alrededor de los evals nativos de plugins

1. Una puerta de delta para pull requests es la oportunidad más sólida

Cree un producto ligero de CI que ejecute el comando nativo, lea aggregate-result.json y publique una sola revisión con el cambio de puntuación, el delta, el costo, el evaluador fallido y enlaces al informe archivado. Los equipos de plugins y quienes mantienen marketplaces pagan por la capa de decisión, no por otro evaluador.

La demanda es temprana, pero tiene una intención comercial clara. claude code evals registra unas 50 búsquedas mensuales en Estados Unidos, un aumento interanual del 600% y un CPC de $17.61. Las plataformas de evaluación más amplias también demuestran que existen presupuestos para calidad: Braintrust ofrece un plan Pro de $249 al mes. Es una referencia de la categoría, no una recomendación de precio para un wrapper de plugins.

La versión mínima vendible es una GitHub Action acompañada de un comentario en el PR. Recibe la ruta del plugin, el umbral, los modelos fijados y el límite de costo estimado; sube el JSON y el HTML nativos; y distingue la salida 1 de la salida parcial 2. El riesgo es la dependencia de la plataforma: Anthropic podría incorporar informes propios para pull requests. La capa defendible está en las políticas entre repositorios, las comparaciones históricas y las reglas de aprobación, no en una copia más atractiva del informe nativo.

2. Los paquetes de evals seleccionados pueden servir a quienes crean skills

Venda paquetes de casos mantenidos para tareas habituales de plugins, como revisión de código, redacción de changelogs, triage de incidentes y selección segura de herramientas. Cada paquete es un directorio evals/ común, con prompts positivos y negativos realistas y evaluadores deterministas, para que un equipo pueda adaptarlo en lugar de inventar desde cero su criterio de calidad.

La palabra clave directa claude code skill evals suma unas 10 búsquedas mensuales en Estados Unidos. Es una cifra muy pequeña, por lo que encaja como complemento especializado y no como mercado independiente financiable con capital de riesgo. El MVP consiste en un paquete excelente para una categoría valiosa de plugins, versionado según los lanzamientos de Claude Code y acompañado por una guía breve de calibración. La dificultad también es evidente: claude plugin eval init ya propone y prueba casos. Los paquetes solo ganan cuando sus escenarios de dominio y criterios de fallo superan a la generación genérica.

Lo que este comando no resuelve

Los evals nativos no demuestran que un plugin sea bueno en términos universales. Demuestran cómo se comportó con los prompts, el entorno, el modelo, los permisos de herramientas y los evaluadores elegidos. Los prompts débiles producen puntuaciones complacientes. Una regex puede premiar el encabezado correcto aunque el contenido esté equivocado. Un juez LLM puede variar y añade tres votos por evaluador y ejecución.

El aislamiento supone otra limitación transparente. Cada ejecución empieza desde cero, por lo que no incluye archivos del proyecto, configuración del usuario, hooks ni servidores personales. Es excelente para la reproducibilidad y problemático cuando un caso omite declarar sus fixtures. Las herramientas que no pertenecen al conjunto de solo lectura requieren un permiso explícito en la línea de comandos. Los servidores MCP reales del plugin necesitan consentimiento y permisos adicionales; además, tanto los hooks como los servidores reales merecen un runner aislado porque pueden operar fuera del sandbox del agente.

Por último, no reduzca max_turns ni timeout_seconds hasta que un trabajo legítimo alcance el límite. Una ejecución que agota el tiempo o el máximo de turnos se registra como error y normalmente reduce la puntuación. Deje margen suficiente para la tarea prevista y utilice después el techo de costo estimado para controlar la suite completa.

El lunes, una persona responsable del plugin debería añadir un caso de activación, hacerlo fallar a propósito, restaurar el plugin y limitar el costo de esa misma comprobación en CI. Si quiere implantar ese sistema de lanzamiento en todos los plugins de su equipo, puedo ayudarle a diseñar la puerta de producción.