Plugins Claude Code : mesurer leur impact avec les evals natives

Le moment est bien choisi. Claude Code 2.1.269 a ajouté les evals de plugins le 11 septembre 2026. Pourtant, le tutoriel daté qui domine encore cette requête repose sur un runner Python sur mesure. Pour maintenir aujourd’hui un plugin local, le chemin le plus court est donc natif : initialiser un cas comportemental, l’exécuter face à un groupe témoin, examiner le rapport, puis demander à la CI de refuser la régression que vous venez de provoquer volontairement.

Ce que mesurent vraiment les evals des plugins Claude Code

Une eval de plugin est un test A/B appliqué au comportement d’un agent. Imaginez deux ateliers identiques recevant la même fiche de travail : le premier dispose de votre plugin, le second non. Claude Code réalise la tâche dans les deux environnements, évalue le travail et présente WITH, W/OUT et Δ, soit le score avec plugin moins celui obtenu sans plugin.

C’est ce delta qui compte. Deux scores de 1.0 peuvent sembler parfaits, mais ils indiquent aussi que Claude savait déjà accomplir la tâche sans votre plugin. Un delta positif quantifie sa contribution ; un delta négatif révèle au contraire qu’il a dégradé le comportement testé.

Par défaut, un seul cas lance trois sessions neuves avec le plugin et trois autres sans. Chacune possède son propre dossier personnel, son répertoire de travail et sa configuration Claude Code. Vos réglages personnels, le fichier CLAUDE.md du projet, les autres plugins, la mémoire et vos serveurs MCP personnels ne sont pas importés. Cette isolation fiabilise la comparaison, mais elle fait aussi échouer — à juste titre — tout plugin qui dépend en secret de la configuration de votre ordinateur. La documentation d’Anthropic sur les evals de plugins détaille l’ensemble du contrat d’isolation et de sécurité.

Partir d’un plugin local qui fonctionne

Les evals comportementales viennent en second, après la validation. Le dossier du plugin doit contenir un plugin.json, un .claude-plugin/plugin.json ou une arborescence de skills valide. La commande claude plugin validate repère les problèmes de fichiers et de schéma ; claude plugin eval répond à des questions comme : « La skill s’est-elle déclenchée sur une demande naturelle et a-t-elle produit le format attendu par l’équipe ? »

Il faut également Claude Code v2.1.269 ou une version ultérieure, ainsi que la même authentification que pour vos sessions ordinaires. Les sessions d’eval, les graders fondés sur un modèle juge et l’assistant d’initialisation interactif consomment tous le quota de votre forfait ou sont facturés via l’API. Si votre environnement Claude Code est encore récent, commencez par le workflow local de base avant d’ajouter un garde-fou de mise en production.

Depuis la racine d’un plugin de confiance, vérifiez la version et créez un cas vide :

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

L’autre possibilité consiste à lancer claude plugin eval init en mode interactif. La commande analyse le plugin, vous demande à quoi ressemble un bon résultat, propose des cas et des graders, les teste une première fois, puis écrit la suite. Pour comprendre le contrat, l’option --bare est plus instructive : elle crée les fichiers sans rien exécuter.

Concevoir un cas comportemental facile à interpréter

Imaginons que le plugin fonctionnel contienne une skill appelée release-notes. Sa valeur ne réside pas seulement dans la rédaction d’un texte. Elle doit reconnaître une demande naturelle portant sur une évolution produit et restituer les notes de version selon les trois rubriques de l’équipe : Summary, Impact et Risk.

Placez la demande réaliste de l’utilisateur dans prompt.md. Ajoutez ensuite un grader déterministe pour le résultat et un autre pour le mécanisme. « Déterministe » signifie ici que la CLI contrôle directement la trace ou le texte, sans solliciter de modèle juge.

# 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"'
---

Remplacez release-notes par la valeur réelle du champ name dans le fichier SKILL.md de votre skill. Le prompt évite délibérément de nommer la skill ou d’imposer les trois intertitres. Le test vérifie ainsi si le plugin reconnaît la tâche et apporte son propre format. Si le prompt fournit déjà toutes les réponses, le groupe sans plugin peut réussir lui aussi, et le delta montrera que le plugin apporte peu.

Le frontmatter ci-dessus correspond au schéma natif actuel. Dans prompt.md, les champs tels que runs, max_turns, timeout_seconds, model, tags et allowed_tools restent au premier niveau. Pour ajouter des fixtures, un historique de conversation ou des répertoires, utilisez case.yaml : ce fichier exige schema_version: "1.1" et name, tandis que les champs d’exécution passent sous execution:.

Exécuter l’eval et comprendre le rapport

À la racine du plugin, lancez claude plugin eval .. Pour ce cas unique, la commande ouvre trois sessions avec plugin et trois sessions de référence. À mesure qu’elles se terminent, les lignes de progression affichent le verdict des graders. Le récapitulatif fournit ensuite WITH, W/OUT, Δ, RUNS, COST et NOTES.

