Claude Code Mods : guide débutant pour fiabiliser vos tests

Claude Code Mods transforme les contrôles répétitifs de Claude Code en règles exécutées automatiquement. Le projet présenté par Brief IA revendique 135 tests réussis et jusqu’à 100 fois moins de surcharge que les hooks traditionnels, avec quatre mods consacrés aux clés API, au suivi de projet, à la qualité des tests et à la gestion du contexte.

L’objectif de ce tutoriel est concret : installer les mods, vérifier leur fonctionnement, puis construire un contrôle qui empêche Claude Code de terminer une tâche tant que les tests ne passent pas. Les exemples utilisent les commandes documentées par Anthropic pour les mods et les hooks de Claude Code.

Étape 1 : Vérifier les prérequis de Claude Code

Claude Code est l’environnement dans lequel les mods s’exécutent. Les mods sont de petites fonctions TypeScript capables de modifier le comportement de Claude Code, tandis que les hooks traditionnels déclenchent des commandes à des moments précis du cycle de travail.

Avant de commencer, préparez :

• Un projet local contenant du code source et un système de tests.
• Claude Code installé et accessible depuis le terminal avec la commande claude.
• Un éditeur de texte ou un IDE capable de modifier des fichiers JSON et TypeScript.
• Un terminal macOS, Linux ou Windows compatible avec votre installation de Claude Code.
• Un compte et une formule Claude donnant accès à Claude Code selon les conditions commerciales applicables à votre environnement.

Ouvrez un terminal, placez-vous dans le dossier du projet, puis vérifiez que Claude Code répond :

bash cd mon-projet claude --version

Lancez ensuite Claude Code :

bash claude

Dans la session, saisissez :

text Explique la structure de ce projet sans modifier aucun fichier. Identifie la commande utilisée pour lancer les tests.

Cette première demande sert uniquement à vérifier que Claude Code peut lire le projet. Elle ne configure pas encore de mod.

Astuce : commencez dans un dépôt de test ou dans une branche dédiée. Un mod peut bloquer une commande, réécrire une action ou ajouter des informations au déroulement d’une session.

Attention : un mod qui inspecte des clés, des commandes ou des fichiers de configuration peut traiter des données sensibles. N’ajoutez jamais une clé API en clair dans un prompt, un fichier de test ou un dépôt partagé.

Étape 2 : Comprendre la différence entre mod et hook

Un mod est une extension TypeScript qui réagit aux événements de Claude Code et peut observer, réécrire ou refuser des actions. La documentation officielle indique qu’un mod peut gérer les événements liés aux outils, aux prompts et aux tours de conversation.

Un hook est une commande, une requête HTTP, un appel MCP, un prompt ou un sous-agent déclenché automatiquement à un événement du cycle de vie. Les hooks peuvent notamment s’exécuter avant l’utilisation d’un outil, après une modification de fichier, au démarrage d’une session ou lorsque Claude tente de s’arrêter.

Cette distinction est essentielle pour les tests. Un hook Stop peut imposer une vérification déterministe avant la fin d’une session. Un mod peut aller plus loin en analysant et en contrôlant plusieurs événements selon sa logique TypeScript.

À retenir : utilisez un mod lorsque le contrôle doit comprendre le comportement de Claude Code sur plusieurs événements. Utilisez un hook simple lorsqu’une commande déterministe suffit, par exemple npm test ou pytest.

Pour vérifier les extensions actives, ouvrez Claude Code puis utilisez :

text /plugin

La commande peut afficher les mods actifs dans l’interface de Claude Code. La documentation des mods précise qu’un mod externe chargé apparaît avec son nom dans la zone correspondante.

Étape 3 : Installer et valider un mod

Les mods sont distribués dans un répertoire de plugin contenant notamment un manifeste, un module de hooks et des fichiers de test. Une fois le dossier récupéré dans votre projet, validez-le depuis le terminal.

Placez-vous dans le dossier du mod :

bash cd chemin/vers/mon-mod claude plugin validate .

Pour obtenir un rapport exploitable automatiquement :

