Communitygithub.com

barlevalon/skills

Compétences portables pour les workflows d'ingénierie assistés par IA

Qu'est-ce que skills ?

Cette compétence (skill) pour agents IA, nommée `barlevalon/skills`, fournit un guide structuré pour adopter le développement piloté par les tests (TDD) dans le cadre de workflows d'ingénierie logicielle assistés par IA. Elle est conçue pour des outils comme Claude Code, Cursor ou Codex, et se concentre sur un principe fondamental : un changement de comportement ne gagne la confiance que si un test a d'abord échoué pour la bonne raison, puis réussi grâce à l'implémentation. La compétence détaille un workflow itératif en quatre phases — Planifier, ROUGE (test échouant), VERT (implémentation minimale), REFACTOR — et met en garde contre les anti-patrons comme les tranches horizontales (écrire tous les tests avant l'implémentation) ou les tests couplés à l'implémentation. Elle insiste sur l'utilisation d'interfaces publiques, les tests de type intégration, et fournit des checklists, des règles strictes ("fer rule"), des conseils pour tester les CLI, ainsi qu'un tableau de pièges de rationalisation et de drapeaux rouges. L'objectif est de guider l'IA à produire du code fiable et testé, en évitant les tests fragiles et en favorisant la conception modulaire et testable.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add barlevalon/skills

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Développement Piloté par les Tests (TDD)

Principe fondamental

Un changement de comportement ne gagne la confiance que lorsqu'un test a d'abord échoué pour la bonne raison, puis réussi grâce à l'implémentation.

Les tests doivent vérifier le comportement au travers des interfaces publiques, et non les détails d'implémentation. Le code peut changer entièrement ; ce n'est pas le cas des tests.

Les bons tests sont de style intégration : ils exercent des chemins de code réels via des API publiques. Ils décrivent ce que le système fait, pas comment il le fait. Un bon test se lit comme une spécification : « l'utilisateur peut passer à la caisse avec un panier valide » vous indique exactement la capacité qui existe. Ces tests survivent aux refactorisations car ils ne se soucient pas de la structure interne.

Les mauvais tests sont couplés à l'implémentation. Ils simulent (mockent) des collaborateurs internes, testent des méthodes privées, vérifient des compteurs d'appels, ou valident par des moyens externes au lieu de l'interface publique. Signe d'alerte : le test casse après une refactorisation alors que le comportement est resté le même.

Voir tests.md, mocking.md, et testing-anti-patterns.md.

Règle de fer

Aucun changement de comportement en production sans un test qui échoue d'abord.

Signification :

  • Écrivez un test pour un comportement.
  • Exécutez-le et observez son échec.
  • Confirmez que l'échec prouve le comportement manquant, et non une faute de frappe/erreur de configuration.
  • Écrivez le plus petit changement de production qui le fait réussir.
  • Refactorisez seulement après le vert.

Si du code d'implémentation existe déjà avant un test :

  • Ne supprimez pas le travail de l'utilisateur sans permission.
  • Considérez-le comme une référence exploratoire (spike), pas une implémentation validée.
  • Préférez le mettre de côté, écrire le test qui échoue, puis implémenter à partir du test.
  • Si la préservation du code existant est nécessaire, ajoutez d'abord un test de régression ou de caractérisation, puis modifiez le comportement avec un nouveau test qui échoue.

Anti-patron : tranches horizontales

N'écrivez pas tous les tests d'abord, puis toute l'implémentation. C'est ce qu'on appelle une tranche horizontale.

Erroné :

ROUGE : test1, test2, test3, test4
VERT  : impl1, impl2, impl3, impl4

Correct :

ROUGE -> VERT -> REFACTOR : comportement 1
ROUGE -> VERT -> REFACTOR : comportement 2
ROUGE -> VERT -> REFACTOR : comportement 3

Pourquoi : les tests en masse encodent une conception imaginée, dépassent le retour d'information, et testent souvent des formes plutôt que des comportements.