Lisez ces indicateurs dans cet ordre :

1. WITH indique si les sessions équipées du plugin ont satisfait les graders.
2. W/OUT montre à quelle fréquence Claude a obtenu seul le même résultat.
3. Δ mesure l’apport du plugin. Une valeur positive est utile ; une valeur proche de zéro mérite une enquête ; une valeur négative signale une régression.
4. COST est une estimation calculée au tarif catalogue, pas nécessairement la somme facturée dans le cadre d’un abonnement.
5. NOTES renvoie vers l’échec au poids le plus élevé ou vers l’erreur d’exécution du groupe avec plugin.

Dès qu’une suite contient au moins un cas, elle écrit aggregate-result.json et un fichier autonome report.html dans un répertoire de résultats horodaté. Le rapport HTML permet d’ouvrir chaque exécution, de consulter le verdict et l’explication de chaque grader, puis de comparer les définitions du prompt et des graders au travail réellement effectué par Claude. Le JSON expose des champs stables pour la CI : score global, cas réussis, delta moyen, état partiel, estimation du coût, durée et version de Claude Code.

Provoquer une régression avant de faire confiance au test

Il faut maintenant prouver que le test sait échouer. Remplacez temporairement la description de la skill release-notes par une formulation vague, qui ne nomme plus la tâche qu’elle doit reconnaître. Ne touchez pas au cas d’eval. Relancez exactement la même commande, examinez le nouveau rapport, puis rétablissez la description correcte.

L’échec recherché porte sur le comportement : le grader Skill cesse de réussir, le format attendu devient moins fiable ou l’avantage du groupe avec plugin se réduit. Inutile de prédire un score précis, car les exécutions d’agents varient. Si cette panne volontaire ne change pratiquement rien au rapport sur les trois exécutions par défaut, votre cas ne protège pas encore le plugin. Rendez la demande plus représentative, durcissez le grader de résultat ou ajoutez un cas négatif dans lequel la skill ne doit pas se déclencher.

Cette panne volontaire joue le rôle du bouton de test d’un détecteur de fumée. Un tableau de bord vert ne vaut rien tant qu’on n’a pas vérifié qu’un défaut pertinent peut le faire passer au rouge.

Fixer le budget avant de multiplier les cas

Un cas par défaut génère déjà six sessions d’agent. Ajoutez un seul grader LLM, et ce même cas entraîne dix-huit votes du modèle juge : trois votes pour chacune des six sessions. Comme les sessions elles-mêmes peuvent s’étendre sur plusieurs tours, une petite suite peut consommer bien davantage que ne le laisse penser son nombre de cas.

Prévoyez trois budgets correspondant à trois décisions distinctes :

La boucle à une seule exécution est volontairement bruitée. Elle sert à détecter les erreurs évidentes ; validez ensuite le changement avec les trois exécutions par défaut. Pour les contrôles fréquents, privilégiez regex, tool_used, tool_order et file_exists, qui n’ajoutent aucun appel au modèle juge. Réservez un grader LLM aux résultats courts dont la qualité ne peut pas se résumer à une règle stable.

L’option de coût mérite une précision. --max-cost-usd plafonne l’estimation au tarif catalogue de la CLI avant le démarrage de chaque exécution. Celles qui sont déjà en cours vont jusqu’au bout ; l’estimation finale peut donc dépasser le plafond. Lorsque celui-ci est atteint, la commande conserve des résultats partiels et renvoie le code 2. C’est un garde-fou, pas un portefeuille prépayé.

Confier le contrôle de régression à la CI

Une fois la régression volontaire visible et le plugin restauré de nouveau au vert, placez exactement la même suite sous gestion de versions. L’exemple CI d’Anthropic épingle les modèles d’agent et de juge, écrit results.json, applique un seuil de 0.8, conserve le rapport en local et fixe à $20 le plafond du coût estimé. Il ajoute aussi --trust-plugin, une option à réserver au cas où le plugin et la suite extraits du dépôt sont du code que vous exécuteriez vous-même.

La commande à transmettre telle quelle est 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. Placez-la dans le job après l’installation et l’authentification de Claude Code, puis archivez les deux fichiers de résultats.

Le code de sortie suffit pour bloquer un build. Le code 0 indique que tous les cas ont été chargés et ont atteint le seuil. Le code 1 couvre un score inférieur au seuil ainsi que plusieurs erreurs de configuration. Le code 2 correspond à une exécution partielle provoquée par le plafond de coût ou par un rejet initial des identifiants. Même en cas d’échec, archivez results.json et report.html : l’auteur pourra distinguer une régression du plugin, un délai dépassé ou un arrêt imposé par le budget.

Épingler les modèles est essentiel, faute de quoi le déploiement d’une nouvelle version peut ressembler à une régression du plugin. Appliquez la même discipline au budget de raisonnement : testez séparément la qualité et le niveau d’effort, afin qu’une variation de coût ne se dissimule pas dans le score comportemental.

