Modifiez un monorepo full-stack sans casser les paquets partagés

## Placez chaque modification dans le module responsable Avant toute modification, cartographiez l’espace de travail. Distinguez les applications produit, les packages d’UI réutilisables, la logique métier partagée, les schémas et migrations de données, les packages de types, les préréglages de configuration, la documentation, les ressources de déploiement et les bancs de test. Placez le comportement propre à une fonctionnalité dans l’application ou le module qui en est responsable. Placez la logique de domaine réutilisable et les types partagés dans des packages dont les consommateurs sont explicites. Séparez l’infrastructure et les éléments annexes du déploiement du code source exécuté. Regroupez les tests unitaires avec la logique stable qu’ils exercent, tandis que les spécifications des parcours dans le navigateur doivent se trouver dans la zone de tests end-to-end de l’application. Ne dupliquez pas une logique partagée dans une application dans le seul but d’éviter de modifier un package. Respectez le sens des dépendances et vérifiez chaque consommateur en aval lorsqu’un package partagé change. ## Recompilez les paquets précompilés et contournez les caches périmés Identifiez les packages précompilés puis copiés dans les ressources publiques d’une application. Une application en cours d’exécution peut importer la sortie de distribution du package plutôt que son code source ; une modification du seul code source peut donc rester invisible. Après avoir modifié un package précompilé ou une dépendance qui affecte son bundle : 1. supprimez uniquement les sorties de distribution connues du package et les artefacts copiés ; 2. contournez le cache du système de build pour le graphe de dépendances concerné ; 3. recompilez le package au moyen de sa tâche officielle dans l’espace de travail ; 4. actualisez ou désactivez le cache du navigateur ; 5. ne redémarrez le serveur de développement que si la ressource recompilée n’est toujours pas chargée. Ne modifiez jamais manuellement les bundles copiés ni les artefacts générés. Considérez l’invalidation du cache comme une étape de la procédure de vérification, et non comme la preuve que la modification du code source a échoué. ## Suivez les règles partagées de lint et de types Utilisez les préréglages partagés du dépôt pour le lint, le formatage et le compilateur plutôt que des surcharges locales. Respectez les règles établies concernant l’indentation, la largeur de ligne, les guillemets, les points-virgules et le regroupement des imports. Nommez les composants et leurs dossiers de manière cohérente, utilisez le lower camel case pour les fonctions et les variables, et réservez l’upper snake case aux véritables constantes. Placez les mocks à l’emplacement prévu afin de préserver la stabilité de la résolution et de l’ordre des imports. Privilégiez les types inférés lorsqu’ils restent clairs, utilisez les types de domaine partagés et évitez les échappatoires non typées. Traitez les props des composants comme immuables. Gardez des composants ciblés, des effets restreints et des dépendances de hooks correctes ; ne recourez à la mémoïsation que si un besoin mesuré la justifie, et non par habitude. ## Séparez la logique serveur et créez les clés de cache avec une seule fabrique Séparez la composition des routes, la logique des services et les modules de fonctionnalités. Les actions serveur doivent appeler des services et renvoyer une structure uniforme de succès ou d’erreur. Les fournisseurs de contexte doivent échouer clairement lorsqu’ils sont utilisés hors de leur provider et doivent nettoyer les effets à l’aide d’instantanés stables plutôt que de références mutables. Utilisez une mémoïsation limitée à la requête pour les travaux dupliqués au sein d’une même requête. Pour les travaux coûteux entre plusieurs requêtes, utilisez l’abstraction de cache partagé approuvée ou un cache distribué explicite. N’introduisez pas une API de cache instable d’un framework si le dépôt l’a rejetée. Créez chaque clé de cache par l’intermédiaire de la fabrique de clés canonique. La clé doit inclure toutes les dimensions susceptibles de modifier le résultat, afin que des utilisateurs, tenants, environnements, locales ou modes de fonctionnalité ne partagent pas des entrées incompatibles. ## Passez les textes par la traduction et séparez fuseau horaire et langue Faites passer tout texte destiné aux utilisateurs par la fonction de traduction et respectez la convention établie de clés en minuscules séparées par des points. Conservez un seul fichier de locale source comme unique source de traduction rédigée manuellement. Ne modifiez jamais à la main les fichiers de locale générés ; exécutez le générateur de localisation et le validateur de clés après toute modification du texte source. Affichez les dates et heures destinées aux utilisateurs au moyen des utilitaires partagés. Obtenez la locale d’affichage depuis la source de vérité de la langue de l’application, jamais depuis une valeur par défaut implicite du navigateur. Traitez la locale et le fuseau horaire comme des éléments indépendants : la locale régit le formatage, tandis que le fuseau horaire régit l’instant représenté. Ne déduisez jamais le fuseau horaire de la locale. Préservez la sémantique existante des valeurs stockées, sauf si le produit définit une source de vérité pour le fuseau horaire. Conservez pour le stockage, les API, les exports, les intégrations et les logs des formats stables et non localisés, comme une représentation UTC ou ISO explicite. ## Séparez les données de chaque organisation et gardez des requêtes rapides Limitez chaque opération sur les données selon la frontière de tenant du dépôt, par exemple l’organisation et l’environnement. Appliquez systématiquement les filtres de suppression logique afin que les enregistrements inactifs ou supprimés ne réapparaissent pas par d’autres chemins de requête. Pour les décomptes, utilisez une requête de comptage filtrée plutôt que des paramètres de pagination par décalage. Exécutez simultanément les requêtes indépendantes de comptage et de données. Préférez la pagination par curseur pour les grands jeux de données et incluez des champs de propriété indexés lorsque vous filtrez par date ou heure. Examinez les modifications de schéma et de migration avec tous les chemins de requête concernés. L’isolation des données est un invariant transversal : l’absence d’un prédicat de tenant n’est pas un problème mineur de performance, mais une défaillance potentielle de la frontière des données. ## Choisissez les tests selon le risque utilisateur, pas le taux de couverture Optimisez la confiance plutôt qu’un pourcentage de couverture : - Utilisez des tests end-to-end dans le navigateur pour les parcours utilisateur critiques, les régressions d’UI et le comportement des composants. - Utilisez des tests unitaires pour la logique pure et stable, notamment les validateurs, les transformateurs, les évaluateurs, les calculs et les cas limites. - Utilisez des vérifications manuelles en staging pour confirmer qu’une release est prête, avec une boucle de correction, de backport et de nouveaux tests pour les problèmes critiques. Gardez les tests de navigateur ciblés, correctement nommés et explicites quant aux suites lentes. Simulez les frontières du réseau et du stockage au moyen des utilitaires partagés. N’ajoutez pas de snapshots de composants fragiles, d’assertions sur le balisage, de tests de détails d’implémentation, d’astuces de temporisation, de parcours démesurés ni de tests peu pertinents créés uniquement pour augmenter la couverture. Exécutez la suite unitaire standard avant l’examen, mesurez la couverture lorsque des parcours critiques changent et lancez la suite end-to-end directement concernée en cas de risque pour un parcours. ## Tenez à jour la documentation et les exemples de composants Respectez le contrat de fichiers, les champs de métadonnées, les règles de titres et les composants approuvés d’étape ou d’encadré du système de documentation. Signalez le contenu des éditions restreintes avec l’avis standard plutôt que d’inventer un nouveau badge ou un nouveau libellé. Conservez les exemples de composants à côté du composant et importez-les par son point d’entrée public. Organisez les contrôles selon les groupes standard du dépôt. Couvrez l’état par défaut, l’état désactivé s’il est pris en charge, l’état avec icône s’il est pris en charge, toutes les variantes et les cas limites pertinents. Avant de créer ou d’examiner une UI, chargez le contexte de conception de la surface concernée. Les recommandations de conception partagées complètent les conventions du code et restent la source de vérité pour les tokens, les composants, les animations et la qualité visuelle. ## Donnez aux workflows de CI seulement les permissions nécessaires N’accordez aux tokens d’automatisation que les autorisations requises par chaque workflow. Commencez les jobs Linux hébergés par l’étape approuvée de renforcement du runner, afin de limiter le comportement du réseau et des processus avant l’exécution du code du projet. Traitez les fichiers de verrouillage des dépendances comme la référence et exécutez les commandes de l’espace de travail à l’aide du gestionnaire de packages choisi par le dépôt. Évitez les commandes ponctuelles d’installation ou de build qui contournent le graphe de tâches, l’environnement partagé ou les métadonnées de cache. Lorsque vous modifiez un workflow, vérifiez les déclencheurs d’événements, les autorisations, l’exposition des secrets, les clés de cache, les artefacts et la propagation des échecs. La réussite d’une étape en aval ne doit pas masquer l’échec d’un prérequis. ## Livrez une pull request avec résultats de tests et captures d’écran Avant de terminer, supprimez le code mort et les imports inutilisés, exécutez la commande de lint faisant autorité et lancez le plus petit ensemble de tests qui démontre la modification, ainsi que tout parcours plus large directement concerné. Gardez les commits ciblés et conformes à la convention de commits du dépôt. Une pull request doit exposer le problème, résumer la solution, renvoyer à l’issue ou à la spécification qui fait autorité et signaler les migrations ou les changements d’environnement. Joignez des preuves visuelles pour les travaux d’UI et indiquez les résultats des commandes pertinentes de lint, de test, de build et de migration. Les personnes chargées de l’examen doivent pouvoir déterminer ce qui a changé, pourquoi cela relève de ce module, comment les résultats générés ont été actualisés et quels risques ont été vérifiés, sans avoir à reconstituer le travail à partir du seul diff.