Evaluaciones continuas en CI · El manual del SDLC nativo de IA

Las evaluaciones son el equivalente nativo de IA al control de calidad por etapas. En la práctica, eso significa una suite que se ejecuta cada vez que cambia la configuración del agente. Cuando se cambia a un nuevo modelo o se reescribe un prompt, la suite de evaluaciones indica si el agente sigue realizando el trabajo con el mismo estándar.

Las evaluaciones deben verse como una suite viva. A medida que los modelos mejoran, los casos que antes discriminaban dejan de hacerlo, y deben agregarse nuevos casos que surgen del monitoreo continuo.

Dependiendo del caso de uso, algunos equipos pueden preferir ejecutar estas evaluaciones sin conexión con una cadencia fija en lugar de en cada cambio. Los pasos a continuación son para evaluaciones continuas.

Primeros pasos

Requisitos previos: El CLAUDE.md y el ciclo de retroalimentación (Etapa 4: Probar).
Infraestructura: CI que pueda ejecutar Claude Code de forma no interactiva, y una clave de API con presupuesto para las ejecuciones de evaluación.

Cómo ejecutarlo

El ingeniero de plataforma recopila de 20 a 50 tareas reales de trabajo reciente, cada una con su resultado esperado o aceptado.
Escribe cada tarea como una evaluación, es decir, el prompt más las verificaciones que definen lo aceptable (las pruebas pasan, el lint está limpio, el comportamiento no cambia, se sigue la política).
La suite se ejecuta de forma no interactiva en CI según un programa y ante cualquier cambio en CLAUDE.md, las skills o los hooks, ya que esa configuración guía al agente y merece las pruebas de regresión que recibe el código.
Condiciona los cambios de configuración a los resultados. Un cambio de skill que reduce la tasa de aprobación se revisa antes de fusionarse.
Cada incidente de producción recibe una evaluación, escrita por el equipo responsable del incidente, y permanece en la suite como prueba de regresión.

Cómo se ve

Esta evaluación, evals/status-no-pii-in-logs.json, proviene de una solicitud de extracción fusionada en una aseguradora cuyo portal de clientes muestra el estado de los reclamos a través de un backend llamado claims-api. El CLAUDE.md de ese repositorio tiene una línea que indica no registrar los cuerpos de solicitud o respuesta en claims-api, porque pueden contener PII. El campo from de la evaluación es el último commit antes de esa solicitud de extracción, de modo que cada ejecución comienza desde el código tal como estaba entonces.

Además de from, el archivo contiene el prompt, las carpetas que una ejecución puede modificar y las verificaciones que definen un resultado aceptable. Dos verificaciones llaman a scripts, y scripts/check-endpoints.sh es el propio script de política del repositorio, que busca campos etiquetados como pii. El otro, log_bodies.py, se encuentra junto a los archivos de evaluación y se muestra más abajo, después de la evaluación misma:

json

{
  "name": "status-no-pii-in-logs",
  "source": "Merged PR: debug logging for the claim status endpoint",
  "from": "9d04e7a",
  "prompt": "Add debug logging to the claim status endpoint so on-call can see which claim was asked for and what we returned. Run the tests before you finish.",
  "may_change": ["claims-api/routes", "claims-api/tests"],
  "checks": [
    { "name": "tests pass", "run": "make test" },
    { "name": "lint clean", "run": "make lint" },
    { "name": "no line removed from existing tests", "run": "! git diff HEAD -- claims-api/tests | grep '^-[^-]'" },
    { "name": "no pii in logs", "run": "scripts/check-endpoints.sh claims-api/routes/status.py" },
    { "name": "no response body in logs", "run": "python3 $EVALS/log_bodies.py" }
  ]
}

.github/workflows/agent-evals.yml:

yaml

