Évaluations continues en CI · Le guide pratique du SDLC natif à l'IA

Les évaluations (evals) sont l'équivalent natif de l'IA au contrôle qualité par jalons (stage-gate QA). En pratique, cela signifie une suite qui s'exécute chaque fois que la configuration de l'agent change. Lorsqu'un nouveau modèle est substitué ou qu'un prompt est réécrit, la suite d'évaluations indique si l'agent effectue toujours le travail selon la même norme.

Les évaluations doivent être considérées comme une suite vivante. À mesure que les modèles s'améliorent, les cas qui permettaient autrefois de discriminer cessent de le faire, et de nouveaux cas doivent être ajoutés, issus de la surveillance continue.

Selon le cas d'usage, certaines équipes peuvent préférer exécuter ces évaluations hors ligne selon une cadence fixe plutôt qu'à chaque changement. Les étapes ci-dessous concernent les évaluations continues.

Pour commencer

Prérequis : Le CLAUDE.md et la boucle de rétroaction (Étape 4 : Test).
Infrastructure : Un CI capable d'exécuter Claude Code de manière non interactive, et une clé API disposant d'un budget pour les exécutions d'évaluations.

Comment l'exécuter

L'ingénieur plateforme collecte 20 à 50 tâches réelles issues de travaux récents, chacune avec son résultat attendu ou accepté.
Rédigez chaque tâche sous forme d'évaluation, c'est-à-dire le prompt ainsi que les vérifications qui définissent ce qui est acceptable (tests réussis, lint propre, comportement inchangé, politique respectée).
La suite s'exécute de manière non interactive en CI selon un calendrier et à chaque modification de CLAUDE.md, des Compétences ou des hooks, car cette configuration pilote l'agent et mérite les tests de régression dont bénéficie le code.
Conditionnez les modifications de configuration aux résultats. Une modification de Compétence qui fait baisser le taux de réussite est examinée avant sa fusion.
Chaque incident de production donne lieu à une évaluation, rédigée par l'équipe responsable de l'incident, qui reste dans la suite comme test de régression.

À quoi cela ressemble

Cette évaluation, evals/status-no-pii-in-logs.json, provient d'une pull request fusionnée chez un assureur dont le portail client affiche le statut des réclamations via un backend appelé claims-api. Le CLAUDE.md de ce dépôt contient une ligne indiquant de ne pas journaliser les corps des requêtes ou des réponses dans claims-api, car ils peuvent contenir des PII. Le champ from de l'évaluation correspond au dernier commit avant cette pull request, de sorte que chaque exécution démarre à partir du code tel qu'il était à ce moment-là.

Outre from, le fichier contient le prompt, les dossiers qu'une exécution peut modifier, et les vérifications qui définissent un résultat acceptable. Deux vérifications appellent des scripts, et scripts/check-endpoints.sh est le script de politique propre au dépôt, qui recherche les champs marqués pii. L'autre, log_bodies.py, se trouve à côté des fichiers d'évaluation et est présenté plus bas, après l'évaluation elle-même :

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 ]

Pour chaque évaluation, la boucle effectue un checkout vierge au commit from de l'évaluation et supprime evals/ de celui-ci, afin qu'une exécution ne rencontre pas ses propres vérifications dans le dépôt. Elle copie ensuite le CLAUDE.md et le .claude/ de la branche testée, afin que l'ancien code soit traité sous la nouvelle configuration.

Le seuil ici est que toutes les évaluations réussissent, et une suite de 20 à 50 évaluations peut en fixer un plus bas.

L'option --bare permet à une exécution non interactive de démarrer plus rapidement. Elle le fait en ignorant CLAUDE.md, les Compétences et les hooks. Ce sont précisément les fichiers que cette suite teste, donc n'ajoutez pas cette option ici.

Ce script, evals/check.sh, exécute chaque vérification sur les fichiers laissés par Claude. Il fait échouer toute exécution ayant modifié quelque chose en dehors des dossiers et fichiers autorisés par l'évaluation, à l'exception des fichiers ignorés par Git, comme les caches de test. Ainsi, un agent ne peut pas réussir en réécrivant le Makefile ou les vérifications, et pour la même raison, le workflow exécute le script à partir d'une copie réalisée avant toute exécution.

bash

#!/bin/bash
# Utilisation : check.sh <eval.json> <result.json>, depuis la racine du checkout dans lequel l'exécution a eu lieu.
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

Ce script, evals/log_bodies.py, appelle le point de terminaison avec une réclamation fictive, conserve chaque ligne de journal, et échoue si une ligne contient la réponse entière. Il teste ce que fait le code et non la façon dont il est écrit, donc le nom que Claude donne à la variable n'a pas d'importance. Il ne détecte que la réponse entière, donc une ligne qui journaliserait uniquement next_step réussirait.

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)

Lors d'une nuit normale, la suite affiche un résultat pour chaque évaluation, comme ces deux-ci :

text

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

Supposons qu'une pull request réduise CLAUDE.md pour le maintenir sous une page et supprime la ligne concernant les corps des requêtes et des réponses. Cette ligne semble pouvoir être supprimée sans risque, car une Compétence et un hook empêchent déjà les champs marqués pii d'apparaître dans les journaux. Comme la pull request modifie CLAUDE.md, la suite s'exécute.

Cette fois, Claude journalise la réponse entière, et le script de politique réussit toujours car aucun des trois champs de la réponse n'est marqué pii. Mais next_step est du texte libre, et dans la réclamation fictive, il contient le nom et le numéro de téléphone d'un client. Une vérification échoue donc, et voici ce que la suite affiche :

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 vérification de fusion échoue, de sorte que le relecteur voit quelle évaluation a échoué et la ligne de journal qui en est la cause. La ligne concernant les corps des requêtes et des réponses est réintégrée dans CLAUDE.md avant que la modification ne soit fusionnée.

Considérations de gouvernance

Les évaluations offrent au contrôle qualité un verrou qui suit le rythme de la production de l'agent. Le seuil de taux de réussite est appliqué comme vérification de fusion, les exécutions sont journalisées afin que les résultats puissent être comparés dans le temps, et l'équipe propriétaire de la modification de configuration l'approuve.

Comment le mesurer

Indicateur avancé : Le taux de réussite des évaluations dans le temps, rapporté par la suite à chaque exécution, et le temps nécessaire pour qu'un incident de production devienne une évaluation permanente.
Indicateur retardé : Les régressions détectées en CI comparées aux régressions trouvées en production, issues du suivi des incidents.

Pour commencer

Comment l'exécuter

À quoi cela ressemble

Considérations de gouvernance

Comment le mesurer

Pour commencer

Comment l'exécuter

À quoi cela ressemble

Considérations de gouvernance

Comment le mesurer