Développer une CLI multiplateforme dans un arbre de travail partagé sans abîmer le travail des autres

## Chercher et modifier uniquement dans l'arbre de travail actuel Lorsque le développement utilise des arbres de travail, le répertoire de travail actuel constitue le dépôt complet de la branche active. Limitez les recherches, la lecture, la compilation, les tests et les modifications à cette racine. - Utilisez des chemins relatifs ou des chemins résolus sous la racine actuelle. - Ne supposez pas qu’un répertoire parent constitue le dépôt. - Ne recherchez ni implémentations ni configurations dans les arbres de travail voisins. - Refusez les chemins codés en dur vers le répertoire personnel d’un développeur. - Résolvez les chemins des fixtures et des sources à partir de la racine active. Sortir de l’arbre de travail peut mêler du code obsolète provenant d’une autre branche à l’analyse et aux modifications. ## Ne pas réinitialiser ni effacer les modifications des autres sessions Partez du principe que les fichiers et modifications inconnus peuvent appartenir à une autre session active. Ne supprimez, ne réinitialisez, n’abandonnez et n’écrasez jamais un travail au seul motif qu’il sort du cadre de la tâche actuelle. - Préservez les fichiers que vous n’avez pas créés. - Demandez avant de supprimer des fichiers non suivis. - N’exécutez aucune opération de `reset`, `checkout-discard`, `clean` ou `stash-deletion` sans autorisation explicite. - Si les hooks échouent à cause de fichiers non modifiés, signalez le conflit au lieu de les modifier. - Limitez les modifications au périmètre demandé et examinez le diff final. Traitez l’état partagé de l’arbre de travail comme des données utilisateur dont la propriété doit être établie avant toute action destructive. ## Ajouter des commandes via un registre plutôt que par des conditions dispersées Utilisez un registre pour rendre les commandes, les fournisseurs et les intégrations extensibles. Toute nouvelle implémentation doit respecter une interface stable et s’enregistrer par une voie canonique unique, plutôt que d’ajouter des conditions dans toute l’application. - Définissez des interfaces pour les comportements majeurs. - Injectez les dépendances par des constructeurs ou des champs. - Générez les mocks avec le générateur pris en charge par le dépôt. - Utilisez des options fonctionnelles pour proposer une configuration extensible assortie de valeurs par défaut. - Conservez l’implémentation de chaque commande dans un fichier ciblé. - Ajoutez des packages spécialisés plutôt que d’étendre un package générique d’utilitaires. Examinez les couches existantes de commandes, d’exécution et de packages avant d’introduire une logique parallèle. ## Réserver le contexte à l'annulation et aux délais, et faire passer les flags par un seul analyseur Utilisez le contexte de requête uniquement pour l’annulation, les échéances et les rares valeurs limitées à la requête. Lorsqu’il est accepté, transmettez-le en premier. N’utilisez pas le contexte pour dissimuler la configuration, les dépendances ou les paramètres ordinaires. Modélisez la configuration comme un pipeline déterministe : 1. chargez les sources de configuration ; 2. traitez les imports et l’héritage ; 3. appliquez l’ordre de priorité des flags de commande, puis de l’environnement et des fichiers, jusqu’aux valeurs par défaut ; 4. effectuez le rendu des modèles pris en charge ; 5. générez la configuration effective. Faites passer les flags et la liaison des variables d’environnement par l’analyseur unifié. Lors de l’ajout d’une option, mettez à jour chaque schéma responsable et ne contournez jamais la couche centrale de liaison. ## Envoyer les données pour les pipes et les messages pour les gens vers des flux distincts Écrivez les résultats exploitables par un pipe uniquement dans le flux de données. Écrivez les invites, la progression, les avertissements et les messages formatés pour les utilisateurs dans le flux d’interface. Réservez la journalisation structurée aux événements système plutôt qu’aux sorties destinées aux utilisateurs. - Utilisez des abstractions d’E/S partagées au lieu d’imprimer directement. - Laissez la couche UI gérer les couleurs, les icônes, Markdown, la largeur du terminal et la détection des capacités. - Dégradez automatiquement l’affichage si le terminal ne prend pas en charge les styles ou si l’exécution a lieu en intégration continue. - Préservez la validité des données structurées lorsque le formatage destiné aux utilisateurs est désactivé. - Masquez les secrets de manière cohérente et ne collectez aucune donnée utilisateur dans la télémétrie. Les flags de test ou d’enregistrement peuvent imposer certaines caractéristiques du terminal, mais les valeurs par défaut de production doivent rester adaptées à l’environnement. ## Garder des fonctions courtes et envelopper les erreurs dans des catégories stables Veillez à ce que les fichiers et les fonctions restent ciblés. Extrayez des étapes nommées des orchestrations très complexes afin que la fonction de niveau supérieur se lise comme un pipeline linéaire. - Respectez les conventions du dépôt pour le formatage, le regroupement des imports, les alias et la ponctuation des commentaires. - Conservez les commentaires utiles et actualisez-les lorsque le comportement change. - Appliquez le suivi standard des performances aux opérations publiques significatives. - Exemptez les accesseurs triviaux, les constructeurs, les recherches pures et les délégations simples lorsque la politique l’autorise. - Encapsulez les erreurs dans des catégories stables et préservez leurs causes. - Combinez les défaillances indépendantes sans perdre aucune chaîne d’erreurs. - Vérifiez les erreurs encapsulées par correspondance sémantique plutôt que par comparaison de chaînes. Utilisez des constructeurs d’erreurs riches lorsque les utilisateurs ont besoin de conseils, de contexte ou d’une sémantique de sortie. ## Tester le comportement avec des mocks et des tests qui peuvent vraiment échouer Privilégiez des tests unitaires rapides avec des mocks générés pour les comportements isolés, puis ajoutez une couverture d’intégration ou d’acceptation lorsque le comportement public d’une commande franchit des limites réelles. - Utilisez des cas pilotés par table pour couvrir les entrées et les erreurs. - Testez le comportement plutôt que l’implémentation interne. - Supprimez les stubs, les tests tautologiques et les tests ignorés de façon permanente. - Pour les collections fusionnées, modifiez séparément le résultat et la source afin de démontrer l’isolation dans les deux sens. - Pour les résultats de type `slice`, vérifiez un contenu représentatif ainsi que la longueur. - Ajoutez des tests négatifs démontrant que la récupération ne se déclenche pas lorsque sa condition est absente. - Utilisez la correspondance sémantique des erreurs pour les défaillances encapsulées. La couverture ne constitue une preuve que si les assertions peuvent échouer pour le comportement protégé. ## Écrire des tests qui tournent sur tous les systèmes et échouent clairement si la préparation manque Les tests doivent s’exécuter sur les plateformes de bureau et de serveur prises en charge sans supposer l’existence d’un shell, d’un séparateur de chemin ou d’un utilitaire propre à une plateforme. - Construisez les chemins à partir de composants distincts avec la bibliothèque de chemins standard. - Normalisez les séparateurs uniquement pour comparer de manière portable les suffixes ou les affichages. - Utilisez l’exécutable de test ou un exécuteur injecté plutôt que des commandes propres à une plateforme. - Intégrez les contrôles de sous-processus à un point d’entrée de test existant au lieu d’en définir un autre. - Résolvez les racines des fixtures en chemins absolus avant de les parcourir ou de les compter. - Faites échouer explicitement les gardes de prérequis et de comptage des fixtures lorsque la configuration requise manque. - Ajoutez des sentinelles à la compilation pour les champs de schéma dont le renommage doit faire échouer le test. Vérifiez la propagation implicite de l’environnement dans un sous-test explicite de prérequis avant de tester un comportement de sous-processus qui en dépend. ## Régénérer les snapshots avec les outils de test au lieu de les modifier à la main Les snapshots de référence incluent le formatage invisible, la largeur du terminal, les styles et les sorties sensibles à l’environnement. Ne les modifiez jamais manuellement. - Régénérez les snapshots au moyen du flag de test ou du générateur pris en charge. - Examinez le diff obtenu avant de l’accepter. - Ne faites pas passer les tests de snapshots ou de terminal dans un pipe, car la redirection peut modifier la détection des capacités. - Régénérez ensemble les enregistrements associés lorsque l’aide ou la sortie d’une commande change. - Vérifiez dans les enregistrements les échecs de commande, les références manquantes et les fuites de chemins propres à une machine. - Ne modifiez pas les fixtures protégées ni les données de test sans périmètre explicite. Les sorties générées doivent être modifiées par l’intermédiaire de leur source responsable et du workflow canonique. ## Documenter chaque nouvelle commande et consigner le travail reporté dans un ticket Chaque nouvelle commande, chaque flag, chaque paramètre ou chaque surface de configuration doit faire l’objet d’une documentation destinée aux utilisateurs et comprenant les métadonnées, l’utilisation, les exemples, les arguments, les flags et les preuves visuelles exigés par le dépôt. - Vérifiez l’identifiant déclaré de la page plutôt que de déduire une URL du nom du fichier. - Générez le site de documentation après les modifications et vérifiez les liens, les images et les composants. - Régénérez les captures visuelles lorsque le comportement, l’aide ou la sortie d’une commande change, mais pas pour de simples modifications de prose. - Placez les documents d’exigences à l’emplacement prévu et respectez leur convention de nommage. - Lorsqu’un travail est reporté, créez une issue suivie et associez son identifiant avant le merge. - Veillez à ce que les notes de version, les données de feuille de route et les labels correspondent à la catégorie de la modification. La documentation reste incomplète lorsqu’elle promet un suivi qui n’est pas enregistré. ## Mettre à jour les révisions sans contourner les hooks ni lancer de commandes Git destructrices Utilisez le workflow de révision du dépôt et limitez les automatisations de maintenance récurrente à la session, sauf autorisation explicite d’un service durable. - Effectuez un `rebase` ou une mise à jour uniquement selon le processus de branche approuvé. - Vérifiez l’intégration continue et traitez les fils de révision non résolus. - Répondez dans le fil de révision d’origine et vérifiez le lien. - Exécutez le lint et la couverture de tests limités au patch avant de mettre à jour la révision. - Ne contournez pas les hooks et n’utilisez pas de flags sans vérification. - Ne validez pas de notes temporaires, de recherches ou de marqueurs non résolus. N’exécutez jamais de commandes Git destructives et ne supprimez jamais le travail d’une autre session sans confirmation explicite de ce qui sera perdu. ## Reproduire chaque bug par un test d'abord et corriger la cause des vérifications en échec Pour un bug, commencez par écrire un test qui le reproduit, observez l’échec, implémentez la plus petite correction possible et recherchez les régressions. Avant de terminer, confirmez que : - le projet se compile avec la chaîne d’outils épinglée ; - les fichiers modifiés passent le formateur et le linter canoniques ; - les tests courts réussissent, et les tests complets ou d’acceptation sont exécutés lorsque le chemin concerné l’exige ; - la couverture atteint le seuil imposé sans assertions théâtrales ; - les mocks, schémas, snapshots, documents et captures visuelles générés sont à jour ; - les limites de complexité et de taille de fichier restent respectées ; - les chemins multiplateformes et les tests de sous-processus sont portables ; - aucun secret, aucune donnée utilisateur et aucun travail sans rapport n’ont été introduits dans le diff. Corrigez la cause de chaque contrôle ayant échoué au lieu d’affaiblir le contrôle.