Faire lire le code à l'IA avant de modifier un grand dépôt et ne livrer qu'après revue

## Lire d'abord les règles générales, puis le guide du dossier où l'on travaille Réservez le document racine à la politique stricte et à l'orientation ; laissez les guides de portée spécifique porter le déroulé détaillé de chaque domaine. Avant de travailler dans une sous-arborescence, lisez le guide qui en a la charge. ### Un seul emplacement pour chaque type de règle La politique stricte, les frontières transversales et la répartition des responsabilités entre guides se trouvent à la racine. Les procédures propres à une tâche vivent dans le guide de portée spécifique, à côté du code qu'elles régissent. Ne reformulez pas un même déroulé à deux endroits, où les copies risqueraient de diverger. ### Référencez le code comme le fait le dépôt Citez les fichiers par leur chemin relatif au dépôt, et non par un chemin absolu ou basé sur le répertoire personnel, afin qu'une référence signifie la même chose pour tout lecteur. ## Chercher une bibliothèque ou un outil existant avant de créer le sien Avant de proposer ou de construire un système, une fonctionnalité, un outil, une intégration ou une automatisation sur mesure, effectuez une vérification légère pour voir si une bibliothèque, un plugin ou une plateforme gratuite existante résout déjà le problème de façon suffisante. ### Privilégiez l'option éprouvée Lorsqu'une option existante convient, utilisez-la. Ne construisez du sur-mesure que lorsque les alternatives sont inadaptées, trop coûteuses, non maintenues, dangereuses, non conformes, ou lorsque l'utilisateur a explicitement demandé une solution sur mesure. ### Gardez cette vérification légère Il s'agit d'un simple filtre préalable, pas d'un travail de recherche approfondi. Ne recommandez pas de service payant sans que l'utilisateur ait approuvé la dépense. ## Relire en lisant les appelants, les appelés et les tests, pas seulement le diff Les corrections, le tri et les revues nécessitent un haut niveau de confiance fondé sur la lecture, et non une supposition à partir du changement visible. Une revue basée uniquement sur le diff est insuffisante. ### Lisez l'ensemble de la surface concernée avant de trancher Avant de dire que c'est bon, mauvais, la meilleure correction, ou suffisamment prouvé, lisez l'intégralité de la fonction ou du module modifié, ainsi que ses appelants, ses fonctions appelées, les implémentations similaires, les tests adjacents, la documentation de portée spécifique, et les contrats de tout ce dont il dépend. ### Construisez une petite carte des preuves Identifiez la surface modifiée, son point d'entrée, la frontière de responsabilité, au moins un appelant et un appelé, les surfaces similaires partageant le même invariant, les tests existants, et le comportement actuellement en production. Si une case manque, signalez le manque au lieu de conclure. ### En cas de contestation, lisez avant de défendre votre position Lorsqu'un verdict est remis en question, vérifiez d'abord le chemin manquant ; ne défendez pas la conclusion précédente avant d'avoir vérifié. ## Lire le code source des dépendances et tester les API externes en conditions réelles Lorsque le comportement dépend d'une bibliothèque ou d'un service externe, vérifiez sur l'élément réel, et non de mémoire, via un wrapper, un schéma généré, ou le rapport d'un autre agent. ### Lisez le code source de la dépendance elle-même Pour un comportement reposant sur une dépendance, lisez directement la source amont, la documentation ou les types, et citez ce que vous avez vérifié. La plupart des dépendances sont open source, il n'y a donc aucune excuse à deviner une valeur par défaut, une erreur ou un délai. ### Testez les services externes en conditions réelles Tout travail sur une API externe nécessite un test en conditions réelles ainsi qu'une preuve actuelle et citée ; n'affirmez jamais rien sur une API de mémoire. Vérifiez en conditions réelles chaque fois que possible, et n'affichez jamais de secret au cours du processus. ## Juger si une correction est la meilleure, pas seulement si elle marche Le verdict d'une revue doit déterminer si le changement constitue la meilleure correction, et non simplement une correction qui fonctionne. Comparez les frontières de responsabilité, les appelants, les surfaces similaires, les tests et le comportement actuel avant de conclure. ### Une correction partielle nécessite une preuve sur les surfaces similaires Une correction qui touche une surface sans toucher ses équivalents nécessite une preuve que ces derniers ne sont pas affectés, ou un suivi explicite qui les couvre. ### Ne présentez pas une question de goût comme un constat Ne soulevez pas de constat pour une simple préférence de politique du dépôt lorsque le code modifié respecte son guide de portée spécifique et ne présente aucun risque visible pour l'utilisateur, à l'exécution, en matière de sécurité, ou pour les mainteneurs. ## Lire la configuration d'une seule façon et migrer les anciennes clés au lieu de les perdre L'exécution ne lit que la forme canonique actuelle de la configuration et des données. Il n'existe aucune compatibilité silencieuse pour les clés anciennes ou mal formées. ### Supprimez l'ancien chemin Privilégiez un chemin canonique unique et supprimez l'ancien, sauf si un contrat explicite déjà livré ou un chemin de mise à niveau balisé est cité. Une refactorisation qui laisse subsister un second chemin a probablement échoué. ### Migrez, ne supprimez jamais en silence Si un changement invalide une configuration existante, ajoutez une migration correspondante dans l'étape dédiée de migration ou de réparation ; ne supprimez jamais une clé en silence, car une clé supprimée constitue un changement de comportement caché. ### Gardez la surface de configuration réduite La surface de configuration et d'environnement est soumise à des exigences élevées. Avant d'ajouter une option, prouvez que le comportement existant ne peut pas résoudre le besoin, et privilégiez la suppression ou la consolidation des options. Considérez les procédures d'installation documentées comme sensibles à la compatibilité : privilégiez les indicateurs additifs plutôt que de casser des extraits de code existants. ## Garder le code propre à un module dans ce module, pas dans le code partagé Le code partagé et le code central restent génériques ; le comportement propre à un responsable vit dans le module qui en a la charge. Ne franchissez une frontière que par une interface publique documentée, jamais en accédant directement aux éléments internes d'un autre module. ### Déplacez la responsabilité, ne l'enrobez pas La forme par défaut d'une correction est une refactorisation propre et bornée qui déplace la logique vers le bon responsable et supprime les abstractions obsolètes, les politiques dupliquées et les branches mortes, et non le correctif le plus petit possible. ### Correct, mais sans sur-ingénierie La justesse sur les entrées et états réels est obligatoire ; les couches et protections supplémentaires pour des entrées imaginaires sont des défauts, pas de la rigueur. Lorsque vous sacrifiez un cas limite improbable pour une réelle simplicité, nommez ce compromis afin qu'il soit une décision, et non un oubli. ## Garder l'état d'exécution dans le stockage du projet, pas dans des fichiers à part Conservez l'état d'exécution dans le magasin canonique du projet. Ne dispersez pas de fichiers annexes pour l'état, les caches, les files d'attente, les index ou les données temporaires que le magasin devrait posséder. ### Les migrations prennent en charge l'ancienne forme Les anciens magasins de fichiers et les formes retirées ne sont normalisés que dans le code de migration ou de réparation, avant l'exécution ; en régime stable, l'exécution ne lit jamais un emplacement de repli. ### Ne changez jamais seul une version de schéma Un changement de version de schéma que les anciens lecteurs ne peuvent pas tolérer nécessite d'abord une discussion explicite avec l'utilisateur et son accord ; ne l'avancez jamais de manière autonome. Un changement purement additif, que les anciennes versions tolèrent encore, ne justifie pas de changer la version. ## Réutiliser les infos déjà trouvées au lieu de les rechercher à chaque requête Un chemin critique doit transmettre les faits déjà résolus en amont, et non les redécouvrir à chaque requête. ### Résolvez une fois, réutilisez Transmettez les identifiants, les chemins résolus et les faits de capacité, et réutilisez l'objet préparé. Ne corrigez pas une découverte répétée au moment de la requête en dispersant des caches ; déplacez le fait canonique plus en amont et supprimez les recherches dupliquées. ### Pas de vérification de fraîcheur dans la boucle Les métadonnées stables pour le processus, telles que les installations, les manifestes et les chemins résolus, ne changent qu'au redémarrage ou lors d'un rechargement explicite ; les chemins critiques ne doivent donc pas revérifier leur fraîcheur en relisant ou en recalculant un hachage. Un cache local au processus n'est acceptable que s'il est géré par le cycle de vie et borné. ## Écrire du code court, lisible et strictement typé Gardez le typage strict activé et gardez le code honnête. L'objectif est un code réduit et clair, pas le diff le plus petit possible. ### Typez les frontières, fermez les branches Évitez le type dynamique fourre-tout ; privilégiez de vrais types et des adaptateurs restreints. Validez les entrées externes à l'aide d'un schéma. Structurez vos branches sur des unions discriminées ou des codes de résultat fermés plutôt que sur des chaînes de caractères libres ou des valeurs sentinelles, et rendez les états impossibles irreprésentables. ### Structurez pour la lecture Privilégiez les retours anticipés aux pyramides imbriquées, et découpez le travail en collecte, normalisation, décision et action. Gardez les points d'appel simples : les décisions complexes se prennent en amont, de sorte que les arguments restent des noms, des littéraux ou de simples lectures. ### Commentez ce qui n'est pas évident Un commentaire en ligne mérite sa place sur un invariant non évident, une contrainte d'ordre, une frontière de responsabilité, ou un couplage de nettoyage : une à trois lignes expliquant pourquoi la branche existe et ce qui casserait si elle était supprimée. Pas de narration de la syntaxe. ## Si un refactoring allonge le code, le réduire ou expliquer pourquoi Une refactorisation devrait supprimer à peu près autant de complexité locale qu'elle en ajoute. Un solde positif de lignes en production est un signal d'alerte à justifier, pas une norme à accepter. ### Vérifiez la taille avant de clore Avant de terminer une refactorisation non triviale, comparez la taille du changement ; si le code hors tests a grossi, réduisez-le ou expliquez clairement pourquoi moins de chemins coûtent désormais davantage de lignes. ### Faites en sorte que toute nouvelle surface se justifie Un nouvel utilitaire ou fichier doit immédiatement réduire les chemins d'appel, les concepts ou la logique répétée. N'en ajoutez pas pour une compatibilité ponctuelle, un renommage de champ, ou une résilience spéculative. Gardez les interfaces publiques restreintes et retournez la forme utile la plus petite possible. ## Tester le comportement plutôt que le texte, et isoler chaque test Les tests prouvent le comportement et protègent contre les régressions ; ce ne sont pas une case à cocher pour chaque branche interne. ### Testez le comportement, pas la formulation Privilégiez les tests de comportement à la recherche de chaînes de documentation ou de politique par grep, et placez les rappels destinés aux opérateurs dans la documentation plutôt que dans les assertions de test. Relisez les nouveaux tests avant de les intégrer et supprimez ceux à faible valeur, y compris les tests portant sur des chemins que vous venez de supprimer. ### Gardez les tests isolés et honnêtes Nettoyez les minuteurs, l'environnement, les variables globales, les mocks et l'état temporaire. Un mock doit exporter chaque liaison touchée par le code réel, y compris les types d'erreur utilisés dans les vérifications d'identité. Ne modifiez pas un fichier de référence ou de snapshot pour faire taire une vérification sans approbation. ### Testez sur une copie de l'état réel Lorsque des données réalistes comptent, copiez l'état dans un emplacement temporaire et testez la copie ; ne modifiez jamais directement l'état d'un service en production sans approbation explicite. ## Ne jamais exécuter de code non fiable en local et envoyer les builds lourds à l'exécuteur distant Classez le niveau de confiance de la source avant de décider du degré de validation nécessaire, et choisissez où s'exécute cette validation en fonction de cette même confiance. ### Ne faites jamais tourner de code non fiable en local Une source fiable peut exécuter localement quelques tests ciblés et des vérifications statiques peu coûteuses lorsque les dépendances sont prêtes. Le code non fiable ou provenant d'une contribution externe ne fait tourner localement aucun de ses propres scripts, tests, hooks ou configurations, quelle que soit l'ampleur de la validation ; utilisez à la place une exécution isolée et sans identifiants. ### Envoyez les tâches lourdes à l'exécuteur distant Les suites complètes, les builds, les vérifications de types, l'empaquetage et la validation multiplateforme sont confiés à un exécuteur distant, acquis paresseusement à la première commande lourde, réutilisé pour une seule session, puis libéré avant la passation. Si l'exécuteur distant est indisponible, le travail issu d'une source fiable peut se replier en local ; le travail non fiable ne le fait jamais. ### Conditionnez l'intégration à une revue récente Avant d'intégrer, effectuez une revue automatisée récente jusqu'à ce qu'il ne reste plus aucun constat exploitable ; ne vous contentez pas d'une intégration continue au vert, sauf si la portée est triviale ou que l'utilisateur y renonce explicitement. Si la validation est bloquée, précisez exactement ce qui manque et pourquoi. ## Ouvrir issues et pull requests selon le processus du projet et faire valider les releases Modifier une surface partagée est un acte social : suivez le processus de contribution du projet et obtenez une approbation pour chaque étape irréversible. ### Suivez le processus de revue et de fusion Lisez le guide de contribution, les modèles d'issue et de pull request, ainsi que le fichier des responsables du code, avant d'ouvrir quoi que ce soit. Ouvrez d'abord une issue pour les bugs, les fonctionnalités visibles par l'utilisateur, et les décisions d'architecture. Rédigez un véritable corps de pull request présentant le problème, l'impact et les preuves, et vérifiez l'état en conditions réelles via l'outil propre de la plateforme avant toute modification. ### Ne faites rien d'irréversible sans qu'on vous le demande N'étiquetez, ne renommez, ne rebasez, ni n'intégrez sans qu'on vous l'ait demandé. Présentez d'abord tout commentaire public comme un brouillon, sauf si l'utilisateur vous a explicitement demandé de le publier, et nommez chaque commentaire publié avec son lien. Terminez tout travail sur une issue ou une pull request en indiquant l'URL complète de l'élément. ### Commitez et créez des branches proprement Ne commitez que les fichiers prévus, avec des messages concis et regroupés, rebasez sur la branche principale la plus récente avant de pousser, et ne supprimez ni ne renommez jamais de fichiers inattendus. Gardez la documentation alignée sur le comportement au sein du même changement, et laissez le changelog de release au processus de release. ### Obtenez une approbation pour les releases et les secrets Les releases, les changements de version, et les modifications de dépendances ou de fichiers de verrouillage nécessitent une approbation explicite. Ne commitez jamais de véritables identifiants ni de configuration en production, et conservez les secrets dans le magasin désigné.