Workflow

1. Planifier le comportement

Avant d'écrire du code :

  • Confirmer les changements d'interface publique avec l'utilisateur quand ce n'est pas évident.
  • Lister les comportements à tester, pas les étapes d'implémentation.
  • Prioriser les chemins critiques et la logique complexe ; ne cherchez pas une exhaustivité factice.
  • Identifier les opportunités de modules profonds.
  • Concevoir les interfaces pour la testabilité.
  • Choisir le premier comportement traceur (tracer bullet).

Demandez : « Quel comportement public doit exister ? Quel comportement compte en premier ? »

2. ROUGE : un test qui échoue

Écrivez un test minimal pour un comportement observable.

Exigences :

  • Utilise uniquement l'interface publique.
  • Le nom décrit le comportement.
  • Teste le code réel dans la mesure du possible.
  • Ne simule (mock) qu'aux frontières du système ou aux coutures inévitables.
  • Échoue avant l'implémentation.

Exécutez la commande la plus étroite utile, par exemple :

npm test chemin/vers/test.test.ts

Vérifiez l'échec :

  • Le test échoue, pas d'erreurs de configuration/typo.
  • La raison de l'échec correspond au comportement manquant.
  • S'il réussit immédiatement, le test est erroné ou le comportement existe déjà. Corrigez le test ou choisissez le prochain comportement manquant.

3. VERT : implémentation minimale

Écrivez juste assez de code pour faire réussir le test actuel.

Ne faites pas :

  • Ajouter des fonctionnalités spéculatives.
  • Refactoriser du code non lié.
  • Ajouter des options futures.
  • Élargir le périmètre parce que « c'est facile en passant ».

Exécutez :

npm test chemin/vers/test.test.ts

Puis exécutez les tests environnants pertinents. La sortie doit être propre : pas de nouveaux avertissements, de tests instables (flakes) ou d'erreurs cachées.

4. REFACTOR : nettoyer pendant que c'est vert

Refactorisez seulement après que les tests sont verts. Si aucune refactorisation n'est utile, dites-le brièvement et continuez.

Recherchez des candidats à la refactorisation :

  • duplication
  • mauvais noms
  • modules peu profonds
  • limites confuses
  • complexité pouvant être cachée derrière une petite interface

Règles :

  • Le comportement et les attentes ne changent pas.
  • Les tests restent verts après chaque étape de refactorisation.
  • Les refactorisations de test peuvent renommer, dé-dupliquer, extraire des fixtures/constructeurs (builders), ou améliorer les messages d'échec.
  • Si une assertion modifie le comportement attendu, arrêtez : c'est un nouveau cycle ROUGE.

5. Répéter verticalement

Choisissez le comportement suivant en fonction de ce que le dernier cycle vous a appris. Un comportement à la fois.

Liste de vérification par cycle

[ ] Le test décrit un comportement observable, pas l'implémentation
[ ] Le test utilise uniquement l'interface publique
[ ] Le test a échoué avant l'implémentation
[ ] La raison de l'échec était correcte
[ ] Le code est minimal pour ce test
[ ] Aucun comportement spéculatif ajouté
[ ] Les tests pertinents passent proprement
[ ] La refactorisation n'est envisagée que lorsque c'est vert

Étapes de commit

Pour un travail auditable, commitez les phases séparément lorsque c'est pratique :

  • Commit ROUGE : test uniquement ou échafaudage minimal plus assertion qui échoue. Le corps enregistre la commande qui échoue et la raison.
  • Commit VERT : implémentation minimale. Le corps enregistre le test ciblé réussi et la refactorisation envisagée.
  • Commit REFACTOR : aucun changement de comportement ou d'attente. Le corps indique ce qui a changé et ce qui est resté inchangé.

N'incluez pas d'attribution à l'IA dans les commits.

Tests de contrat CLI

