読み込み中

評価(evals)は、ステージゲート型QAのAIネイティブな等価物です。実際には、エージェントの設定が変更されるたびに実行されるスイートを意味します。新しいモデルに切り替えられたり、プロンプトが書き直されたりしたとき、評価スイートはエージェントが同じ水準で作業を行えているかどうかを示します。

評価はライブスイートとして捉えるべきです。モデルが改善するにつれて、かつては判別に役立っていたケースが役に立たなくなり、継続的なモニタリングから生じる新しいケースを追加する必要があります。

ユースケースによっては、すべての変更ごとではなく、一定の周期でこれらの評価をオフラインで実行することを好むチームもあります。以下の手順は継続的評価のためのものです。

はじめに

  • 前提条件:CLAUDE.mdとフィードバックループ(ステージ4:テスト)。
  • インフラストラクチャ:Claude Codeを非対話的に実行できるCIと、評価実行のための予算を持つAPIキー。

実行方法

  1. プラットフォームエンジニアが、直近の作業から20〜50件の実際のタスクを、それぞれの期待される結果または許容される結果とともに収集します。
  2. 各タスクを評価として記述します。つまり、プロンプトと、許容可能であることを定義するチェック(テストが通る、lintがクリーンである、動作が変わらない、ポリシーに従っている)です。
  3. スイートはスケジュールに従って、またCLAUDE.md、スキル、フックへの変更があるたびにCIで非対話的に実行されます。これらの設定はエージェントを導く役割を持ち、コードが受けるのと同じ回帰テストに値するためです。
  4. 設定変更を結果に基づいてゲートします。合格率を下げるスキル変更は、マージされる前にレビューされます。
  5. 各本番インシデントには、そのインシデントを担当したチームによって書かれた評価が作成され、回帰テストとしてスイートに残ります。

実際の様子

この評価、evals/status-no-pii-in-logs.jsonは、claims-apiというバックエンドを通じて顧客ポータルに請求状況を表示する保険会社でマージされたプルリクエストから来ています。そのリポジトリのCLAUDE.mdには、claims-apiでリクエストやレスポンスのボディをログに記録しないようにという1行があります。これらはPIIを含む可能性があるためです。この評価のfromフィールドは、そのプルリクエストの直前のコミットであり、各実行はその時点のコードから開始されます。

fromのほかに、このファイルにはプロンプト、実行が変更してよいフォルダ、そして許容される結果を定義するチェックが含まれています。2つのチェックはスクリプトを呼び出し、scripts/check-endpoints.shはリポジトリ自身のポリシースクリプトで、piiとタグ付けされたフィールドを探します。もう一方のlog_bodies.pyは評価ファイルのそばに置かれており、評価自体の後、さらに下で示されています。

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 ]

各評価について、ループは評価のfromコミットでスクラッチチェックアウトを作成し、そこからevals/を削除します。これにより、実行がリポジトリ内で自分自身のチェックに遭遇することがなくなります。その後、テスト対象のブランチのCLAUDE.mdと.claude/をコピーし、古いコードが新しい設定のもとで作業されるようにします。

ここでの閾値はすべての評価が合格することであり、20〜50件の評価スイートではより低い閾値を設定することもあります。

--bareフラグは非対話的な実行をより速く開始させます。これはCLAUDE.md、スキル、フックをスキップすることによって行われます。これらはこのスイートがテストしているファイルそのものなので、ここではこのフラグを追加しないでください。

通常の夜には、スイートは各評価について結果を出力します。例えば次の2つのようにです。

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

あるプルリクエストがCLAUDE.mdを1ページ以内に収めるために削り、リクエストとレスポンスのボディに関する行を削除したとします。スキルとフックが既にpiiとタグ付けされたフィールドをログから除外しているため、この行を削除しても安全に見えます。このプルリクエストがCLAUDE.mdに触れるため、スイートが実行されます。

今回Claudeはレスポンス全体をログに記録し、レスポンス内の3つのフィールドのいずれもpiiとタグ付けされていないため、ポリシースクリプトは依然として合格します。しかしnext_stepは自由記述のテキストであり、架空の請求ではそこに顧客の名前と電話番号が含まれています。そのため1つのチェックが失敗し、スイートは次のように出力します。

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

マージチェックが失敗するため、レビュアーはどの評価が壊れたか、そしてそれを壊したログ行を確認できます。リクエストとレスポンスのボディに関する行は、変更がマージされる前にCLAUDE.mdに戻されます。

ガバナンス上の考慮事項

評価は、エージェントの出力に追随するゲートをQAに提供します。合格率の閾値はマージチェックとして強制され、実行はログに記録されるため結果を時間の経過とともに比較でき、設定変更を所有するチームがそれを承認します。

測定方法

  • 先行指標:スイートが各実行で報告する、時間経過に伴う評価合格率、および本番インシデントが永続的な評価になるまでにかかる時間。
  • 遅行指標:インシデントトラッカーから導き出された、本番環境で見つかった回帰と比較した、CIで捕捉された回帰。