Modifier un dépôt multimodule backend et frontend sans casser la compilation

## Partir de la racine du dépôt et lire les règles de chaque module concerné Ouvrez et coordonnez le projet depuis la racine du dépôt, même lorsqu’une tâche semble limitée à un seul sous-projet. Considérez les instructions d’agent à la racine comme la base et les fichiers d’instructions imbriqués comme des règles locales supplémentaires. Avant toute modification, recensez chaque module que la tâche peut affecter et chargez le fichier d’instructions de chacun. Une tâche qui traverse plusieurs modules doit respecter toutes les règles locales pertinentes, et non uniquement celles du fichier le plus proche de la première modification envisagée. ## Clarifier le rôle de chaque module et modifier backend et frontend ensemble Tenez à jour une carte des responsabilités pour les principales zones : - le module d’API publique est responsable des points d’extension, des contrats de service et des abstractions de sécurité ; - l’application backend est responsable de la logique métier, des services réactifs, du routage, de la sécurité, des migrations et du paquetage ; - l’espace de travail frontend est responsable des interfaces d’administration et d’utilisation, des paquets partagés et du client d’API généré ; - les modules de la plateforme de dépendances sont responsables des contraintes de l’application et des extensions en aval ; - la documentation destinée aux développeurs est responsable des indications d’architecture et de flux de travail destinées aux personnes. Traitez les modifications du backend et du frontend comme une seule tâche full-stack dès que les contrats, les charges utiles, l’authentification, la navigation ou l’expérience utilisateur franchissent cette frontière. Dans une même modification, synchronisez les contrats publics, les gestionnaires du backend et leur utilisation dans le frontend. ## Régénérer le client quand l’API change, sans le retoucher à la main Évaluez l’impact sur le frontend chaque fois que changent les types publics de requête ou de réponse, les routes, les contrats du routeur, les annotations du schéma d’API, les schémas générés, l’authentification ou le comportement des sessions. Après avoir mis à jour le contrat source, régénérez la description de l’API et le client au moyen des commandes prescrites par le dépôt. Ne modifiez jamais directement les fichiers clients générés. Corrigez le contrat ou l’entrée du générateur, régénérez la sortie et examinez la différence obtenue. Demandez une confirmation avant de modifier de façon destructive une sortie générée ou de changer une API publique dont des consommateurs en aval peuvent dépendre. ## Vérifier comment le frontend est intégré au paquet du backend Comprenez comment la sortie du frontend entre dans l’artefact backend déployable. Si la compilation du backend intègre l’interface compilée aux ressources de l’application, toute modification de la sortie du frontend affecte aussi le chemin de paquetage du backend et doit y être vérifiée. Exécutez depuis la racine la coordination entre couches afin que la compilation du backend, le paquetage de l’interface et les tests utilisent le même graphe de dépendances. Considérez les téléchargements effectués pendant la compilation, les extensions prédéfinies et les ressources de distribution copiées comme des éléments du contrat de compilation, et non comme des fichiers accessoires. ## Lire les versions et les règles de formatage dans les fichiers prévus Lisez les versions des dépendances, la version du projet, la version du langage, les versions des modules complémentaires et les dépendances du frontend dans les catalogues, fichiers de propriétés, scripts de compilation et manifestes de paquets prévus à cet effet. Ne codez pas en dur une version qui dispose déjà d’une source faisant autorité. Utilisez l’outil de formatage et l’analyseur configurés comme sources de référence pour l’indentation, la largeur des lignes et la syntaxe prise en charge. Respectez la version déclarée du langage, y compris `release 21` lorsqu’elle est indiquée, et conservez les règles de formatage de la racine dans la portée où le processus de compilation les attend. ## Ne pas mettre d’E/S bloquante dans le code réactif et garder la base de données au bon endroit N’introduisez aucune entrée ou sortie bloquante dans les chemins d’exécution réactifs, même si les threads virtuels sont activés ailleurs. Conservez le moteur de migration choisi par le projet au lieu de le remplacer silencieusement par un autre, et maintenez les migrations propres à chaque dialecte dans les répertoires de base de données prévus à cet effet. Conservez les schémas d’extension, les données JSON d’exécution, la configuration propre à chaque profil et le répertoire de travail remplaçable dans leurs emplacements respectifs. Utilisez des chemins de fichiers absolus pour les bases de données intégrées fondées sur des fichiers ; un URI relatif peut créer des répertoires indésirables sous le module de l’application et changer la base de données qui est ouverte. ## Choisir les tests selon la partie modifiée Sélectionnez les contrôles selon la portée réelle : - les modifications limitées au backend exigent le formatage du dépôt et les tests backend concernés ; - les modifications limitées au frontend exigent le formatage du frontend, la vérification des types, l’analyse statique et les tests unitaires pertinents ; - les modifications de contrat exigent la génération de la description de l’API, la régénération du client, la validation du frontend et les tests backend ; - les modifications entre couches exigent la vérification de l’artefact final empaqueté en plus des deux côtés du contrat. Exécutez d’abord les contrôles ciblés, puis élargissez leur portée si nécessaire. Ajoutez ou mettez à jour des tests pour chaque comportement modifié et ne soumettez pas le travail tant que des contrôles obligatoires d’intégration continue échouent. ## Vérifier le bon dépôt upstream avant de pousser et n’indexer que les fichiers de la tâche Identifiez le dépôt actuel et inspectez ses dépôts distants avant de pousser des modifications ou d’ouvrir une revue. Ciblez le bon upstream pour cette copie de travail ; utiliser celui d’un dépôt public ou propriétaire associé peut être coûteux à annuler. Commencez le travail à partir de la base prévue de l’upstream et respectez les conventions de branches du dépôt, telles que `upgrade/gradle-X`, `feat/name`, `fix/name` ou `improvement/name`. Ne préparez que les fichiers appartenant à la tâche ; n’utilisez jamais `git add -A` ni `git add .` lorsque des sorties de compilation ou des artefacts de base de données peuvent être présents. Si un arbre de travail obsolète verrouille la branche principale, inspectez la liste des arbres de travail et retirez explicitement uniquement l’entrée dont l’obsolescence est confirmée. Ne remplacez pas l’identification du propriétaire exact du verrou par un nettoyage général. ## Demander avant une migration ou une nouvelle dépendance et ne jamais commiter de secrets Utilisez trois niveaux de contrôle : - travaillez toujours depuis la racine, chargez toutes les règles imbriquées applicables, préparez explicitement les fichiers, régénérez depuis la source les clients dérivés, ajoutez des tests pour les comportements modifiés et signalez dans la description de la revue que le contenu a bénéficié d’une assistance par IA ; - demandez une confirmation avant de modifier des API publiques, d’ajouter des dépendances de compilation ou de paquets, d’écrire des migrations de base de données, de modifier la configuration de sécurité ou les flux d’intégration continue, ou de remplacer de façon destructive une sortie générée ; - ne validez jamais de secrets dans le dépôt, ne codez jamais en dur des versions faisant autorité, n’ajoutez aucune opération bloquante aux chemins réactifs, ne modifiez jamais directement les clients générés et n’ouvrez aucune revue sans avoir confirmé le bon upstream. Ces limites s’appliquent même lorsque la mise en œuvre elle-même est simple. La facilité de développement ne réduit pas les risques liés à la compatibilité, à la sécurité, aux données ou à la mise en production. ## Éviter les pièges connus de la compilation, comme les chemins relatifs de base de données Préservez les invariants connus et propres aux outils : 1. Les emplacements des bases de données intégrées fondées sur des fichiers doivent être résolus en chemins absolus du système de fichiers ; des chemins relatifs peuvent créer des répertoires de module indésirables et amener l’application à ouvrir la mauvaise base de données. 2. La mise à niveau du wrapper de compilation nécessite à la fois la commande du wrapper avec version et une seconde commande de génération du wrapper ; n’exécuter que la première laisse les fichiers de wrapper générés incohérents. 3. Conservez à la racine les autres réglages de formatage applicables à l’ensemble du dépôt. Les déplacer dans un sous-module de l’application combinerait des tâches de formatage incompatibles et déclencherait des erreurs de validation de dépendances implicites dans la version `9.x` de l’outil de compilation. Consignez ces pièges à proximité des instructions de compilation faisant autorité et vérifiez-les chaque fois que la configuration concernée change.