Sept comportements de plugin à tester en priorité

Les équipes qui ont le plus à gagner sont celles qui distribuent leurs plugins. Un assistant privé peut se contenter d’un contrôle manuel. Pour un plugin de marketplace ou d’entreprise, en revanche, une description imprécise, une autorisation d’outil mal réglée ou un changement de sortie se transforme en demandes d’assistance répétées.

Commencez par les deux premiers comportements dont vos utilisateurs remarqueraient immédiatement la disparition. Dix cas vagues sont moins utiles qu’un test de déclenchement et un test de résultat capables d’exposer un défaut reproductible.

Deux produits à bâtir autour des evals natives de plugins

1. Un garde-fou de delta sur les pull requests est l’occasion la plus solide

Construisez un produit CI léger qui exécute la commande native, lit aggregate-result.json et publie une seule revue indiquant l’évolution du score, le delta, le coût, le grader en échec et les liens vers le rapport archivé. Les équipes de plugins et les responsables de marketplaces paient pour cette couche de décision, pas pour un évaluateur supplémentaire.

La demande est encore naissante, mais son potentiel commercial est net. claude code evals représente environ 50 recherches mensuelles aux États-Unis, en hausse de 600% sur un an, avec un CPC de $17.61. Les plateformes d’évaluation généralistes confirment aussi l’existence de budgets qualité : Braintrust affiche une offre Pro à $249 par mois. Il s’agit d’un repère pour la catégorie, pas d’un conseil tarifaire pour un wrapper de plugin.

La plus petite version commercialisable est une GitHub Action assortie d’un commentaire sur la pull request. Elle accepte un chemin de plugin, un seuil, les modèles épinglés et un plafond de coût estimé ; elle téléverse les fichiers JSON et HTML natifs ; elle distingue le code de sortie 1 du code partiel 2. Le risque vient de la plateforme elle-même : Anthropic peut ajouter nativement les rapports de pull request. La couche défendable repose donc sur les règles communes à plusieurs dépôts, les comparaisons historiques et les circuits d’approbation, non sur une copie plus jolie du rapport natif.

2. Des packs d’evals sélectionnés peuvent servir les auteurs de skills

Commercialisez des packs de cas maintenus pour les usages courants des plugins : revue de code, rédaction de changelogs, triage d’incidents ou sélection sûre des outils. Un pack n’est qu’un répertoire evals/ ordinaire, composé de prompts positifs et négatifs réalistes ainsi que de graders déterministes. Une équipe peut ainsi l’adapter au lieu d’inventer de zéro son propre niveau de qualité.

La requête exacte claude code skill evals génère environ 10 recherches mensuelles aux États-Unis. Ce volume minuscule en fait un complément ciblé, pas un marché autonome taillé pour le capital-risque. Le MVP consiste en un excellent pack pour une seule catégorie de plugin à forte valeur, versionné au rythme des versions de Claude Code et accompagné d’un bref guide de calibration. La limite est tout aussi évidente : claude plugin eval init propose et teste déjà des cas. Les packs ne l’emporteront que si leurs scénarios métier et leurs critères d’échec surpassent une génération générique.

Ce que cette commande ne résout pas

Les evals natives ne prouvent pas qu’un plugin est bon en toutes circonstances. Elles montrent son comportement pour les prompts, l’environnement, le modèle, les autorisations d’outils et les graders que vous avez choisis. Des prompts trop faibles produisent des scores flatteurs. Une expression régulière peut récompenser le bon intertitre malgré un contenu erroné. Un juge LLM peut varier et ajoute trois votes par grader et par exécution.

L’isolation impose une autre contrainte saine. Chaque exécution repart de zéro : fichiers du projet, réglages utilisateur, hooks et serveurs personnels sont absents. C’est excellent pour la reproductibilité, moins pour un cas qui a oublié de déclarer ses fixtures. Les outils autres que ceux en lecture seule exigent une autorisation explicite en ligne de commande. Les vrais serveurs MCP d’un plugin réclament une activation et des autorisations supplémentaires ; quant aux hooks et aux serveurs réels, mieux vaut les confiner dans un runner isolé, car ils peuvent agir hors de la sandbox de l’agent.

Enfin, ne réduisez pas max_turns ou timeout_seconds au point qu’une tâche légitime atteigne la limite. Une exécution qui dépasse le délai ou le nombre de tours autorisé est enregistrée comme une erreur et fait généralement baisser le score. Laissez assez de marge pour le travail attendu, puis servez-vous du plafond de coût estimé pour maîtriser la suite dans son ensemble.

Lundi, un responsable de plugin devrait ajouter un cas de déclenchement, le faire échouer volontairement, restaurer le plugin, puis plafonner exactement ce contrôle dans la CI. Si vous souhaitez déployer ce système de mise en production sur tous les plugins de votre équipe, je peux vous aider à concevoir le garde-fou destiné à la production.