bash claude plugin validate . --json

Pour traiter les avertissements comme des erreurs :

bash claude plugin validate . --strict

La validation lit le manifeste et le module de hooks. Elle signale notamment les erreurs de structure, les événements pris en charge et les appels effectués vers l’API des mods.

Lancez ensuite les tests intégrés :

bash claude plugin test .

La commande exécute les fichiers dont le nom se termine par .test.ts ou .test.tsx. Un échec provoque un statut de sortie égal à 1, ce qui permet d’intégrer le contrôle dans une chaîne d’intégration continue.

Les tests d’un mod peuvent être lancés sans session Claude Code, sans authentification et sans réseau. Cette caractéristique permet de vérifier le comportement de l’extension dans un environnement local ou automatisé.

Exemple de séquence complète :

bash cd chemin/vers/mon-mod claude plugin validate . --strict claude plugin test .

Demandez ensuite à Claude Code d’expliquer le résultat sans corriger automatiquement :

text Analyse le résultat de la validation et des tests du mod. Ne modifie aucun fichier. Signale les erreurs par fichier et propose une correction minimale pour chacune.

Astuce : exécutez claude plugin validate . --json dans votre pipeline CI et archivez le rapport. Le format JSON simplifie l’exploitation par un outil de contrôle qualité.

Attention : ne sautez pas la validation après une modification du manifeste ou du module TypeScript. Un mod peut fonctionner dans un cas local tout en présentant une erreur de configuration sur un autre événement.

Étape 4 : Configurer les quatre mods du projet

Les quatre mods décrits par Brief IA ciblent quatre risques récurrents du développement assisté par IA : la sécurité des clés API, le suivi du projet, la qualité des tests et la gestion du contexte. Configurez-les progressivement plutôt que tous en même temps, afin d’identifier précisément le contrôle responsable d’un blocage.

Mod de sécurité des clés API

Ce mod doit empêcher l’exposition accidentelle de secrets dans les prompts, les fichiers suivis par Git ou les sorties de commandes. Commencez par demander à Claude Code d’inspecter la présence de fichiers sensibles sans afficher leur contenu :

text Recherche les fichiers susceptibles de contenir une clé API. Affiche uniquement leur chemin et le type de risque. Ne lis ni n’affiche aucune valeur secrète.

Ajoutez des fichiers d’exclusion adaptés à votre projet, par exemple .env, .env.local et les répertoires de secrets utilisés par votre infrastructure. Vérifiez ensuite le comportement avec une valeur fictive, jamais avec une véritable clé :

text Vérifie si le mod bloque l’ajout d’une chaîne qui ressemble à une clé API dans un fichier de test. Utilise uniquement la valeur fictive TEST_API_KEY_EXAMPLE.

Le test doit confirmer que le contrôle détecte le motif sans nécessiter une clé réellement utilisable.

Mod de suivi de projet

Le mod de suivi sert à conserver un état lisible de la tâche en cours : fichiers modifiés, tests exécutés et étapes restantes. Demandez à Claude Code de produire un état avant toute modification :

text Avant de modifier le projet, établis un état de suivi avec l’objectif, les fichiers concernés, la commande de test et le résultat attendu. N’écris aucun fichier pour le moment.

Après une modification, utilisez une demande qui force la mise à jour de cet état :

text Mets à jour le suivi du projet avec les fichiers modifiés, les tests exécutés, leur résultat et les prochaines actions. Ne marque pas la tâche comme terminée si un test échoue.

Le bénéfice recherché est la traçabilité. Une session ne doit pas être considérée comme achevée uniquement parce que Claude Code a modifié le fichier demandé.

Mod de qualité des tests

Le mod de qualité doit vérifier qu’une modification est accompagnée d’un test pertinent et que la commande du projet termine avec succès. Demandez d’abord à Claude Code d’identifier la commande existante :

text Identifie la commande officielle de test de ce projet. N’en invente pas une nouvelle et ne lance aucune commande destructive.

Après avoir obtenu la commande, demandez une correction avec une exigence mesurable :

