Claude Code evals: misurare davvero l’effetto di un plugin

Il momento è quello giusto. Claude Code 2.1.269 ha introdotto gli eval per i plugin l’11 settembre 2026. Il principale tutorial datato che compare per questa ricerca descrive ancora un runner Python personalizzato. Per chi oggi mantiene un plugin locale, il percorso più breve è ormai quello nativo: inizializzare un singolo caso comportamentale, eseguirlo contro un controllo, leggere il report e infine fare in modo che la CI respinga proprio la regressione provocata intenzionalmente.

Che cosa misurano davvero i Claude Code evals

L’eval di un plugin è un test A/B applicato al comportamento di un agente. Immagina due officine identiche che ricevono la stessa scheda di lavoro: nella prima il plugin è installato, nella seconda no. Claude Code ripete il compito in entrambe, valuta il risultato e riporta WITH, W/OUT e Δ, cioè il punteggio con il plugin meno quello senza plugin.

È il delta il dato che conta. Ottenere 1.0 in entrambi i bracci può sembrare un risultato eccellente, ma significa che Claude era già in grado di completare il compito senza il plugin. Un delta positivo quantifica il contributo del plugin; uno negativo indica invece che il comportamento testato è peggiorato.

Per impostazione predefinita, un caso genera tre sessioni nuove con il plugin e tre senza. Ogni sessione dispone di una home, una directory di lavoro e una configurazione di Claude Code isolate. Le impostazioni personali, il CLAUDE.md del progetto, gli altri plugin, la memoria e i server MCP personali restano fuori. L’isolamento rende il confronto più pulito, ma fa anche emergere — giustamente — i plugin che dipendono di nascosto dalla configurazione del laptop. La documentazione Anthropic sugli eval dei plugin descrive per intero il modello di isolamento e sicurezza.

Parti da un plugin locale funzionante

Gli eval comportamentali sono il secondo controllo, non il primo. La directory del plugin deve contenere plugin.json, .claude-plugin/plugin.json oppure una struttura valida di directory per le skill. claude plugin validate serve a trovare errori nei file e nello schema. claude plugin eval risponde invece a domande come: «La skill si è attivata davanti a una richiesta naturale? Ha prodotto il formato previsto dal team?».

Servono inoltre Claude Code v2.1.269 o successivo e la stessa autenticazione usata nelle normali sessioni. Le sessioni di eval, i grader basati su un modello giudice e l’inizializzatore interattivo consumano il plafond del piano o generano addebiti API. Se la configurazione generale di Claude Code è ancora agli inizi, conviene partire dal flusso locale di base prima di aggiungere un gate di rilascio.

Dalla root di un plugin attendibile, verifica la versione e crea un caso vuoto:

claude --version
claude plugin eval init --bare release-note

L’alternativa interattiva è claude plugin eval init. Il comando legge il plugin, chiede come dovrebbe presentarsi un buon risultato, propone casi e grader, li prova una volta e scrive la suite. Per capire il contratto è preferibile la variante --bare, perché crea i file senza eseguire nulla.

Crea un caso comportamentale facile da interpretare

Supponiamo che il plugin funzionante contenga una skill chiamata release-notes. Il suo valore non consiste semplicemente nello scrivere del testo: deve riconoscere una richiesta naturale relativa a una modifica di prodotto e restituire le note di rilascio nel formato in tre parti adottato dal team: Summary, Impact e Risk.

Inserisci in prompt.md una richiesta realistica dell’utente. Aggiungi poi un grader deterministico per il risultato e uno per il meccanismo. «Deterministico» significa che la CLI controlla direttamente la traccia o il testo, senza chiamare un modello giudice.

# evals/release-note/prompt.md
---
name: release-note
tags: [smoke]
runs: 3
max_turns: 8
timeout_seconds: 180
allowed_tools: [Skill]
---

Turn this change into a customer-facing release note: checkout now retries a failed payment once before showing an error.

# evals/release-note/graders/format.md
---
type: regex
target: last_message
pattern: 'Summary[\s\S]*Impact[\s\S]*Risk'
flags: i
---

# evals/release-note/graders/skill-fired.md
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?release-notes"'
---

Sostituisci release-notes con il valore effettivo di name nel file SKILL.md della skill. Il prompt evita di proposito sia il nome della skill sia l’indicazione delle tre intestazioni. In questo modo il test verifica se il plugin sa riconoscere il compito e applicare il proprio formato. Se il prompt contiene già tutte le risposte, anche il braccio senza plugin può superare la prova e il delta mostrerà che il contributo del plugin è scarso.

Il frontmatter riportato sopra segue lo schema nativo attuale. In prompt.md, campi come runs, max_turns, timeout_seconds, model, tags e allowed_tools restano al livello principale. Per aggiungere fixture, cronologia della conversazione o directory, usa case.yaml: questo file richiede schema_version: "1.1" e name e raccoglie i campi di esecuzione sotto execution:.

Esegui il test e interpreta il report