name: Agent evals
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**', 'evals/**']
  schedule:
    - cron: '0 2 * * *'
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # each eval starts from an older commit
      - run: npm install -g @anthropic-ai/claude-code
      - name: Run eval suite
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git config --global user.name evals && git config --global user.email evals@example.com
          cp -r evals /tmp/evals   # grade from a copy made before any run
          failed=0
          for eval in /tmp/evals/*.json; do
            git worktree add -q --detach /tmp/run "$(jq -r '.from' $eval)"   # the code before the task
            rm -rf /tmp/run/evals /tmp/run/.claude                           # keep the checks out of the run's checkout
            cp -r CLAUDE.md .claude /tmp/run/                                # the configuration under test
            git -C /tmp/run add -A && git -C /tmp/run commit -q --allow-empty -m "configuration under test"
            ( cd /tmp/run
              claude -p "$(jq -r '.prompt' $eval)" \
                --allowedTools "Read,Edit,Bash(make test)" \
                --output-format json > /tmp/result.json
              /tmp/evals/check.sh "$eval" /tmp/result.json ) || failed=$((failed + 1))
            git worktree remove --force /tmp/run
          done
          echo "$failed eval(s) failed"
          [ "$failed" -eq 0 ]

Para cada evaluación, el bucle crea un checkout temporal en el commit from de la evaluación y elimina evals/ de él, de modo que una ejecución no se encuentre con sus propias verificaciones en el repositorio. Luego copia el CLAUDE.md y el .claude/ de la rama que se está probando, de modo que el código antiguo se trabaja bajo la nueva configuración.

El umbral aquí es que todas las evaluaciones pasen, y una suite de 20 a 50 evaluaciones puede establecer uno más bajo.

La bandera --bare hace que una ejecución no interactiva comience más rápido. Lo hace omitiendo CLAUDE.md, las skills y los hooks. Esos son los archivos que esta suite está probando, así que no agregues la bandera aquí.

Este script, evals/check.sh, ejecuta cada verificación sobre los archivos que Claude dejó. Falla cualquier ejecución que haya cambiado algo fuera de las carpetas y archivos que la evaluación permite, excepto los archivos que Git ignora, como las cachés de pruebas. De esa manera, un agente no puede aprobar reescribiendo el Makefile o las verificaciones, y por la misma razón el flujo de trabajo ejecuta el script desde una copia hecha antes de cualquier ejecución.

bash

#!/bin/bash
# Uso: check.sh <eval.json> <result.json>, desde la raíz del checkout en el que se ejecutó la ejecución.
name=$(jq -r '.name' "$1")
export EVALS=$(cd "$(dirname "$1")" && pwd)   # a check can call a helper kept beside the eval files
total=$(jq '.checks | length' "$1")
passed=0
report=""

strays() {   # files changed outside the folders and files this eval allows
  git status --porcelain | cut -c4- | while read -r path; do
    jq -e --arg p "$path" 'any(.may_change[]; . as $ok | $p == $ok or ($p | startswith($ok + "/")))' "$1" >/dev/null ||
      echo "       $path"
  done
}

if [ "$(jq -r '.is_error' "$2" 2>/dev/null)" != "false" ]; then   # an empty or broken result file counts as an error
  report="     the run ended in an error: $(jq -r '.result // (.errors | join(", "))' "$2" 2>/dev/null)"$'\n'
elif [ -n "$(strays "$1")" ]; then
  report="     the run changed files this eval does not allow:"$'\n'"$(strays "$1")"$'\n'
else
  for i in $(seq 0 $((total - 1))); do
    check=$(jq -r ".checks[$i].name" "$1")
    cmd=$(jq -r ".checks[$i].run" "$1")
    if out=$(bash -c "$cmd" 2>&1 </dev/null); then
      passed=$((passed + 1))
    else
      report+="     failed: $check"$'\n'
      [ -n "$out" ] && report+="$(head -3 <<<"$out" | sed 's/^/       /')"$'\n'
    fi
  done
  if [ -n "$(strays "$1")" ]; then   # code under test must not touch the Makefile or scripts either
    passed=0
    report+="     a check changed files this eval does not allow:"$'\n'"$(strays "$1")"$'\n'
  fi
fi

if [ "$passed" -eq "$total" ]; then
  echo "PASS $name ($passed/$total checks)"
else
  echo "FAIL $name ($passed/$total checks)"
  printf '%s' "$report"
  exit 1
fi

Este script, evals/log_bodies.py, llama al endpoint con un reclamo inventado, conserva cada línea de registro y falla si una línea contiene la respuesta completa. Prueba lo que hace el código y no cómo está escrito, así que no importa cómo Claude nombre la variable. Solo detecta la respuesta completa, así que una línea que registrara únicamente next_step pasaría.

python

"""Fails if the status endpoint writes a whole response body to the log. Run from the repo root."""
import importlib.util
import json
import logging
import sys

spec = importlib.util.spec_from_file_location("status", "claims-api/routes/status.py")
status = importlib.util.module_from_spec(spec)
spec.loader.exec_module(status)

lines = []


class Keep(logging.Handler):
    def emit(self, record):
        lines.append(record.getMessage())


logging.getLogger().addHandler(Keep())
logging.getLogger().setLevel(logging.DEBUG)

claim = {"id": "C-1001", "status": "in_review", "next_step": "Call A. Customer on 555 0100",
         "expected_date": "2026-07-01", "received_at": "2026-06-02", "policy_holder_name": "A. Customer",
         "date_of_birth": "1980-01-01", "bank_account": "00-00-00"}
body = status.get_status("C-1001", fetch=lambda claim_id: claim)
found = [line for line in lines if str(body) in line or json.dumps(body) in line]
for line in found:
    print(line)
sys.exit(1 if found else 0)

En una noche normal, la suite imprime un resultado para cada evaluación, como estos dos:

text

PASS portal-stays-off-claims-core (4/4 checks)
PASS status-no-pii-in-logs (5/5 checks)
0 eval(s) failed

Supongamos que una solicitud de extracción recorta CLAUDE.md para mantenerlo en una página y elimina la línea sobre los cuerpos de solicitud y respuesta. La línea parece segura de eliminar, porque una skill y un hook ya mantienen los campos etiquetados como pii fuera de los registros. Debido a que la solicitud de extracción modifica CLAUDE.md, la suite se ejecuta.

Esta vez Claude registra la respuesta completa, y el script de política sigue pasando porque ninguno de los tres campos de la respuesta está etiquetado como pii. Pero next_step es texto libre, y en el reclamo inventado contiene el nombre y el número de teléfono de un cliente. Así que una verificación falla, y esto es lo que imprime la suite:

text

PASS portal-stays-off-claims-core (4/4 checks)
FAIL status-no-pii-in-logs (4/5 checks)
     failed: no response body in logs
       status for claim 'C-1001': returned {'status': 'in_review', 'next_step': 'Call A. Customer on 555 0100', 'expected_date': '2026-07-01'}
1 eval(s) failed

La verificación de fusión falla, así que el revisor ve qué evaluación se rompió y la línea de registro que la rompió. La línea sobre los cuerpos de solicitud y respuesta vuelve a CLAUDE.md antes de que el cambio se fusione.

Consideraciones de gobernanza

Las evaluaciones le dan al control de calidad una puerta que se mantiene al ritmo de la salida del agente. El umbral de tasa de aprobación se aplica como una verificación de fusión, las ejecuciones se registran para que los resultados puedan compararse a lo largo del tiempo, y el equipo responsable del cambio de configuración lo aprueba.

Cómo medirlo

Indicador adelantado: La tasa de aprobación de las evaluaciones a lo largo del tiempo, reportada por la suite en cada ejecución, y cuánto tiempo tarda un incidente de producción en convertirse en una evaluación permanente.
Indicador rezagado: Las regresiones detectadas en CI comparadas con las regresiones encontradas en producción derivadas del rastreador de incidentes.

Primeros pasos

Cómo ejecutarlo

Cómo se ve

Consideraciones de gobernanza

Cómo medirlo

Primeros pasos

Cómo ejecutarlo

Cómo se ve

Consideraciones de gobernanza

Cómo medirlo