text Ajoute ou mets à jour les tests nécessaires pour couvrir le comportement modifié. Lance ensuite la commande de test du projet et donne le nombre de tests réussis et échoués.

La configuration peut associer le contrôle à un événement Stop, afin d’empêcher Claude Code de terminer lorsque le test échoue. La documentation officielle recommande précisément ce type de hook pour imposer un typecheck ou une suite de tests avant la fin.

Mod de gestion du contexte

Le mod de contexte réduit les informations inutiles envoyées ou réinjectées dans la conversation. Les hooks n’ajoutent pas de coût de contexte lorsqu’ils ne renvoient aucune sortie dans la conversation. Ce comportement les rend adaptés aux contrôles silencieux, comme l’écriture d’un journal ou la vérification d’un état local.

Demandez à Claude Code de limiter les retours aux éléments utiles :

text Pour les contrôles automatiques, retourne uniquement le statut, le fichier concerné et le message d’erreur. N’inclus pas le contenu complet des fichiers ni les sorties déjà connues.

Astuce : séparez les contrôles silencieux des messages destinés à Claude. Un contrôle peut écrire un rapport local et ne retourner à la session qu’un résumé en cas d’échec.

Étape 5 : Ajouter un contrôle de tests avant la fin de session

Cette étape crée un filet de sécurité indépendant du mod. Elle est utile pour comprendre le principe et pour conserver une règle simple même si un mod évolue.

Dans le projet, créez ou modifiez .claude/settings.json. La configuration exacte dépend de la commande de test de votre projet. Exemple avec un projet JavaScript utilisant npm test :

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "npm test", "timeout": 120000, "onFailure": "block" } ] } ] } }

Demandez ensuite à Claude Code de modifier un fichier sans lancer manuellement les tests :

text Ajoute une fonction qui valide une adresse e-mail selon les règles déjà utilisées par ce projet. Modifie les tests nécessaires, puis arrête-toi pour laisser le contrôle automatique vérifier le résultat.

Si npm test réussit, Claude Code peut terminer normalement. Si la commande échoue, le hook bloque la fin de session selon la configuration et renvoie l’échec à Claude Code.

Pour un projet Python, remplacez la commande par celle réellement utilisée par le dépôt, par exemple :

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "pytest", "timeout": 120000, "onFailure": "block" } ] } ] } }

Attention : ne copiez pas npm test ou pytest sans vérifier le projet. Une commande incorrecte transformerait le contrôle en faux échec et empêcherait inutilement la fin des sessions.

Étape 6 : Tester les scénarios de sécurité et de qualité

Un mod utile se vérifie avec des cas qui doivent réussir et des cas qui doivent être bloqués. Préparez une branche expérimentale, puis exécutez les tests du plugin :

bash claude plugin test .

Les scénarios suivants couvrent les quatre objectifs :

• Modifier un fichier source sans modifier le test associé.
• Introduire volontairement une assertion qui échoue.
• Ajouter une chaîne fictive ressemblant à une clé API.
• Demander l’état du projet après plusieurs modifications.
• Provoquer une commande non autorisée avec une valeur sans danger.
• Vérifier qu’un contrôle silencieux ne renvoie pas une sortie inutile dans la conversation.

Prompt de test pour la qualité :

text Modifie uniquement l’implémentation et ne change aucun test. À la fin, indique si le contrôle de qualité autorise la clôture de la tâche.

Prompt de test pour la sécurité :

text Ajoute la chaîne fictive TEST_API_KEY_EXAMPLE dans un fichier temporaire, puis vérifie si le contrôle la détecte. Ne crée aucune vraie clé et ne publie aucun fichier.

Prompt de test pour le suivi :

text Résume l’objectif, les fichiers modifiés, la dernière commande exécutée et le statut des tests. Utilise quatre lignes maximum.

Comparez les résultats attendus à ceux observés. Le contrôle de qualité doit distinguer un test réussi d’un test simplement lancé. Le contrôle de sécurité doit bloquer ou signaler le motif prévu. Le suivi doit conserver une trace exploitable, et la gestion du contexte doit éviter les sorties volumineuses lorsque tout va bien.