Pour les outils en ligne de commande, la surface de commande est le contrat du produit. Préférez les tests de l'extérieur vers l'intérieur au niveau fiable le plus bas :

  1. Tests de contrat CLI : exécutez les commandes racine/sous-commandes avec des fournisseurs fictifs (fake providers) ou des fixtures ; vérifiez stdout, stderr, le comportement de sortie, la forme JSON.
  2. Tests unitaires : analyse syntaxique, comparaison, classification, sélection de contexte, classification d'erreurs.
  3. Tests d'intégration de fournisseur : fixtures de système de fichiers et services externes fictifs (fakes) ; pas de réseau/auth.
  4. Tests de validation en direct (smoke tests) : optionnels uniquement ; vérifiez la forme/les invariants, pas un résultat exact volatil.

Règle de régression pour la QA manuelle

La QA manuelle est une découverte, pas une colonne vertébrale de validation. Lorsqu'elle trouve un écart de comportement :

  1. Écrivez le test de régression ROUGE du plus bas niveau qui le reproduit.
  2. Vérifiez la preuve d'échec.
  3. Implémentez VERT.
  4. Relancez les tests automatisés.
  5. Relancez la QA manuelle seulement après que les tests passent.

Si la sortie/le texte/la forme de la CLI a changé, ajoutez ou mettez à jour un test de contrat CLI.

Pièges de rationalisation

AffirmationRéponse
« Trop simple pour être testé »Un comportement simple régresse quand même. Ajoutez le petit test.
« Je testerai après »Les tests écrits après ne prouvent pas que le test peut échouer.
« Je l'ai vérifié manuellement »Les vérifications manuelles ne sont pas des tests de régression reproductibles.
« Besoin d'explorer d'abord »D'accord. Faites une exploration exploratoire (spike), puis mettez-la de côté et commencez le TDD.
« Le test est difficile »L'interface est peut-être difficile à utiliser. Simplifiez la couture/la conception.
« Le mock simplifie les choses »Vous testez peut-être le comportement du mock. Lisez les anti-patrons.
« Un seul gros test couvre tout »Préférez un comportement par test, sauf si un contrat de bout en bout nécessite plus.
« La refactorisation a besoin d'un test qui échoue »Une refactorisation pure commence verte et reste verte ; un changement de comportement nécessite ROUGE.

Drapeaux rouges : arrêtez et corrigez

  • Le comportement de production a changé avant le test qui échoue.
  • Le test réussit immédiatement mais est présenté comme ROUGE.
  • La raison de l'échec n'est pas inspectée.
  • Le nom du test décrit l'implémentation.
  • Le test vérifie des appels privés, l'ordre des appels ou des collaborateurs internes.
  • La configuration de simulation (mock) domine la logique du test.
  • Une nouvelle méthode existe uniquement pour les tests.
  • Correction du test pendant VERT parce que l'implémentation est en désaccord.
  • Lot horizontal de tests avant toute implémentation.

Quand vous êtes bloqué

ProblèmeAction
Vous ne savez pas comment testerÉcrivez l'API publique souhaitée et la première assertion.
La configuration du test est énormeExtrayez un fixture/helper ; si toujours énorme, simplifiez la conception.
Vous devez tout simuler (mocker)Le code est probablement trop couplé. Introduisez l'injection de dépendances/une couture.
Le code existant n'a pas de testsAjoutez un test de caractérisation pour le comportement actuel, puis ROUGE pour le changement.
Le bogue n'est pas clairReproduisez manuellement/avec des journaux d'abord, puis codez la plus petite régression qui échoue.

Vérification avant de terminer

  • Les comportements nouveaux/modifiés ont des tests.
  • Chaque nouveau test de comportement a été observé échouant pour la bonne raison.
  • Tous les tests pertinents passent.
  • Les tests vérifient le comportement public.
  • Les simulations (mocks) sont uniquement aux limites ou justifiées.
  • Aucune API de production ajoutée uniquement pour les tests.
  • Les découvertes de la QA manuelle sont devenues des tests de régression.

Skills associés