# Ewaluacja agentów, promptów i zmian w CLAUDE.md: promptfoo, Inspect SWE, Langfuse i Braintrust

URL: https://developertoolkit.ai/pl/ecosystem/observability/evals-coding-agents/
Description: Test A/B zmiany w CLAUDE.md lub AGENTS.md na stałym zestawie zadań w promptfoo lub Inspect SWE i śledzenie nieudanych sesji w Langfuse lub Braintrust.

Ewaluacja agenta kodującego polega na uruchomieniu stałego zestawu prawdziwych zadań na dwóch konfiguracjach i porównaniu wyników, które da się sprawdzić kodem. promptfoo uruchamia Claude Code i Codex przez ich SDK, Inspect SWE uruchamia je w sandboksach Dockera, a Langfuse lub Braintrust śledzą każdą sesję, żeby dało się wyjaśnić, dlaczego zadanie się nie udało.

Ktoś z zespołu otwiera pull request, który skraca `CLAUDE.md` z 400 do 120 linii i dodaje dwie nowe reguły. W wątku review jest sześć opinii i zero danych: jedna osoba twierdzi, że po dniu z nowym plikiem agent „wydaje się bystrzejszy”, druga, że przestał uruchamiać testy. Za chwilę scalisz zmianę, którą przeczyta każda sesja agenta w repozytorium, i nikt nie potrafi powiedzieć, czy pomaga. Ta strona jest dla **programisty**, który buduje ewaluację, i dla **tech leada**, który decyduje, czy zmiana reguł trafi do `main`.

## Co daje ci ewaluacja reguł agenta

- **Konfigurację promptfoo, która robi test A/B dwóch wariantów `CLAUDE.md`** na tych samych zadaniach, tym samym commicie i tym samym przypiętym modelu, z deterministycznymi kontrolami (testy przechodzą, diff mieści się w zakresie, testy zostały uruchomione) przed jakąkolwiek oceną przez model.
- **Ten sam eksperyment dla Codeksa i `AGENTS.md`** oraz drogę dla Cursora, dla którego promptfoo nie ma providera.
- **Zadanie Inspect SWE** na wypadek, gdy każde uruchomienie ma działać w jednorazowym sandboksie Dockera, a klucz do modelu ma zostać na hoście.
- **Regułę decyzyjną** do czytania wyników, żeby zmianę reguł scalać na podstawie dowodów, a nie wrażeń.
- **Miejsce platform śledzenia**: Langfuse, Braintrust, Opik i Phoenix wyjaśniają, *dlaczego* zadanie się nie udało; nie zastępują stałego zestawu zadań.
- **Trzy prompty do skopiowania** i tabelę awarii, czyli sposobów, na które takie eksperymenty po cichu nic nie mierzą.

Każde polecenie i klucz konfiguracji poniżej sprawdziliśmy 2026-09-26 na promptfoo 0.123.1, inspect-ai 0.3.269 z inspect-swe 0.2.71, Claude Code 2.1.283 i Codex CLI 0.157.1. Ogólną metodę budowania zestawu ewaluacyjnego do wyboru *modelu* opisuje strona [jak czytać benchmarki i budować własne ewaluacje](/pl/ecosystem/models/benchmarks/); ta strona dotyczy ewaluacji zmian w *twoim harnessie*: plikach reguł, promptach, skillach i pluginach.

## Które narzędzie odpowiada na które pytanie?

Zacznij od pytania. Pierwsze trzy wiersze uruchamiają agenta; pozostałe go obserwują albo testują coś, co sam dostarczasz.

| Pytanie | Narzędzie | Uruchamia agenta? | Gdzie działa |
| --- | --- | --- | --- |
| Czy nowy `CLAUDE.md` lub `AGENTS.md` jest lepszy na naszych zadaniach? | promptfoo (`anthropic:claude-agent-sdk`, `openai:codex-sdk`) | Tak, przez SDK dostawcy | Twoja maszyna lub runner CI |
| To samo, ale każde uruchomienie w osobnym kontenerze, kilku agentów w jednym harnessie | Inspect AI + Inspect SWE (`claude_code()`, `codex_cli()`) | Tak, w sandboksie; wywołania modelu idą przez Inspect | Docker lub Kubernetes |
| Czy ten plugin lub skill pomaga w porównaniu z brakiem pluginu? | `claude plugin eval` (Claude Code 2.1.283) | Tak, z ramieniem bazowym bez pluginu | Twoja maszyna |
| Dlaczego ta sesja się nie udała i ile kosztowała? | Plugin Langfuse, Braintrust `bt trace`, Opik | Nie, śledzi prawdziwe sesje | SaaS lub self-hosted |
| Lokalny interfejs śladów OpenTelemetry bez konta | Arize Phoenix | Nie | Twoja maszyna |
| Czy funkcja LLM, *którą dostarczamy*, ma regresję albo wycieka dane? | DeepEval, garak, OpenLLMetry | Nie, testuje twoją aplikację | CI, twoja aplikacja |