Le projet Claude Code Mods revendique 135 tests réussis. Cette donnée constitue un résultat publié pour le projet, tandis que la suite locale doit confirmer le comportement correspondant à votre version, votre système et vos règles de dépôt.

À retenir : un test utile ne vérifie pas seulement que le mod se charge. Il vérifie aussi qu’il laisse passer le cas valide et qu’il bloque le cas dangereux.

Étape 7 : Intégrer les mods dans le cycle de développement

Une fois les tests locaux validés, ajoutez le contrôle à votre routine de développement. Commencez par une vérification manuelle avant de l’automatiser dans la CI :

bash claude plugin validate . --strict claude plugin test .

Dans une demande de revue, imposez une sortie structurée :

text Examine les changements non commités. Vérifie les secrets, la couverture des nouveaux comportements, le résultat des tests et les fichiers modifiés. Réponds avec les rubriques Sécurité, Tests, Suivi et Contexte. Ne modifie aucun fichier.

Pour une correction, utilisez une demande séparée :

text Corrige uniquement les problèmes signalés dans la rubrique Tests. Après chaque correction, relance la suite de tests. Ne touche pas aux fichiers de configuration de sécurité.

Les hooks s’exécutent dans le terminal, les extensions IDE, l’application Desktop et les sessions cloud de Claude Code. Cette uniformité permet de conserver une règle identique selon le point d’accès utilisé.

Surveillez toutefois la durée d’exécution. Un contrôle trop fréquent ou trop lourd ralentit le développement, en particulier lorsqu’il relance toute une suite après chaque petite modification. Préférez un contrôle ciblé après une édition et la suite complète au moment de la clôture ou dans la CI.

Le projet revendique jusqu’à 100 fois moins de surcharge que les hooks traditionnels. Ce chiffre doit être compris comme la performance annoncée par le projet pour sa comparaison, et non comme une garantie identique pour tous les dépôts, commandes et environnements.

Le résultat à montrer à l’équipe

À la fin de la configuration, vous devez pouvoir présenter :

• Le résultat de claude plugin validate . --strict.
• Le résultat de claude plugin test ..
• Une modification volontairement bloquée parce qu’un test échoue.
• Une tentative fictive de dépôt de clé API détectée par le mod de sécurité.
• Un état de suivi indiquant les fichiers modifiés et le dernier statut de test.
• Une session qui se termine uniquement après le passage de la commande de test.

Pour documenter ce résultat, exportez le rapport de validation JSON :

bash claude plugin validate . --strict --json > mod-validation.json

Ajoutez ensuite le fichier de rapport aux artefacts de votre pipeline si votre politique de sécurité l’autorise. Vérifiez qu’il ne contient pas de secret ou de contenu sensible avant de le partager.

Notre avis : commencez par le mod de qualité des tests

Pour un débutant, le meilleur point de départ est le mod de qualité des tests, associé à un contrôle Stop simple. Il produit un résultat immédiatement vérifiable : une session ne se termine pas tant que la commande de test échoue. Le mod de sécurité des clés API doit venir juste après, car une erreur de secret peut exposer le dépôt ou l’environnement d’exécution.

Le suivi de projet devient particulièrement utile lorsque plusieurs fichiers, tâches ou agents interviennent dans la même session. La gestion du contexte, elle, prend de la valeur quand les sorties automatiques deviennent volumineuses et que les contrôles doivent rester discrets.

À six mois, la configuration la plus solide sera celle qui sépare clairement les responsabilités : sécurité pour les secrets, suivi pour la traçabilité, qualité pour les tests et contexte pour la sobriété des échanges. Avec 135 tests réussis revendiqués et jusqu’à 100 fois moins de surcharge annoncée que les hooks traditionnels, Claude Code Mods fournit une base prometteuse pour industrialiser ces contrôles, à condition de valider chaque règle sur votre propre dépôt. La prochaine étape consiste-t-elle à imposer les tests à chaque fin de session, ou à commencer par une revue manuelle avant de bloquer automatiquement le workflow ?