Kontinuierliche Evals in CI · Das KI-native SDLC-Playbook

Evals sind das KI-native Äquivalent zu Stage-Gate-QA. In der Praxis bedeutet das eine Suite, die immer dann läuft, wenn sich die Konfiguration des Agenten ändert. Wenn ein neues Modell eingesetzt oder ein Prompt umgeschrieben wird, zeigt die Eval-Suite, ob der Agent die Arbeit noch auf demselben Niveau erledigt.

Die Evals sollten als lebende Suite betrachtet werden. Wenn sich Modelle verbessern, hören Fälle, die früher unterschieden haben, auf, dies zu tun, und neue müssen hinzugefügt werden, die sich aus der laufenden Überwachung ergeben.

Je nach Anwendungsfall bevorzugen manche Teams es, diese Evals offline in einem festen Rhythmus auszuführen, statt bei jeder Änderung. Die folgenden Schritte gelten für kontinuierliche Evaluierungen.

Erste Schritte

Voraussetzungen: Die CLAUDE.md und die Feedback-Schleife (Stufe 4: Test).
Infrastruktur: CI, die Claude Code nicht interaktiv ausführen kann, und ein API-Key mit Budget für Eval-Läufe.

So wird es umgesetzt

Der Platform Engineer sammelt 20 bis 50 reale Aufgaben aus der jüngsten Arbeit, jeweils mit dem erwarteten oder akzeptierten Ergebnis.
Jede Aufgabe wird als Eval geschrieben, das heißt als Prompt plus die Prüfungen, die definieren, was akzeptabel ist (Tests bestehen, Lint sauber, Verhalten unverändert, Richtlinie eingehalten).
Die Suite läuft nicht interaktiv in CI nach einem Zeitplan und bei jeder Änderung an CLAUDE.md, Skills oder Hooks, da diese Konfiguration den Agenten steuert und dieselbe Regressionstestung verdient wie Code.
Konfigurationsänderungen werden anhand der Ergebnisse freigegeben. Eine Skill-Änderung, die die Erfolgsquote senkt, wird überprüft, bevor sie gemergt wird.
Jeder Produktionsvorfall erhält einen Eval, geschrieben vom Team, das für den Vorfall verantwortlich war, und bleibt als Regressionstest in der Suite.

So sieht es aus

Dieser Eval, evals/status-no-pii-in-logs.json, stammt aus einem gemergten Pull Request bei einem Versicherer, dessen Kundenportal den Schadenstatus über ein Backend namens claims-api anzeigt. Die CLAUDE.md dieses Repos enthält eine Zeile, die besagt, dass Request- oder Response-Bodies in claims-api nicht geloggt werden dürfen, da sie PII enthalten können. Das from-Feld des Evals ist der letzte Commit vor diesem Pull Request, sodass jeder Lauf vom Code in dem damaligen Zustand ausgeht.

Neben from enthält die Datei den Prompt, die Ordner, die ein Lauf ändern darf, und die Prüfungen, die ein akzeptables Ergebnis definieren. Zwei Prüfungen rufen Skripte auf, und scripts/check-endpoints.sh ist das eigene Richtlinienskript des Repos, das nach Feldern sucht, die mit pii markiert sind. Das andere, log_bodies.py, liegt neben den Eval-Dateien und wird weiter unten gezeigt, nach dem Eval selbst:

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 ]

Für jeden Eval erstellt die Schleife ein Scratch-Checkout beim from-Commit des Evals und löscht evals/ daraus, damit ein Lauf nicht auf seine eigenen Prüfungen im Repo stößt. Anschließend kopiert sie die CLAUDE.md und das .claude/-Verzeichnis des getesteten Branches hinein, sodass der alte Code unter der neuen Konfiguration bearbeitet wird.

Der Schwellenwert hier ist, dass jeder Eval bestehen muss, und eine Suite mit 20 bis 50 Evals kann einen niedrigeren festlegen.

Das Flag --bare lässt einen nicht interaktiven Lauf schneller starten. Es tut dies, indem es CLAUDE.md, Skills und Hooks überspringt. Das sind genau die Dateien, die diese Suite testet, also sollte das Flag hier nicht hinzugefügt werden.

Dieses Skript, evals/check.sh, führt jede Prüfung auf den von Claude zurückgelassenen Dateien aus. Es lässt jeden Lauf fehlschlagen, der etwas außerhalb der vom Eval erlaubten Ordner und Dateien geändert hat, mit Ausnahme von Dateien, die Git ignoriert, wie etwa Test-Caches. So kann ein Agent nicht bestehen, indem er das Makefile oder die Prüfungen umschreibt, und aus demselben Grund führt der Workflow das Skript von einer Kopie aus, die vor jedem Lauf erstellt wurde.

bash

#!/bin/bash
# Verwendung: check.sh <eval.json> <result.json>, ausgehend vom Root-Verzeichnis des Checkouts, in dem der Lauf ausgeführt wurde.
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

Dieses Skript, evals/log_bodies.py, ruft den Endpunkt mit einem erfundenen Schadensfall auf, behält jede Log-Zeile und schlägt fehl, wenn eine Zeile die gesamte Response enthält. Es prüft, was der Code tut, und nicht, wie er geschrieben ist, sodass es keine Rolle spielt, wie Claude die Variable benennt. Es erfasst nur die gesamte Response, sodass eine Zeile, die nur next_step loggt, bestehen würde.

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)

In einer normalen Nacht gibt die Suite für jeden Eval ein Ergebnis aus, wie diese beiden:

text

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

Angenommen, ein Pull Request kürzt CLAUDE.md, um sie unter einer Seite zu halten, und entfernt dabei die Zeile über Request- und Response-Bodies. Die Zeile scheint sicher entfernbar zu sein, da ein Skill und ein Hook bereits mit pii markierte Felder aus den Logs heraushalten. Da der Pull Request CLAUDE.md betrifft, läuft die Suite.

Dieses Mal loggt Claude die gesamte Response, und das Richtlinienskript besteht trotzdem, weil keines der drei Felder in der Response mit pii markiert ist. Aber next_step ist Freitext, und im erfundenen Schadensfall enthält es den Namen und die Telefonnummer eines Kunden. Also schlägt eine Prüfung fehl, und das gibt die Suite aus:

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

Die Merge-Prüfung schlägt fehl, sodass der Reviewer sieht, welcher Eval fehlgeschlagen ist und welche Log-Zeile ihn zum Scheitern gebracht hat. Die Zeile über Request- und Response-Bodies wird wieder in CLAUDE.md aufgenommen, bevor die Änderung gemergt wird.

Governance-Überlegungen

Evals geben der QA ein Gate, das mit der Ausgabe des Agenten Schritt hält. Der Schwellenwert für die Erfolgsquote wird als Merge-Prüfung durchgesetzt, Läufe werden protokolliert, damit Ergebnisse über die Zeit verglichen werden können, und das Team, das die Konfigurationsänderung verantwortet, genehmigt sie.

So wird es gemessen

Frühindikator: Die Eval-Erfolgsquote über die Zeit, die von der Suite bei jedem Lauf gemeldet wird, sowie die Zeit, die ein Produktionsvorfall benötigt, um zu einem dauerhaften Eval zu werden.
Spätindikator: In CI erkannte Regressionen im Vergleich zu in der Produktion gefundenen Regressionen, abgeleitet aus dem Incident-Tracker.

Erste Schritte

So wird es umgesetzt

So sieht es aus

Governance-Überlegungen

So wird es gemessen

Erste Schritte

So wird es umgesetzt

So sieht es aus

Governance-Überlegungen

So wird es gemessen