Popularność na 2026-09-26, według GitHuba i rejestrów pakietów: [promptfoo](https://github.com/promptfoo/promptfoo) 25,5 tys. gwiazdek (npm 0.123.1; README podaje, że projekt „is now part of OpenAI” i pozostaje na licencji MIT), [Langfuse](https://github.com/langfuse/langfuse) 35,1 tys. (samo repozytorium pluginu do Claude Code: 24), [Opik](https://github.com/comet-ml/opik) 22,2 tys., [DeepEval](https://github.com/confident-ai/deepeval) 18,4 tys., [Arize Phoenix](https://github.com/Arize-ai/phoenix) 11,6 tys., [garak](https://github.com/NVIDIA/garak) 9,4 tys., [OpenLLMetry](https://github.com/traceloop/openllmetry) 7,4 tys., [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai) 2,9 tys. i [Inspect SWE](https://github.com/meridianlabs-ai/inspect_swe) 33. [Monorepo pluginów Braintrust dla agentów kodujących](https://github.com/braintrustdata/braintrust-coding-agent-plugins) miało 2 gwiazdki (npm `braintrust` 3.35.0). Platformy są dojrzałe; ich pluginy do agentów kodujących mają po kilka miesięcy.

## Test A/B zmiany w CLAUDE.md w promptfoo

Eksperyment ma jedną zmienną. Oba ramiona dostają ten sam commit repozytorium, te same zadania, ten sam model i te same uprawnienia narzędzi; różni się tylko plik reguł. promptfoo uruchamia każde zadanie w każdym ramieniu, odpala twoje kontrole i pokazuje obok siebie odsetek zaliczonych zadań, koszt i czas dla każdego ramienia.

1. **Zbuduj stały zestaw 10–20 prawdziwych zadań.** Weź je ze scalonych pull requestów, które przyszły z testami: poprawka błędu, mała funkcja, refaktoryzacja, dopisanie testów. Każde zadanie potrzebuje promptu, jaki programista naprawdę by napisał, i kontroli, którą da się uruchomić kodem. Zamroź listę; zmiana zadań między przebiegami psuje porównanie.

2. **Utwórz dwa worktree poza repozytorium**, oba na tym samym commicie, i zacommituj proponowane reguły w drugim. Claude Code czyta pliki `CLAUDE.md` także z katalogów nadrzędnych, więc worktree wewnątrz repozytorium wczytałby do ramienia „proposed” również obecny plik. W terminalu, z katalogu głównego repozytorium:

   ```bash
   BASE=$(git rev-parse origin/main)
   mkdir -p ../rules-ab
   git worktree add --detach ../rules-ab/current "$BASE"
   git worktree add --detach ../rules-ab/proposed "$BASE"
   git show origin/trim-claude-md:CLAUDE.md > ../rules-ab/proposed/CLAUDE.md
   git -C ../rules-ab/proposed add CLAUDE.md && git -C ../rules-ab/proposed commit -qm "eval: proposed CLAUDE.md"
   (cd ../rules-ab/current && npm ci) && (cd ../rules-ab/proposed && npm ci)
   cd ../rules-ab && npm install --save-dev promptfoo@0.123.1 @anthropic-ai/claude-agent-sdk
   ```

   `trim-claude-md` oznacza gałąź ocenianego pull requesta. Zacommitowanie proponowanego pliku pozwala hookowi resetu przywrócić każde ramię do czystego stanu przez `git reset --hard` bez utraty testowanych reguł.

3. **Napisz konfigurację.** Zapisz ją jako `../rules-ab/promptfooconfig.yaml`. Oba providery są identyczne poza `label` i `working_dir`:

   ```yaml title="rules-ab/promptfooconfig.yaml"
   description: CLAUDE.md A/B on a fixed task set
   prompts:
     - '{{task}}'
   providers:
     - id: anthropic:claude-agent-sdk
       label: current
       config:
         working_dir: ./current
         setting_sources: ['project']      # load CLAUDE.md from working_dir; no user-level files
         model: claude-opus-5-5            # pin it: a default that moves mid-experiment ruins the A/B
         tools: ['Read', 'Grep', 'Glob', 'Write', 'Edit', 'Bash']   # what the agent can see
         permission_mode: dontAsk          # anything that would prompt is denied, never prompted
         append_allowed_tools: ['Write', 'Edit', 'Bash(npm test:*)', 'Bash(npx tsc:*)']
         disallowed_tools: ['WebFetch', 'WebSearch']
         max_turns: 40
         max_budget_usd: 3
     - id: anthropic:claude-agent-sdk
       label: proposed
       config:
         working_dir: ./proposed
         setting_sources: ['project']
         model: claude-opus-5-5
         tools: ['Read', 'Grep', 'Glob', 'Write', 'Edit', 'Bash']   # what the agent can see
         permission_mode: dontAsk          # anything that would prompt is denied, never prompted
         append_allowed_tools: ['Write', 'Edit', 'Bash(npm test:*)', 'Bash(npx tsc:*)']
         disallowed_tools: ['WebFetch', 'WebSearch']
         max_turns: 40
         max_budget_usd: 3
   extensions:
     - file://reset.js:extensionHook
   defaultTest:
     options:
       provider: openai:responses:gpt-6-sol   # the judge comes from another vendor than the agent
     assert:
       - type: javascript
         value: file://checks.js:testsPass
         metric: tests_pass
       - type: javascript
         metric: ran_tests
         value: |
           const calls = context.providerResponse?.metadata?.toolCalls || [];
           return calls.some(t => t.name === 'Bash' && t.input?.command?.includes('npm test'));
       - type: llm-rubric
         metric: conventions
         value: >-
           The final message states what changed and why, and names the tests it ran.
           You see only this message, not the diff.
   tests:
     - description: invoice rounding bug (from PR 1841)
       vars:
         task: >-
           Invoice totals are one cent off when a line has quantity 3 and unit price 0.10.
           Fix it in src/billing and add a regression test.
       assert:
         - type: javascript
           metric: in_scope
           value: file://checks.js:diffInScope
           config: { allowedPrefixes: ['src/billing/', 'test/billing/'] }
     # ...9 to 19 more tasks in the same shape
   ```

   W providerze promptfoo `setting_sources` jest domyślnie wyłączone, więc bez tego klucza żadne ramię nie czyta `CLAUDE.md` i oba ramiona są tym samym eksperymentem powtórzonym dwa razy. Ustaw też jawnie `tools`: przy podanym `working_dir` i braku `tools` promptfoo 0.123.1 wyprowadza listę narzędzi z wpisów o dozwolonych narzędziach, a wzorzec w rodzaju `Bash(npm test:*)` to reguła uprawnień, nie nazwa narzędzia. `tools` decyduje, co agent w ogóle może wywołać; `append_allowed_tools` – co wykona się bez pytania; `dontAsk` odrzuca to, o co agent w innym trybie by zapytał. Aktualny identyfikator modelu weź z [porównania modeli](/pl/ecosystem/models/) w dniu, w którym uruchamiasz test.

4. **Dodaj kontrole i hook resetu** obok konfiguracji. Kontrole zaglądają do katalogu roboczego ramienia po zakończeniu pracy agenta; hook przywraca oba ramiona do ich commita po każdym teście.

   ```js title="rules-ab/checks.js"
   const { execFileSync } = require('node:child_process');
   const path = require('node:path');

   const dirOf = (context) => path.join(__dirname, context.provider.label);
   const run = (cmd, args, cwd) => {
     try {
       return { ok: true, out: execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: 'pipe', timeout: 600000 }) };
     } catch (err) {
       return { ok: false, out: `${err.stdout || ''}${err.stderr || ''}` };
     }
   };

   module.exports.testsPass = (output, context) => {
     const r = run('npm', ['test', '--silent'], dirOf(context));
     return { pass: r.ok, score: r.ok ? 1 : 0, reason: r.ok ? 'npm test passed' : r.out.slice(-800) };
   };

   module.exports.diffInScope = (output, context) => {
     const cwd = dirOf(context);
     const changed = run('git', ['diff', '--name-only', 'HEAD'], cwd).out;
     const added = run('git', ['ls-files', '--others', '--exclude-standard'], cwd).out;
     const files = `${changed}\n${added}`.split('\n').filter(Boolean);
     const outside = files.filter((f) => !context.config.allowedPrefixes.some((p) => f.startsWith(p)));
     return { pass: outside.length === 0, score: outside.length ? 0 : 1, reason: outside.length ? `outside scope: ${outside.join(', ')}` : `${files.length} files, all in scope` };
   };
   ```

   ```js title="rules-ab/reset.js"
   const { execFileSync } = require('node:child_process');
   const path = require('node:path');

   function reset() {
     for (const arm of ['current', 'proposed']) {
       const cwd = path.join(__dirname, arm);
       execFileSync('git', ['reset', '--hard', '--quiet', 'HEAD'], { cwd });
       execFileSync('git', ['clean', '-fdq'], { cwd });   // keeps ignored files such as node_modules
     }
   }

   module.exports.extensionHook = async (hookName) => {
     if (hookName === 'beforeAll' || hookName === 'afterEach') reset();
   };
   ```

5. **Uruchamiaj sekwencyjnie, trzy razy na zadanie, z wyłączonym cache.** Sekwencyjnie, bo oba ramiona dzielą hook resetu; trzy powtórzenia, bo jedno uruchomienie agenta na zadanie daje za dużo szumu do porównań; bez cache, bo odpowiedź z cache nie jest nowym uruchomieniem.

   ```bash
   cd ../rules-ab
   # Load ANTHROPIC_API_KEY (the agent) and OPENAI_API_KEY (the judge) into the environment
   # from your secret manager; never type a key on the command line. To use your local
   # Claude Code login instead of an API key, add apiKeyRequired: false to both providers.
   npx promptfoo eval -j 1 --repeat 3 --no-cache -o results.json
   npx promptfoo view
   ```

   `promptfoo eval` kończy się kodem `100`, gdy choć jeden test nie przejdzie, więc to samo polecenie posłuży później jako bramka w CI. `promptfoo view` otwiera macierz w przeglądarce: kolumna na ramię, wiersz na zadanie, z nazwanymi metrykami (`tests_pass`, `ran_tests`, `conventions`, `in_scope`) i kosztem w każdej komórce.

**Agent wykonuje prawdziwe polecenia na maszynie, na której działa ewaluacja**

Konfiguracja automatycznie zatwierdza edycje plików i tylko dwa prefiksy poleceń, a narzędzia WebFetch i WebSearch blokuje. `permission_mode: dontAsk` odrzuca każde inne wywołanie, które wymagałoby pytania, zamiast czekać na zatwierdzenie, którego nikt nie da. Mimo to uruchamiaj eksperyment na jednorazowej maszynie lub w kontenerze, w którym jest tylko kopia repozytorium i klucze do modeli: żadnych poświadczeń chmurowych, kluczy SSH ani produkcyjnych plików `.env`.

## Ten sam eksperyment w Claude Code, Codeksie i Cursorze

Zestaw zadań, kontrole i reguła decyzyjna się nie zmieniają. Zmienia się provider i plik reguł, który czyta dany agent.

**Claude Code**

    Użyj konfiguracji powyżej. Identyfikatory providera to `anthropic:claude-agent-sdk` i alias `anthropic:claude-code`; `anthropic:claude-code-sdk` nie istnieje. promptfoo 0.123.1 instaluje `@anthropic-ai/claude-agent-sdk` 0.3.263 jako opcjonalną zależność; jawna instalacja, jak w kroku 2, daje bieżące wydanie (npm 0.3.283 na 2026-09-26) i obejmuje instalacje pomijające opcjonalne zależności.

    Do testu A/B **skilla lub pluginu** zamiast pliku reguł Claude Code 2.1.283 ma wbudowany runner. Czyta przypadki z katalogu `evals/` pluginu i sam dodaje ramię bazowe bez pluginu:

    ```bash
    claude plugin eval ./plugins/release-notes --runs 3 --threshold 0.8 --no-publish
    ```

    Pierwsze uruchomienie w nowym katalogu pluginu prosi o potwierdzenie zaufania; w CI przekaż `--trust-plugin`, i to tylko dla pluginów, które sam byś uruchomił. `--threshold` sprawia, że polecenie kończy się kodem `1`, gdy którykolwiek przypadek wypadnie poniżej progu, a `--max-cost-usd` ustawia twardy limit kosztu przebiegu. Kod pluginu działa z twoimi uprawnieniami, więc oceniaj tylko pluginy, którym ufasz. Format przypadków opisuje strona [budowa i dystrybucja pluginu](/pl/ecosystem/plugins/building-plugins/).

**Codex**

    Codex czyta `AGENTS.md`, więc warianty różnią się tym plikiem. Zamień oba providery na providera Codex SDK; `openai:codex` to alias. promptfoo 0.123.1 deklaruje `@openai/codex-sdk` `^0.153.2` jako opcjonalną zależność (npm 0.157.1 na 2026-09-26).

    ```yaml title="rules-ab/promptfooconfig.yaml (providers only)"
    providers:
      - id: openai:codex-sdk
        label: current
        config:
          working_dir: ./current
          model: gpt-6-astra
          sandbox_mode: workspace-write     # writes stay inside working_dir
          approval_policy: never
          network_access_enabled: false
      - id: openai:codex-sdk
        label: proposed
        config:
          working_dir: ./proposed
          model: gpt-6-astra
          sandbox_mode: workspace-write
          approval_policy: never
          network_access_enabled: false
    ```

    Usuń asercję `ran_tests`: czyta wywołania narzędzi w formacie Claude. Kontrole `testsPass` i `diffInScope` działają bez zmian. Od Codeksa 0.150.0 niezaufane projekty nie dostarczają projektowego `AGENTS.md`; oznacz obie ścieżki worktree jako zaufane i zanim uwierzysz w remis, uruchom regułę-kanarka na ramionach Codeksa.

**Cursor**

    promptfoo 0.123.1 nie ma providera dla Cursora (sprawdzone w indeksie providerów na tagu `0.123.1`). Zachowaj zestaw zadań i kontrole, a uruchom je przez agenta `cursor-cli` w [Harborze](/pl/ecosystem/models/benchmarks/) (Harbor 0.23.0, 2026-09-12). Instaluje on Cursor CLI w kontenerze każdego zadania i steruje nim w trybie print z automatycznym zatwierdzaniem. Przygotuj dwa katalogi zadań, które różnią się wyłącznie plikami reguł wbudowanymi w obraz zadania, i uruchom oba. Załaduj `CURSOR_API_KEY` do środowiska z menedżera sekretów; Harbor przekazuje go do kontenera zadania.

    ```bash
    harbor run -p evals/tasks-current  -a cursor-cli -m "$CURSOR_MODEL" -k 3 -n 4
    harbor run -p evals/tasks-proposed -a cursor-cli -m "$CURSOR_MODEL" -k 3 -n 4
    ```

    `CURSOR_MODEL` podajesz w formacie Harbora `provider/model`; Harbor przekazuje Cursorowi część po ukośniku, więc użyj nazwy modelu dostępnej w twoim planie Cursora. `-k 3` to trzy próby na zadanie, `-n 4` – cztery równolegle. Harbor zatwierdza każde polecenie automatycznie, więc jedyną granicą jest kontener zadania: nie wkładaj do niego żadnych poświadczeń poza kluczem Cursora i ogranicz jego ruch wychodzący do API Cursora oraz hostów, z których pobiera instalator. Układ zadań, przebiegi kontrolne `oracle` i `nop` oraz pozostałe flagi opisuje strona o benchmarkach.

    Dokumentacja Cursora (sprawdzone 2026-10-12) mówi, że reguły projektu leżą w `.cursor/rules` jako pliki `.mdc` (zwykły plik `.md` jest tam ignorowany), że Cursor obsługuje `AGENTS.md` w katalogu głównym projektu i w podkatalogach oraz że reguły dotyczą wyłącznie czatu Agenta. Ta strona nie testowała, czy Cursor w trybie print w Harborze je wczytuje. Przed pierwszym przebiegiem dodaj do obu ramion regułę-kanarka, np. „zakończ każdą końcową wiadomość słowem CANARY”, i sprawdź, czy się pojawia. Plik reguł, który się nie wczytuje, daje idealny remis.

## Test A/B w sandboksie z Inspect SWE

Wybierz Inspect SWE, gdy każde uruchomienie ma działać w świeżym kontenerze albo gdy chcesz jednego harnessu dla kilku agentów: agenci `claude_code()` i `codex_cli()` działają w sandboksie próbki, a ich wywołania modelu wracają przez Inspect. Dzięki temu limity tokenów i czasu oraz transkrypty działają jak w każdej ewaluacji Inspect, a klucz API nigdy nie trafia do kontenera.

```python title="rules_ab.py"
from pathlib import Path

from inspect_ai import Task, task
from inspect_ai.dataset import json_dataset
from inspect_ai.scorer import CORRECT, INCORRECT, Score, Target, accuracy, scorer, stderr
from inspect_ai.solver import Generate, TaskState, solver
from inspect_ai.util import sandbox
from inspect_swe import claude_code

@solver
def install_rules(rules_file: str):
    async def solve(state: TaskState, generate: Generate) -> TaskState:
        await sandbox().write_file("/repo/CLAUDE.md", Path(rules_file).read_text())
        return state
    return solve

@scorer(metrics=[accuracy(), stderr()])
def tests_pass():
    async def score(state: TaskState, target: Target) -> Score:
        result = await sandbox().exec(["npm", "test", "--silent"], cwd="/repo")
        return Score(value=CORRECT if result.success else INCORRECT, explanation=result.stderr[-800:])
    return score

@task
def rules_ab(rules: str = "rules/current.md") -> Task:
    return Task(
        dataset=json_dataset("tasks.jsonl"),        # one {"id", "input", "target"} per line
        setup=install_rules(rules),
        solver=claude_code(cwd="/repo", disallowed_tools=["WebSearch", "WebFetch"]),
        scorer=tests_pass(),
        sandbox=("docker", "compose.yaml"),         # image with the repository at /repo, deps installed, no secrets
        epochs=3,
    )
```

Uruchom każde ramię, a potem porównaj je w przeglądarce logów:

```bash
pip install inspect-ai==0.3.269 inspect-swe==0.2.71
inspect eval rules_ab.py --model anthropic/claude-opus-5-5 -T rules=rules/current.md
inspect eval rules_ab.py --model anthropic/claude-opus-5-5 -T rules=rules/proposed.md
inspect view
```

Dla Codeksa zaimportuj `codex_cli` i zapisuj `AGENTS.md`. W Inspect SWE 0.2.71 `codex_cli()` domyślnie używa `sandbox_mode="danger-full-access"` (własny sandbox Codeksa wyłączony) i `web_search="live"`. Pierwsze jest do przyjęcia tylko dlatego, że granicą jest kontener Inspect, więc nie trzymaj w nim żadnych poświadczeń i zablokuj jego ruch wychodzący: wywołania modelu i tak wracają przez Inspect, więc agent nie potrzebuje bezpośredniego wyjścia do sieci. Obu ramionom przekaż `web_search="disabled"` – odpowiednik `disallowed_tools=["WebSearch", "WebFetch"]` po stronie Claude Code – żeby żadne nie mogło wyszukać odpowiedzi w sieci. Pakiet z PyPI instalujesz przez `pip install inspect-swe`; polecenie z README projektu instaluje wersję deweloperską z gita.

## Jak podjąć decyzję na podstawie wyników?

Zapisz regułę przed uruchomieniem, żeby wyniku nie dało się dopasować do odpowiedzi, której ktoś chciał.

| Wynik | Decyzja |
| --- | --- |
| `tests_pass` dla proposed co najmniej taki jak dla current, `in_scope` i `ran_tests` nie gorsze, koszt na zadanie w granicach 20% | Scal zmianę reguł i wklej tabelę z wynikami obu ramion do pull requesta |
| Proposed wygrywa na części zadań, a na innych przegrywa | Przeczytaj zadania, w których ramiona różnią się we wszystkich trzech powtórzeniach; to jest sygnał, pojedyncze przeskoki to szum. Popraw regułę, która spowodowała przegraną, i uruchom ponownie |
| Równy odsetek zaliczeń, proposed tańszy lub szybszy | Scal: krótszy plik, który zachowuje zachowanie agenta, oszczędza tokeny w każdej sesji |
| Proposed gorszy na `tests_pass` w którymkolwiek zadaniu we wszystkich trzech powtórzeniach | Nie scalaj. Znajdź regułę, którą miał stary plik, a nowy zgubił |
| Różni się tylko ocena sędziego `conventions` | Traktuj to jako wskazówkę, a nie werdykt, dopóki sędzia nie zostanie skalibrowany na twoich etykietach ([kontrole oceniane przez model](/pl/workflows/test/model-graded-checks/)) |

Wiersz 4 ma pierwszeństwo przed wierszem 1: stała przegrana w którymkolwiek zadaniu blokuje scalenie, nawet gdy ogólny odsetek zaliczeń jest taki sam lub wyższy.

Kontrole deterministyczne mają pierwszeństwo przed sędzią. Sędzia, który lubi dłuższe końcowe wiadomości, nagrodzi rozwlekły plik reguł, i tak właśnie regresja trafia do `main` z lepszym wynikiem.

## Gdzie w pętli pasują platformy śledzenia

Stały zestaw zadań mówi, *czy* zmiana pomaga. Ślad mówi, *dlaczego* jedno zadanie się nie udało: który plik agent przeczytał jako pierwszy, którą regułę zacytował, w którym miejscu się poddał. Dodaj śledzenie, gdy ewaluacja pokazuje przegraną, której nie da się wyjaśnić z końcowej wiadomości.

**Langfuse**

    Oficjalny plugin śledzi prompty, tury, generacje modelu z użyciem tokenów i kosztem, wywołania narzędzi, skille i subagentów dla CLI `claude` i aplikacji desktopowej w trybie Code. Wymaga `uv` w `PATH`.

    ```bash
    claude plugin marketplace add langfuse/Claude-Observability-Plugin
    claude plugin install langfuse-observability@langfuse-observability
    ```

    Potem skonfiguruj klucze z wnętrza sesji poleceniem `/plugin configure langfuse-observability@langfuse-observability`; klucz tajny trafia do systemowego pęku kluczy, nie do pliku. Uruchom Claude Code ponownie. Jeśli ślad się nie pojawia, przeczytaj `~/.claude/state/langfuse_hook.log`. Na śledzonych sesjach Langfuse może potem uruchamiać zbiory danych i ewaluacje typu LLM-as-judge.

**Braintrust**

    CLI `bt` instaluje plugin i lokalnego demona śledzenia dla Claude Code, Codeksa, OpenCode, Pi, Groka i Antigravity. Każda sesja staje się jednym śladem ze spanami tur, wywołań modelu, narzędzi i subagentów.

    ```bash
    curl -fsSL https://bt.dev/cli/install.sh | bash   # Windows and mise installs: README of braintrustdata/bt
    bt login
    bt trace enable claude --project rules-ab
    bt trace doctor claude
    bt trace run --project rules-ab --additional-metadata '{"arm":"proposed"}' claude -- -p "Fix the invoice rounding bug in src/billing"
    ```

    Plugin nie redaguje lokalnie promptów, wejścia i wyjścia narzędzi ani promptów systemowych. Skonfiguruj redakcję w Braintrust, zanim włączysz śledzenie na prawdziwym repozytorium.

**Opik i Phoenix**

    **Opik** (Comet, Apache-2.0, możliwy self-hosting) łączy się z Claude Code, Codeksem, Cursorem i innymi przez MCP, więc możesz poprosić agenta o ocenę jego ostatnich śladów:

    ```bash
    pip install opik && opik configure
    uvx opik mcp configure
    ```

    **Arize Phoenix** daje lokalny interfejs śladów OpenTelemetry i ewaluacji bez konta: `pip install arize-phoenix && phoenix serve`. Podłączenia sesji samego Claude Code do Phoenixa nie dało się zweryfikować 2026-09-26; używaj go do śladów emitowanych przez twoją aplikację.

Koszt kontekstu: promptfoo, Inspect i `bt trace run` działają poza twoimi interaktywnymi sesjami i nic nie dodają do ich kontekstu. Pluginy Langfuse i Braintrust działają przez hooki; po instalacji uruchom `claude plugin details <plugin>`, żeby zobaczyć prognozowany koszt tokenów każdego dodanego komponentu. Serwer MCP Opika dodaje definicje narzędzi do każdej sesji, która go wczytuje, więc zmierz go przez `/context` przed i po.

Do funkcji LLM we własnej aplikacji, a nie do agenta kodującego, służą inne narzędzia: **DeepEval** (`deepeval test run test_chatbot.py`) blokuje funkcję w CI asercjami w stylu pytest, **garak** (`pip install garak`) sonduje endpoint modelu pod kątem jailbreaków, prompt injection i wycieków, a **OpenLLMetry** (`pip install traceloop-sdk`, potem `Traceloop.init()`) instrumentuje aplikację przez OpenTelemetry. Żadne z tych trzech nie śledzi agenta kodującego. Starsze repozytorium `openai/evals` odsyła teraz do ewaluacji w panelu OpenAI; jego pakiet PyPI `evals` ostatnio wydano w maju 2024.

## Prompty do skopiowania dla ewaluacji agentów

**Prompt do skopiowania: stały zestaw zadań ze scalonych pull requestów**

```text
Read the last 60 merged pull requests in this repository with `gh pr list --state merged --limit 60 --json number,title,files,body`.

Pick 15 that (1) changed code and tests together, (2) touched at most 6 files, and (3) cover a mix: at least 5 bug fixes, 4 small features, 3 refactors and 3 test-only tasks. Skip anything that touched migrations, CI config or dependencies.

For each, write one line of JSON with: id (pr-<number>), the task prompt a developer would have typed before the work existed (no hints from the final diff), the directories the change may touch as allowedPrefixes, and the test command that proves it. Write them to evals/tasks.jsonl. Do not modify any other file.
```

**Prompt do skopiowania: zmiana reguł jako eksperyment A/B**

```text
Compare CLAUDE.md on main with the version in this branch. List every rule that was added, removed or reworded, and for each one name the behaviour it should change.

For each behaviour, propose one deterministic check that a script can run in the working directory after the agent finishes (a test command, a git diff condition, a grep over changed files) and say which tasks in evals/tasks.jsonl would exercise it. If no task exercises a rule, draft one new task for it.

Output a table (rule, expected behaviour, check, tasks) and the JavaScript for any new check in the style of rules-ab/checks.js. Do not run the eval.
```

**Prompt do skopiowania: odczytaj wyniki promptfoo i zarekomenduj decyzję**

```text
Read rules-ab/results.json from a promptfoo run with two providers labelled "current" and "proposed", three repeats per task.

Report per arm: pass rate for each named metric (tests_pass, ran_tests, conventions, and in_scope where present), mean cost and mean latency per task. Then list every task where the arms disagree on tests_pass in all three repeats, and separately the tasks that flip between repeats.

Apply this rule: merge only if proposed is no worse on tests_pass, in_scope and ran_tests, and its mean cost is within 20% of current. State the decision, the evidence for it, and for each consistent loss quote the part of the proposed CLAUDE.md most likely responsible. Do not treat a conventions-only difference as decisive.
```

## Skąd wiadomo, że sama ewaluacja działa?

Ewaluacja, która nie może oblać, to tautologia z pozycją kosztową. Zanim zaufasz wynikowi, udowodnij, że harness wykrywa różnicę:

- **Reguła-kanarek.** Dodaj nieszkodliwą regułę tylko do jednego ramienia („zakończ końcową wiadomość słowem CANARY-B”) i uruchom jedno zadanie. Jeśli znacznik się nie pojawi, plik reguł się nie wczytuje.
- **Wariant celowo zły.** Uruchom raz z proponowanym plikiem, który każe agentowi nie uruchamiać testów. `ran_tests`, a zwykle także `tests_pass`, muszą spaść. Jeśli nie spadają, kontrole są za słabe; zobacz [siłę wyroczni](/pl/workflows/test/oracle-strength/).
- **Sędzia od innego dostawcy.** Ramię agenta nigdy nie ocenia samo siebie: konfiguracja powyżej wysyła `llm-rubric` do modelu innego dostawcy. Skalibruj go na 20 ręcznie oznaczonych wynikach, zanim pozwolisz mu blokować scalenie.
- **Powtarzaj przy każdej zmianie modelu.** Plik reguł dostrojony do jednego modelu może pogorszyć wyniki na następnym. [Plan oceny nowego modelu](/pl/ecosystem/models/new-model-playbook/) zaczyna się właśnie od ponownego uruchomienia tego zestawu zadań.

Odpowiedzialność: programista, który proponuje zmianę reguł, uruchamia test A/B i dołącza tabelę wyników obu ramion do pull requesta jako część [pakietu dowodów](/pl/workflows/ship/evidence-bundle/). Tech lead jest właścicielem zestawu zadań, przegląda tabelę zamiast prozy nowego pliku i zatwierdza scalenie.

## Co się psuje przy ewaluacji reguł agenta?

| Objaw | Przyczyna | Naprawa |
| --- | --- | --- |
| Oba ramiona mają identyczne wyniki w każdym zadaniu | Brak `setting_sources`, więc żadne ramię nie czyta `CLAUDE.md` | Dodaj `setting_sources: ['project']`; potwierdź regułą-kanarkiem |
| Ramię proposed nadal stosuje regułę, którą usunąłeś | Worktree wewnątrz repozytorium: Claude Code wczytuje też `CLAUDE.md` z katalogu nadrzędnego | Umieść oba worktree poza repozytorium, jak w kroku 2 |
| Prywatne preferencje zmieniają wyniki na jednym laptopie | `user` w `setting_sources` wczytuje `~/.claude/CLAUDE.md` | Używaj tylko `['project']` |
| Drugi przebieg kończy się w kilka sekund z tymi samymi wynikami | promptfoo podało odpowiedzi z cache | Przy ewaluacji agentów zawsze dodawaj `--no-cache` |
| Testy przechodzą w jednym ramieniu dzięki edycjom z drugiego | Równoległe przebiegi albo brak resetu między testami | `-j 1` i hook `reset.js` |
| Wyniki tego samego zadania skaczą między przebiegami | Jedno uruchomienie na zadanie albo mniej niż 10 zadań | `--repeat 3` i więcej zadań; decyduj tylko na podstawie powtarzalnych różnic |
| Ramię Codeksa ignoruje `AGENTS.md` | Ścieżka worktree niezaufana (Codex 0.150.0 i nowsze) | Oznacz obie ścieżki ewaluacji jako zaufane; potwierdź regułą-kanarkiem |
| Jedno zadanie przepala budżet | Pętla nieudanych wywołań narzędzi | `max_turns` i `max_budget_usd` na providera; `--max-cost-usd` dla `claude plugin eval` |
| Wyniki różnią się między poniedziałkiem a piątkiem | Zmienił się model domyślny | Przypnij `model` w obu ramionach i uruchamiaj oba ramiona razem |
| Ślady pokazują klucze API i zawartość plików w interfejsie dostawcy | Braintrust i Langfuse zapisują prompty i wyjście narzędzi | Najpierw skonfiguruj redakcję; śledź oczyszczone repozytorium testowe |

**Pułapki w narzędziach do ewaluacji agentów**

- Identyfikatory providerów promptfoo to `anthropic:claude-agent-sdk` (alias `anthropic:claude-code`) i `openai:codex-sdk` (alias `openai:codex`). `anthropic:claude-code-sdk` jest błędny, a „Claude Code SDK” to stara nazwa Claude Agent SDK.
- `pip install openai-evals` nie jest pakietem; starszy pakiet nazywa się `evals`, a OpenAI odsyła teraz do ewaluacji w swoim panelu.
- README Inspect SWE instaluje wersję deweloperską z gita; `pip install inspect-swe` pobiera wydanie z PyPI.
- Pluginy Langfuse, Braintrust i Opik dla agentów kodujących są młode (24, 2 i 23 gwiazdki na 2026-09-26), choć same platformy są popularne. Przypinaj ich wersje i sprawdzaj je po każdej aktualizacji Claude Code.
- garak skanuje endpointy modeli, a nie konfigurację agenta czy skille. Do tego służy Snyk Agent Scan ze strony [bramki bezpieczeństwa dla agentów](/pl/ecosystem/observability/agent-security-gates/).
- Nie zaczynaj nowego projektu na Helicone: od marca 2026 jest w trybie utrzymania (źródła wtórne: wpisy Helicone i Mintlify o przejęciu).

## Co dalej z ewaluacją agentów

Żeby uruchamiać ten zestaw zadań przy każdej zmianie harnessu, a nie raz na PR, zobacz [ciągłe ewaluacje](/pl/developer-scorecard-guide/continuous-evals/).

- [Ciągłe ewaluacje](/pl/developer-scorecard-guide/continuous-evals/) — Testy regresji harnessu agenta przy każdej zmianie, nie raz na PR.
- [Jak czytać benchmarki i budować własne ewaluacje](/pl/ecosystem/models/benchmarks/) — Publiczne benchmarki, Harbor i 30-zadaniowy zestaw, który wybiera model.
- [Kontrole oceniane przez model](/pl/workflows/test/model-graded-checks/) — Skalibruj sędziego z rubryką, zanim pozwolisz mu blokować scalenie.
- [Nowy model na rynku](/pl/ecosystem/models/new-model-playbook/) — Najpierw ten zestaw zadań, potem strojenie wysiłku i reguł.
- [Telemetria i analityka](/pl/ecosystem/observability/agent-telemetry/) — OpenTelemetry dla Claude Code i Codeksa, połączone z pull requestami.

Zanim zmienisz plik reguł, przeczytaj, [jak pisać i odchudzać `CLAUDE.md`](/pl/claude-code/build/memory-system/); ta strona powie ci, czy odchudzona wersja nadal działa. Produkcyjną stronę tych samych danych opisuje [obserwowalność agentów](/pl/workflows/operate/agent-observability/). Hub sekcji, [mierzenie inżynierii agentowej](/pl/ecosystem/observability/), zestawia ewaluacje z telemetrią, śledzeniem kosztów, botami do review i bramkami bezpieczeństwa.
