Modifier un monorepo typé sans le casser et garder son wiki à jour

## Trouver les packages, tests et docs touchés par une modification Considérez les instructions racine destinées aux agents comme le contrat commun à tous les agents de programmation. Tout fichier d’instructions propre à un outil doit rester succinct et renvoyer à ce contrat au lieu de le dupliquer. - Identifiez les emplacements des packages principaux, des intégrations facultatives, des outils de développement, des modules de l’écosystème, des exemples, de la documentation et des tests. - Attendez-vous à trouver les tests et les fixtures près du package qu’ils exercent, sauf indication contraire du dépôt. - Lisez les instructions du package le plus proche avant de modifier un sous-système. - Avant de toucher aux fichiers, reliez la modification demandée au package responsable, à son interface publique, à ses tests et à sa documentation. - Préférez le plus petit périmètre affecté ; ne transformez pas une tâche ciblée en réécriture de tout le dépôt. ## Utiliser le gestionnaire de paquets et les scripts du dépôt Utilisez le gestionnaire de packages, la définition du workspace, la version du runtime et les scripts déclarés par le dépôt. Ne les remplacez pas par une solution familière simplement parce qu’elle est installée localement. - Utilisez la commande d’installation documentée pour préparer le workspace. - Utilisez les scripts racine de build, de test, de lint et de vérification des types pour les contrôles complets. - Utilisez les filtres de workspace pris en charge pour travailler sur un package ciblé. - Préservez exactement la transmission des arguments lorsqu’un wrapper passe des options à un outil sous-jacent. - Consultez les fichiers de configuration du dépôt avant de modifier les hypothèses concernant le gestionnaire de packages ou le runtime. - Consignez tout prérequis dont dépend une commande plus restreinte. ## Lancer les tests dans l’ordre de la CI, sans anciens fichiers de build Reproduisez l’ordre de l’intégration continue au lieu d’inventer une séquence locale. Si la CI installe les dépendances puis exécute sa commande de validation sans build préalable, exécutez les tests de la même manière. - Ne lancez pas de build en premier lorsque les sorties générées peuvent être découvertes aux côtés des fichiers source. - Considérez les erreurs de double enregistrement, de schéma dupliqué ou de classe décorée en double comme un indice possible du chargement simultané des sources et des fichiers générés. - Ne retirez que les répertoires de sorties générées situés sous les racines source documentées, en excluant les dépendances, les tests et les fixtures. - Ne supprimez jamais de répertoire source pour corriger un échec lié à des sorties générées. - Réexécutez le test en échec après le nettoyage, avant de modifier le code d’implémentation. - Si le nettoyage ne modifie pas l’échec, reprenez le débogage ordinaire en tenant compte des nouveaux éléments. ## Suivre le style du code et ne pas mettre l’état de l’app en global Préférez les pratiques établies du dépôt aux nouvelles abstractions. Utilisez le système de modules, les conventions du langage typé, le formateur, le linter et le style de nommage des fichiers déjà adoptés par la base de code. - Conservez des noms de fichiers en minuscules séparés par des traits d’union lorsque telle est la convention du dépôt. - Apportez les modifications d’API publique de manière délibérée, couvrez-les par des tests et documentez-les. - Conservez l’état mutable du runtime propre à une application dans une portée appartenant à cette application, plutôt que dans un singleton global au processus. - Utilisez le stockage à portée limitée du framework pour les utilitaires de cycle de vie et les autres services propres à une application. - Réintégrez la portée de l’application propriétaire pour les callbacks détachés, tels que les timers, les écouteurs d’événements, les gestionnaires de proxy et les points de sortie au niveau des modules. - N’ajoutez pas de wrappers de portée redondants autour d’accesseurs déjà rattachés au bon contexte d’application. ## Rendre les modules chargés au démarrage compatibles avec les snapshots Lorsqu’un runtime peut sérialiser un snapshot de démarrage, supposez que l’amorçage au moment du build peut s’arrêter avant le démarrage normal de l’application. Tout module chargé pendant cette phase doit pouvoir être sérialisé en toute sécurité. - Maintenez les modules externes lorsque leur importation ou leur amorçage crée un état natif non sérialisable. - Considérez les analyseurs HTTP, les liaisons HTTP/2, les contextes TLS, les canaux DNS, les instances WebAssembly, les observateurs de fichiers, les extensions natives et les sockets ouverts comme des dépendances à haut risque pour les snapshots. - Acheminez les modules externalisés par la passerelle de chargement du runtime au moment de la restauration. - Maintenez une liste par défaut unique et documentée des modules qui doivent rester différés ou externes. - Étendez cette liste au moyen de la configuration prise en charge par le dépôt, plutôt qu’en modifiant les sorties générées. - Distinguez la création directe d’un état natif de l’utilisation transitive du réseau : des modules intégrés externalisés et chargés tardivement peuvent déjà protéger les dépendances transitives, tandis qu’un package qui crée directement un état natif ou WebAssembly exige toujours un traitement explicite. - Ajoutez un test de build du snapshot lorsqu’une dépendance du framework peut accéder à la pile native ou réseau pendant l’amorçage. ## Regrouper les ajouts de types globaux dans un module de types dédié Placez les extensions globales propres à tout un package dans un module dédié aux types globaux. Les extensions partagées qui servent plusieurs packages doivent appartenir à un package de types partagé, et non à un seul consommateur. - Conservez les fichiers de déclaration en tant que modules grâce à un import, un import de type uniquement ou un export vide. - Importez l’extension partagée depuis le point d’entrée du package qui a besoin de cette surface de types. - Évitez les déclarations ambiantes qui deviennent globales uniquement parce qu’un fichier ne contient aucune syntaxe de module. - Testez à la fois le package qui définit les types et au moins un package consommateur après le déplacement de types partagés. - Documentez toute modification de la surface publique des types. ## Lancer les tests utiles et relire le diff final avant de rendre compte Exécutez les contrôles les plus ciblés qui prouvent le comportement modifié, puis élargissez-les uniquement lorsque la limite affectée l’exige. - Ajoutez une couverture de régression pour les modifications touchant les chargeurs, le cycle de vie de l’application, le clustering, les agents, la gestion HTTP ou le comportement des processus. - Exécutez le formatage, le linting, la vérification des types et les tests pertinents au moyen des scripts du dépôt. - Respectez la convention de messages de commit du dépôt et conservez une portée exacte. - Expliquez la motivation, le comportement modifié, les risques et les preuves de test dans la description de la modification. - Examinez la différence finale afin de repérer les modifications sans rapport, le bruit généré et les changements publics non documentés. - N’annoncez pas la réussite avant que la commande pertinente ne se soit terminée avec succès. ## Ne pas committer de secrets et s’arrêter avant de publier une faille Lisez la politique de sécurité du dépôt avant de traiter un travail lié à une vulnérabilité. N’incluez jamais dans un commit des secrets, des identifiants d’accès, des points d’accès privés ou une configuration propre à une machine. - Maintenez les versions locales du runtime et du gestionnaire de packages alignées sur les déclarations du dépôt. - Traitez les lockfiles et la configuration du workspace comme des entrées coordonnées ; ne les modifiez que pour une mise à jour intentionnelle d’une dépendance ou de la chaîne d’outils. - Utilisez des valeurs fictives dans les exemples et la documentation à la place de vrais identifiants ou URL privés. - Limitez strictement les modifications sensibles pour la sécurité et ajoutez une couverture de régression pour la limite protégée. - Arrêtez-vous avant de publier les détails d’une vulnérabilité ou de modifier des systèmes externes protégés, sauf si la tâche autorise explicitement cette action. ## Séparer le code et les autres sources, le wiki et les règles de l’IA Maintenez trois couches de connaissances distinctes. Les sources brutes constituent les preuves faisant autorité, le wiki conserve la synthèse durable et les instructions racine destinées aux agents définissent les règles de travail partagées. - Traitez le code, la documentation destinée aux utilisateurs, les fichiers racine du projet, les artefacts externes explicites et les documents bruts importés comme des preuves source. - Commencez par les résumés du wiki pour vous orienter, mais vérifiez les sources brutes lorsque les détails, les conflits ou la fraîcheur sont importants. - Ne réécrivez pas les sources brutes, sauf si la tâche l’exige. - Enregistrez les preuves externes utilisées à plusieurs reprises dans la base de connaissances du dépôt. - Consignez les conflits au lieu de les aplanir en un faux consensus. - Gardez les fichiers d’agent propres à un outil succincts et faites-les pointer vers le schéma partagé. ## Donner à chaque page du wiki un seul sujet et ses fichiers sources Attribuez à chaque page de connaissances substantielle un sujet clair et un type de page déclaré, tel que package, concept, workflow, décision ou source. - Utilisez des noms de fichiers en minuscules séparés par des traits d’union. - Incluez un frontmatter avec un titre lisible, le type de page, un résumé d’une ligne, les principaux chemins source, la date locale du calendrier et l’état de fraîcheur. - Listez les affirmations non triviales avec des fichiers source traçables. - Identifiez comme inférence toute synthèse qui n’est pas évidente. - Marquez les affirmations obsolètes ou non résolues lorsque leur fraîcheur est incertaine. - Gardez l’index du wiki concis et organisé par catégorie. - Utilisez un journal en ajout seul pour les ingestions importantes, les résultats durables, les refactorisations majeures et les changements qui modifient la compréhension consignée. - Ne consignez pas les modifications triviales qui corrigent uniquement des fautes de frappe. ## Lire l’index du wiki avant d’ajouter des sources ou de répondre aux questions Utilisez un workflow prévisible lors de l’ingestion de sources, des réponses aux questions sur le dépôt ou du contrôle de la base de connaissances. - Pour l’ingestion, lisez l’index, recherchez les pages existantes qui doivent intégrer le contenu, créez ou mettez à jour une page source lorsque cela se justifie, actualisez les pages affectées, rafraîchissez l’index et ajoutez une entrée au journal pour les changements importants. - Pour les requêtes, lisez d’abord l’index et les pages de wiki pertinentes, vérifiez les sources brutes, consignez les nouvelles conclusions durables et journalisez les changements importants apportés aux connaissances. - Pour le contrôle, recherchez les pages orphelines, les affirmations obsolètes, les concepts dupliqués, les références source manquantes, l’absence de pages pour les domaines fréquemment utilisés et les contradictions. - Préférez restructurer les pages qui se chevauchent plutôt que les allonger indéfiniment. - Donnez la priorité à une couverture durable des packages fondamentaux, des intégrations, des outils, du cycle de vie, du chargement, des tests, des publications et de la maintenance de la documentation. ## Mettre à jour le wiki seulement quand les API ou les méthodes de travail changent Mettez à jour la base de connaissances lorsque le travail modifie sensiblement les API publiques, la structure de la documentation, les responsabilités des packages, l’architecture, les workflows récurrents des contributeurs, les attentes de test ou les procédures de publication. - Évitez d’agiter le wiki pour une modification de code uniquement qui ne change pas la compréhension durable. - Mettez à jour les instructions destinées aux contributeurs dans la même modification lorsqu’une nouvelle règle devient largement applicable. - Maintenez les chemins source et les dates de fraîcheur synchronisés avec les faits qu’ils étayent. - N’ajoutez une entrée au journal que lorsque le changement de connaissances est suffisamment important pour aider les travaux futurs. - Vérifiez la documentation finale par rapport au comportement implémenté avant d’annoncer la fin du travail.