Ewaluacja wtyczek i umiejętności w Claude Code: inżynieryjny rygor zamiast testowania na wyczucie

Tworzenie rozszerzeń dla autonomicznych asystentów programistycznych wkracza w fazę dojrzałości inżynieryjnej. Wraz z wydaniem wersji v2.1.269 ekosystemu Claude Code pojawił się wbudowany mechanizm, dzięki któremu formalna ewaluacja wtyczek oraz dodatkowych umiejętności (skills) zastępuje dotychczasowe, chaotyczne testowanie oparte na subiektywnych odczuciach twórcy („vibes-based development”). Do dyspozycji programistów oddano dedykowane polecenie claude plugin eval, które pozwala zmierzyć rzeczywisty wpływ kodu rozszerzenia na zachowanie agenta, weryfikując, czy dostarczone instrukcje faktycznie pomagają modelowi w rozwiązywaniu zadań, czy jedynie wprowadzają zbędny szum w oknie kontekstowym.

Nowe narzędzie rozwiązuje jeden z najbardziej dokuczliwych problemów w pracy z agentami LLM: zjawisko cichych regresji. Drobna modyfikacja opisu umiejętności, zaktualizowanie definicji narzędzia w pliku manifestu lub podmiana modelu bazowego mogą sprawić, że asystent przestanie aktywować wtyczkę przy naturalnie sformułowanych zapytaniach. Aby temu zapobiec, claude plugin eval automatyzuje wielokrotne testy porównawcze i umożliwia zablokowanie procesu wdrażania zmian, jeśli jakość odpowiedzi spadnie poniżej ustalonego progu.

Architektura badania: podwójne ramię wykonawcze i mechanizm ablacji

Samo uzyskanie poprawnego wyniku w teście nie dowodzi jeszcze, że to wtyczka przesądziła o sukcesie – nowoczesne modele językowe często radzą sobie z problemem bez żadnych dodatkowych instrukcji. Z tego powodu silnik ewaluacyjny w Claude Code domyślnie przeprowadza badanie w dwóch niezależnych ramionach (ablation study):

1. Ramię z wtyczką (with-arm) – sesja uruchamiana z załadowanym badanym rozszerzeniem (wynik WITH).
2. Ramię bazowe (without-arm) – identyczne zapytanie skierowane do „czystego” modelu bez załadowanej wtyczki (wynik W/OUT).

Różnica między tymi wynikami tworzy kluczowy wskaźnik $\Delta$ (delta). Jeśli przypadek testowy kończy się wynikiem 1.0 w obu wariantach, $\Delta$ wynosi 0, co jednoznacznie wskazuje, że rozszerzenie nie wniosło żadnej wartości dodanej. Co więcej, aby zrównoważyć statystyczny niedeterminizm modeli generatywnych, każdy przypadek jest domyślnie powtarzany trzykrotnie (3 przebiegi w każdym ramieniu, czyli łącznie 6 uruchomień na przypadek).

Twórcy narzędzia zadbali także o to, by specyficzne testy nie fałszowały obrazu sytuacji. Grader weryfikujący samo wywołanie umiejętności (tool_used: Skill) nigdy nie zaliczy testu w ramieniu bez wtyczki. Zaliczenie go do ogólnej puli zepchnęłoby wynik bazowy do zera i sztucznie zawyżyło $\Delta$. Dlatego silnik automatycznie oznacza takie oceniacze jako scored: false – są one prezentowane w raporcie jako wskaźniki diagnostyczne dla ramienia z wtyczką, lecz nie wpływają na kalkulację punktacji porównawczej.

Struktura pakietu testowego: katalog evals/ i typy graderów

Zestaw testowy wtyczki mieści się domyślnie w katalogu evals/ wewnątrz repozytorium rozszerzenia (obok pliku manifestu plugin.json lub .claude-plugin/plugin.json). W razie potrzeby inną ścieżkę można wskazać flagą --eval-dir lub zapisać w manifeście pod kluczem "experimental": { "evals": "quality/evals" }. Każdy pojedynczy przypadek testowy stanowi odrębny podkatalog zawierający:

• prompt.md – plik z treścią zadania, jakie użytkownik mógłby wpisać w konsoli, uzupełniony o nagłówek frontmatter definiujący parametry wykonania, m.in. max_turns, timeout_seconds, allowed_tools czy zmienne środowiskowe env.
• graders/ – folder zawierający definicje oceniaczy weryfikujących rezultaty działania agenta.
• case.yaml – opcjonalny plik konfiguracyjny (wymagający schema_version: "1.1"), pozwalający przygotować środowisko robocze za pomocą skryptu powłoki (context.scaffold_script), wstrzyknąć wcześniejszy zapis rozmowy (context.history_file) lub wskazać katalogi pomocnicze (context.add_dirs).

