Nouveau

claude plugin eval : mesurer enfin ce que votre plugin apporte

Depuis la v2.1.269 (septembre 2026), Claude Code sait tester un plugin sur une suite de cas et le comparer à une session sans plugin. Tutoriel pas à pas, coûts et pièges.

  • Tutoriel
  • Outils
Publié le

En bref

Vous avez écrit un plugin Claude Code avec une ou deux skills. Il a l'air de marcher. Mais est-ce qu'il marche mieux que Claude tout seul ? Jusqu'ici, la seule réponse possible était « j'ai l'impression que oui ».

La commande claude plugin eval, arrivée dans la v2.1.269 pendant la semaine du 7 au 11 septembre 2026, change ça. Elle fait tourner votre plugin sur une suite de cas de test, note les résultats et, par défaut, refait chaque cas sans le plugin pour montrer ce qu'il apporte vraiment.

L'analogie la plus proche, c'est l'essai clinique avec groupe témoin. On ne se contente pas de mesurer que les patients vont mieux, on compare avec ceux qui n'ont pas pris le traitement.

Le principe en trois notions

Un cas : un prompt réaliste, comme un utilisateur de votre plugin le taperait, plus un ou plusieurs correcteurs (« graders »).

Un grader : une vérification réussie ou ratée sur ce que Claude a produit. Par exemple une regex sur la réponse, le fait qu'un outil précis a été appelé, ou une grille d'évaluation qu'un second modèle applique à la réponse.

La baseline sans plugin : chaque cas tourne avec le plugin (colonne WITH) et sans (colonne W/OUT). La différence, Δ, c'est ce que votre plugin apporte. Si un cas obtient 1.0 dans les deux colonnes, ce n'est pas votre plugin qui le fait réussir.

Chaque cas tourne trois fois par défaut, parce qu'un seul essai d'un agent non déterministe ne dit pas grand-chose. Le score d'un cas est la moyenne de ses runs.

Prérequis

  • Claude Code v2.1.269 ou plus récent (claude --version, puis claude update si besoin).
  • Git 2.31 ou plus récent, si git est installé.
  • Un dossier de plugin avec un manifeste plugin.json ou .claude-plugin/plugin.json.

Votre première suite, pas à pas

1

Faire rédiger les cas par Claude

Depuis la racine de votre plugin, lancez claude plugin eval init. Une session interactive s'ouvre. Claude lit votre plugin, vous demande à quoi ressemble un bon résultat, propose des prompts qui devraient déclencher le plugin et d'autres qui ne devraient pas, conçoit les graders, les essaie une fois et écrit un dossier par cas sous evals/. Quittez la session avec /exit quand Claude annonce que la suite est prête.

2

Lancer la suite

Toujours à la racine du plugin, lancez claude plugin eval . pour exécuter tous les cas.

3

Lire le tableau

Un tableau récapitulatif s'affiche avec les colonnes WITH, W/OUT, Δ, le nombre de runs et le coût estimé. Un rapport HTML détaillé est écrit sous evals/results/.

4

Itérer

Ajustez votre plugin, relancez, comparez.

# Depuis la racine du plugin
claude plugin eval init
claude plugin eval .

Exemple de sortie tiré de la documentation :

CASE        WITH  W/OUT Δ      RUNS COST    NOTES
first-case  1.00  0.33  +0.67  6    $0.41


1 case(s) · mean Δ +0.67 · 74s · $0.41

Ici, le plugin fait passer le cas de 0,33 à 1,00 : il apporte clairement quelque chose.

Le diagnostic le plus fréquent

La documentation le dit elle-même : le premier constat le plus courant est un Δ proche de zéro, avec le grader qui vérifie l'appel de la skill en échec. Traduction : Claude ne choisit pas votre skill quand l'utilisateur formule sa demande naturellement.

La correction passe presque toujours par le champ description de la skill. C'est ce texte que Claude lit pour décider s'il l'utilise. Notre guide des skills détaille comment l'écrire.

Pour itérer vite et pour pas cher sur un seul cas, lancez un seul run sans baseline, puis confirmez avec les trois runs par défaut avant de conclure :

claude plugin eval . --case <nom-du-cas> --runs 1 --ablation none

Choisir de bons graders

Il existe six types de graders. Quatre sont calculés à partir de la transcription et des fichiers, et ne coûtent rien : regex, tool_used, tool_order et file_exists. Les deux autres, llm et baseline, font appel à un modèle juge et ajoutent au coût. Il n'existe pas de grader en code personnalisé.

Les conseils de la documentation pour obtenir des scores stables :

  • Pour une sortie longue, comme un fichier généré, préférez une regex sur le fichier. Réservez les graders llm aux sorties courtes, avec des conditions PASS et FAIL concrètes.
  • Donnez à chaque cas un grader sur le résultat et un grader sur le chemin suivi (tool_used ou tool_order). L'un dit si la réponse est juste, l'autre si c'est votre plugin qui l'a produite.
  • Si le grader de skill passe mais que le Δ est négatif, soupçonnez d'abord le juge. Relancez avec --judge-model sonnet pour un juge plus solide.

Un exemple de grader qui vérifie que votre skill a bien été appelée :

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'
---

Sécurité : ce qu'un run peut faire

Les runs ne s'arrêtent jamais pour demander une permission. Par défaut, seuls les outils en lecture listés dans le cas sont autorisés. Bash, Write, Edit, WebFetch et WebSearch sont retirés, sauf si vous les accordez avec --allow-tools.

Si vous accordez Bash, chaque commande tourne dans le sandbox système de Claude Code : écritures confinées au dossier du run, dossier personnel illisible, réseau limité aux domaines accordés. Sous Windows natif, il n'y a pas de sandbox, donc les suites qui accordent un shell doivent tourner sous WSL2.

Les serveurs MCP réels de votre plugin ne démarrent pas pendant un run, sauf si vous le demandez. Vous pouvez les remplacer par des mocks en Markdown sous evals/mocks/.

En CI

claude plugin eval peut servir de garde-fou dans un pipeline. La documentation conseille notamment de fixer le modèle testé avec --model, pour qu'un changement de modèle par défaut ne soit pas pris pour une régression de votre plugin. Pensez aussi à ajouter evals/results/ à votre .gitignore.

Prochaines étapes