Dalla root del plugin, esegui claude plugin eval .. Con questo unico caso, il comando avvia tre sessioni con il plugin e tre sessioni di baseline. Durante l’esecuzione, le righe di avanzamento mostrano l’esito dei grader alla fine di ogni sessione. Il riepilogo presenta poi WITH, W/OUT, Δ, RUNS, COST e NOTES.

Leggili in questo ordine:

1. WITH indica se le sessioni dotate di plugin hanno soddisfatto i grader.
2. W/OUT mostra con quale frequenza Claude ha ottenuto lo stesso risultato da solo.
3. Δ misura il contributo del plugin. Un valore positivo è utile; uno vicino allo zero richiede un’indagine; uno negativo segnala una regressione.
4. COST è una stima basata sui prezzi di listino, non necessariamente l’importo addebitato con un abbonamento.
5. NOTES rimanda all’errore di esecuzione o al fallimento con peso maggiore nel braccio con plugin.

Ogni suite che contiene almeno un caso scrive aggregate-result.json e un report.html autonomo in una directory dei risultati contrassegnata da timestamp. Dal report HTML puoi aprire ogni esecuzione, leggere il verdetto e la spiegazione di ciascun grader e confrontare prompt e definizioni dei grader con ciò che Claude ha effettivamente fatto. Il JSON espone campi stabili per la CI, tra cui punteggio complessivo, casi superati, delta medio, stato parziale, costo stimato, durata e versione di Claude Code.

Provoca una regressione prima di fidarti del test

Ora dimostra che il test sa fallire. Sostituisci temporaneamente la descrizione della skill release-notes con una formula vaga che non nomini più il compito da riconoscere. Non modificare il caso di eval. Esegui di nuovo lo stesso comando, esamina il nuovo report e infine ripristina la descrizione corretta.

Il fallimento da cercare è comportamentale: il grader Skill smette di passare, il formato atteso diventa meno affidabile oppure si riduce il vantaggio del braccio con plugin. Non prevedere un punteggio esatto, perché le esecuzioni degli agenti variano. Se il difetto intenzionale lascia il report sostanzialmente invariato nelle tre esecuzioni predefinite, il caso non sta ancora proteggendo il plugin. Rendi la richiesta più rappresentativa, irrigidisci il grader del risultato oppure aggiungi un caso negativo nel quale la skill non deve attivarsi.

Questo difetto intenzionale equivale al pulsante di prova di un rilevatore di fumo. Una dashboard verde non vale nulla finché non hai verificato che un guasto pertinente possa farla diventare rossa.

Definisci il budget del ciclo prima di aggiungere casi

Già un solo caso predefinito crea sei sessioni dell’agente. Se aggiungi un unico grader LLM, lo stesso caso richiede anche diciotto voti del giudice: tre voti per ciascuna delle sei sessioni. Le sessioni, a loro volta, possono richiedere più turni. Ecco perché una suite piccola può consumare molto più di quanto lasci intuire il numero di casi.

Usa tre budget per tre decisioni diverse:

Il ciclo con una sola esecuzione è volutamente rumoroso. Usalo per intercettare gli errori evidenti, poi conferma con le tre esecuzioni predefinite prima di accettare una modifica. Per i controlli frequenti, privilegia regex, tool_used, tool_order e file_exists: non aggiungono chiamate al giudice. Riserva un grader LLM ai risultati brevi la cui qualità non può essere espressa con una regola stabile.

Il limite di costo richiede una precisazione. --max-cost-usd applica un tetto alla stima della CLI basata sui prezzi di listino prima dell’avvio di ogni esecuzione. Quelle già in corso vengono completate, perciò la stima riportata può superare il limite. Quando si raggiunge il tetto, restano risultati parziali e il processo termina con codice 2. È una barriera di sicurezza, non un portafoglio prepagato.

Affida alla CI il controllo delle regressioni

Quando la regressione intenzionale è visibile e il plugin ripristinato torna a passare, porta la stessa suite nel controllo versione. L’esempio CI di Anthropic fissa i modelli dell’agente e del giudice, scrive results.json, usa una soglia di 0.8, mantiene il report in locale e imposta un tetto di costo stimato pari a $20. Passa anche --trust-plugin, scelta appropriata soltanto quando il plugin e la suite presenti nel checkout sono codice che eseguiresti personalmente.

Il comando esatto per il passaggio è claude plugin eval . --trust-plugin --json results.json --threshold 0.8 --model claude-sonnet-5 --judge-model claude-haiku-4-5 --no-publish --max-cost-usd 20. Inseriscilo nel job dopo aver installato e autenticato Claude Code, quindi archivia entrambi i file dei risultati.

Lo stato di uscita del comando basta per bloccare una build. Il codice 0 significa che tutti i casi sono stati caricati e hanno raggiunto la soglia. Il codice 1 copre sia un punteggio inferiore alla soglia sia vari errori di configurazione. Il codice 2 indica un’esecuzione parziale dovuta al tetto di costo o a un rifiuto iniziale delle credenziali. Archivia results.json e report.html anche in caso di errore, così chi ha proposto la modifica potrà distinguere una regressione del plugin da un timeout o da uno stop imposto dal budget.