Do oceny wyników Claude Code udostępnia sześć wyspecjalizowanych typów graderów. Podzielono je na dwie kategorie:

• Gradery deterministyczne (bezpłatne): analizują transkrypcję sesji lub wygenerowane pliki bez wykonywania dodatkowych zapytań do modeli LLM. Należą do nich regex (dopasowanie wzorca tekstowego), tool_used (sprawdzenie, czy określone narzędzie zostało wywołane z odpowiednimi parametrami), tool_order (weryfikacja chronologii użycia narzędzi) oraz file_exists (potwierdzenie obecności oczekiwanego pliku na dysku).
• Gradery modelowe (płatne): wykorzystują zewnętrzny model w roli sędziego. Grader typu llm ocenia odpowiedź na podstawie zdefiniowanej rubryki z jasnymi warunkami PASS i FAIL, natomiast baseline porównuje wyjście z odpowiedzią wzorcową. Aby uniknąć fluktuacji ocen, zaleca się stosowanie flagi --judge-model sonnet, która wymusza użycie bardziej zaawansowanego sędziego niż domyślny model pomocniczy.

Generowanie testów, koszty i izolacja środowiska

Rozpoczęcie pracy z pakietem ewaluacyjnym nie wymaga ręcznego pisania wszystkich plików konfiguracyjnych. Polecenie claude plugin eval init uruchamia interaktywną sesję, w której asystent analizuje strukturę wtyczki, pyta o pożądane rezultaty, proponuje realistyczne prompty oraz konstruuje gotowe gradery, weryfikując ich działanie w próbnym przebiegu. Dla zwolenników manualnej konfiguracji przewidziano przełącznik claude plugin eval init --bare <case-name>, tworzący czysty szablon.

Każde uruchomienie testowe odbywa się w odizolowanym, nieinteraktywnym procesie roboczym, a narzędzia mogą operować wyłącznie w granicach uprawnień zadeklarowanych w polu allowed_tools. Podobnie jak w przypadku reguł bezpieczeństwa w Auto mode, środowisko ewaluacji wymusza ścisłą kontrolę uprawnień narzędziowych, eliminując ryzyko niekontrolowanych działań podczas zautomatyzowanych przebiegów.

Należy pamiętać, że każdy przebieg agenta oraz każde wywołanie sędziego LLM stanowi rzeczywiste zapytanie API, rozliczane według cennika dostawcy. W środowiskach korporacyjnych uwierzytelnianie odbywa się przy użyciu tych samych poświadczeń co standardowe sesje, uwzględniając konfiguracje Amazon Bedrock, Google Cloud’s Agent Platform czy Microsoft Foundry. Podczas szybkiego prototypowania i dopracowywania samych kryteriów oceny warto zredukować koszty, korzystając z flag --ablation none oraz --runs 1. W połączeniu ze stosowaniem ogólnych zasad efektywności w sesjach Claude Code pozwala to zachować pełną kontrolę nad budżetem tokenów podczas intensywnych prac rozwojowych.

Integracja w potokach CI/CD i analiza raportów

Po zakończeniu procedury testowej claude plugin eval . wyświetla w konsoli zwięzłe zestawienie tabelaryczne zawierające kolumny: CASE, WITH, W/OUT, Δ, RUNS, COST oraz NOTES. Przykładowy pojedynczy test first-case w dokumentacji osiąga wynik WITH: 1.00, W/OUT: 0.33 oraz Δ: +0.67 przy 6 przebiegach, łącznym czasie trwania 74 sekund i szacowanym koszcie rzędu $0.41.

Szczegółowe dane trafiają do pliku evals/results/<timestamp>/report.html oraz na platformę claude.ai (o ile nie użyto flagi --no-publish). Jak widać na grafice przedstawiającej raport wdrożeniowy wtyczki commit-helper v1.2.0, wskaźnik skuteczności z wtyczką (SUITE SCORE WITH PLUGIN) osiągnął 94.4%, podczas gdy wynik bazowy (BASELINE SCORE) wyniósł 61.1%. Przełożyło się to na bezpośredni przyrost wskaźnika ABLATION Δ na poziomie +33.3 przy 3 zdefiniowanych przypadkach testowych (CASES) i 88.9% całkowicie bezbłędnych przebiegów (PERFECT RUNS).

Dzięki obsłudze parametru --threshold (domyślnie wynoszącego 1.0) oraz możliwości generowania wyników maszynowych flagą --json <ścieżka>.json, narzędzie idealnie sprawdza się jako bramka weryfikacyjna (build gate) w potokach ciągłej integracji. Warto przy tym pamiętać o rozróżnieniu ról: komenda claude plugin validate odpowiada wyłącznie za statyczną poprawność manifestów i schematów, natomiast claude plugin eval dostarcza twardych, powtarzalnych dowodów na to, że tworzona wtyczka rzeczywiście podnosi inteligencję całego systemu.