Fissare i modelli è importante: in caso contrario, il rollout di un modello può sembrare una regressione del plugin. Applica la stessa disciplina anche alla spesa di ragionamento: verifica qualità ed effort come dimensioni separate, così una variazione di costo non si nasconde dentro un punteggio comportamentale.

I primi sette comportamenti da testare in un plugin

I team che ottengono il massimo vantaggio sono quelli che distribuiscono plugin ad altre persone. Un assistente privato può tollerare una verifica manuale; in un plugin per un marketplace o un’organizzazione, invece, una descrizione debole, una concessione errata degli strumenti o una modifica dell’output si trasformano in richieste di supporto ripetute.

Comincia dai primi due comportamenti di cui gli utenti noterebbero subito la scomparsa. Dieci casi vaghi valgono meno di un test di attivazione e uno di risultato capaci di rendere riproducibile un difetto.

Due prodotti da costruire intorno agli eval nativi dei plugin

1. Un gate basato sul delta nelle pull request è l’opportunità più solida

Puoi creare un prodotto CI leggero che esegue il comando nativo, legge aggregate-result.json e pubblica una singola review con variazione del punteggio, delta, costo, grader fallito e link al report archiviato. I team che sviluppano plugin e chi li mantiene nei marketplace pagano per il livello decisionale, non per un altro valutatore.

La domanda è ancora iniziale, ma ha un chiaro valore commerciale. claude code evals registra circa 50 ricerche mensili negli Stati Uniti, in crescita del 600% anno su anno, con un CPC di $17.61. Le piattaforme di valutazione più ampie confermano inoltre l’esistenza di budget destinati alla qualità: Braintrust propone un piano Pro da $249 al mese. È un riferimento per la categoria, non un consiglio di prezzo per un wrapper del plugin.

La versione minima vendibile è una GitHub Action accompagnata da un commento nella pull request. Accetta il percorso del plugin, la soglia, i modelli fissati e il tetto di costo stimato; carica JSON e HTML nativi; distingue il codice di uscita 1 dallo stato parziale 2. Il rischio è legato alla piattaforma: Anthropic potrebbe aggiungere un sistema proprietario di reportistica per le pull request. Il livello difendibile non è una copia più elegante del report nativo, ma una policy condivisa tra repository, confronti storici e regole di approvazione.

2. Pacchetti di eval curati possono aiutare chi crea skill

Puoi vendere pacchetti di casi mantenuti per attività comuni dei plugin, come code review, scrittura di changelog, triage degli incidenti e selezione sicura degli strumenti. Un pacchetto è una normale directory evals/ con prompt positivi e negativi realistici e grader deterministici, che un team può adattare invece di definire da zero il proprio standard qualitativo.

La query diretta claude code skill evals totalizza circa 10 ricerche mensili negli Stati Uniti. Il volume è minimo: si tratta quindi di un componente aggiuntivo mirato, non di un mercato autonomo adatto a una startup finanziata da venture capital. L’MVP è un singolo pacchetto eccellente per una categoria di plugin di valore, versionato rispetto alle release di Claude Code e accompagnato da una breve guida alla calibrazione. Anche il limite è evidente: claude plugin eval init propone già i casi e li prova. Un pacchetto si distingue soltanto se gli scenari di dominio e i criteri di fallimento sono migliori di quelli prodotti da una generazione generica.

Che cosa non risolve questo comando

Gli eval nativi non dimostrano che un plugin sia valido in assoluto. Mostrano come si è comportato con i prompt, l’ambiente, il modello, le autorizzazioni agli strumenti e i grader scelti. Prompt deboli producono punteggi lusinghieri. Una regex può premiare l’intestazione corretta anche quando il contenuto è sbagliato. Un giudice LLM può variare e aggiunge tre voti per grader a ogni esecuzione.

Anche l’isolamento impone un vincolo reale. Ogni esecuzione parte da zero: file del progetto, impostazioni utente, hook e server personali non sono presenti. È un’ottima proprietà per la riproducibilità, ma penalizza i casi che dimenticano di dichiarare le fixture. Gli strumenti che non appartengono all’insieme in sola lettura richiedono un’autorizzazione esplicita da riga di comando. I veri server MCP del plugin richiedono opt-in e permessi aggiuntivi, mentre hook e server reali meritano un runner isolato perché possono operare fuori dalla sandbox dell’agente.

Infine, non ridurre max_turns o timeout_seconds finché il lavoro legittimo non urta contro il limite. Un’esecuzione che va in timeout o raggiunge il numero massimo di turni viene registrata come errore e in genere abbassa il punteggio. Lascia margine sufficiente per il compito previsto, poi usa il tetto di costo stimato per controllare l’intera suite.

Lunedì, chi mantiene il plugin dovrebbe aggiungere un caso di attivazione, farlo fallire di proposito, ripristinare il plugin e applicare a quello stesso controllo un tetto di spesa in CI. Se vuoi costruire questo sistema di rilascio per tutti i plugin del tuo team, posso aiutarti a progettare il gate di produzione.