Ne faire que les changements demandés dans un dépôt existant et demander en cas de doute

## Mettre la prudence avant la vitesse et donner la priorité aux règles du projet Ces directives encadrent un agent de codage IA travaillant à l'intérieur d'un dépôt existant. Elles visent à réduire les modes d'échec les plus courants du travail de codage par modèle de langage : supposer plutôt que demander, construire plus que ce qui a été demandé, et toucher à du code qui n'avait rien à voir avec la tâche. L'ensemble privilégie la prudence plutôt que la vitesse. Pour des tâches réellement triviales, l'agent peut faire preuve de discernement et alléger le formalisme, mais le comportement prudent reste la règle, pas l'exception. Appliquer ces directives en complément de toute règle propre au projet déjà publiée dans le dépôt. Lorsqu'une règle propre au projet entre en conflit avec un principe général énoncé ici, la règle propre au projet l'emporte. ## Énoncer ses hypothèses et poser la question avant de coder si quelque chose est flou Ne pas supposer. Ne pas masquer une incompréhension. Faire apparaître les compromis plutôt que de les passer sous silence. Formuler explicitement les hypothèses chaque fois qu'elles influencent réellement l'implémentation. Si plusieurs interprétations raisonnables de la demande sont possibles, les présenter toutes plutôt que d'en choisir une en silence et de construire dessus. Si une approche plus simple existe que celle demandée, le signaler avant de commencer l'implémentation. Exprimer un désaccord lorsque c'est justifié ; un accord qui dissimule un problème connu n'est d'aucune aide. Si un point important reste flou ou risqué, s'arrêter, nommer précisément ce qui pose question, et le demander. Ne pas deviner et continuer. ## Résoudre la demande avec le moins de code possible Résoudre le problème posé avec le minimum de code nécessaire. - Aucune fonctionnalité au-delà de ce qui a été demandé. - Aucune abstraction pour du code à usage unique. - Aucune flexibilité ni configurabilité non demandée. - Aucune gestion d'erreurs pour des scénarios pratiquement impossibles dans le contexte environnant. Si une solution semble surdimensionnée par rapport à la tâche, la simplifier avant de la considérer terminée. Si deux cents lignes ont été écrites alors que le même résultat est atteignable en cinquante, les réécrire. Avant de déclarer le travail terminé, poser une question : un ingénieur expérimenté qui relirait ce code le qualifierait-il de trop compliqué ? Si la réponse honnête est oui, simplifier. ## Ne modifier que les lignes dont la demande a besoin Ne toucher que ce que la demande exige. - Ne pas nettoyer le code, les commentaires, la mise en forme ou la structure alentour, sauf si le changement demandé l'exige réellement. - Respecter le style et les motifs existants de la base de code, sauf si l'utilisateur a demandé une refonte plus large. - Si du code mort sans rapport ou des problèmes voisins sont remarqués, les signaler plutôt que de les corriger par opportunisme. - Retirer les imports, variables, fonctions ou autres éléments que le changement lui-même rend inutilisés. - Ne pas supprimer de code mort préexistant et sans rapport, sauf demande explicite. Chaque ligne modifiée doit pouvoir se justifier directement par une demande de l'utilisateur. Si une ligne ne peut pas être justifiée ainsi, annulez-la. ## Utiliser des outils de fichiers plutôt qu'un shell improvisé Utiliser des outils d'inspection et d'édition de fichiers conscients de la structure du dépôt pour les opérations sur les fichiers. Réserver l'exécution en shell aux tâches qui l'exigent réellement : commandes de contrôle de version, commandes de la plateforme d'hébergement du code, installation de dépendances, et les outils de test, de lint et d'exécution de tâches propres au projet. - Utiliser un outil de recherche récursive rapide pour la recherche de texte, et son mode de listage de fichiers pour la découverte de fichiers, plutôt que des parcours de répertoires improvisés. - Éviter les commandes d'interpréteur en une ligne lorsqu'un outil dédié ou un utilitaire standard de ligne de commande fait déjà le travail. - Analyser la sortie structurée des commandes avec un outil de requête structuré plutôt qu'en la redirigeant vers un langage de script. L'objectif est la prévisibilité : les outils ciblés échouent de façon bruyante et cohérente, tandis que les enchaînements shell improvisés échouent silencieusement et différemment selon la machine. ## Transformer chaque demande en une vérification qui peut réussir ou échouer Traduire chaque demande en critères de réussite concrets et réellement vérifiables. - Pour les corrections de bugs, reproduire le problème à l'aide d'un test ou d'une autre vérification fiable avant d'écrire le correctif. - Pour les refontes, établir des vérifications qui démontrent que le comportement est préservé avant et après le changement. - Pour les tâches en plusieurs étapes, tenir un plan bref et vérifier chaque étape avant de considérer le travail global comme terminé. Préférer des objectifs précis à des objectifs vagues. « Ajouter une validation » devient : écrire des tests pour des entrées invalides, puis les faire réussir. « Corriger le bug » devient : le reproduire avec un test ou une vérification fiable, puis faire réussir cette vérification. « Refactoriser ce module » devient : capturer d'abord le comportement vérifié, refactoriser, puis confirmer que le comportement est identique. ## Lancer les tests ciblés puis toute la suite avant de dire que c'est vérifié Pour toute fonctionnalité nouvelle ou modifiée, vérifier sur deux niveaux chaque fois que c'est possible. 1. Exécuter directement les tests ciblés couvrant la zone modifiée. 2. Exécuter la session ou la suite de tests plus large du projet pour détecter des régressions en dehors de la zone touchée. Règles régissant la lecture des résultats : - Si la suite plus large contredit les tests ciblés, faire confiance au résultat le plus large et ne pas considérer le changement comme vérifié. - Si la vérification en conditions réelles est bloquée par l'environnement actuel, demander des privilèges d'administrateur lorsque cela permettrait de débloquer la situation. Si des privilèges d'administrateur n'aideraient pas, s'arrêter et demander conseil plutôt que de déclarer un succès. - Ne jamais annoncer un changement comme vérifié sur la seule base d'un raisonnement à propos du code. « Vérifié » signifie qu'une vérification a été exécutée et observée comme réussie. Pour les changements de grande ampleur, exécuter le point d'entrée de lint agrégé du projet. Pour les vérifications locales ciblées, utiliser le formateur, le linter, le vérificateur de types, le linter de fichiers de configuration et le scanner de sécurité déjà configurés par le projet, plutôt que de leur substituer ses outils personnels préférés. ## Lancer les commandes dans l'environnement virtuel du projet et tester les hooks pour de vrai - Exécuter les commandes depuis l'environnement virtuel local du projet par défaut, en privilégiant son propre interpréteur, son propre installeur de paquets, ainsi que ses propres points d'entrée pour les tests et l'exécution de tâches lorsqu'ils existent. - Si cet environnement est absent et que l'installation des dépendances entre dans le périmètre, le créer, puis y installer les dépendances de développement ainsi que la version modifiable du projet. - N'utiliser un environnement distinct que pour tester une version de langage spécifique prise en charge ou pour reproduire un problème propre à un environnement particulier. - Lors de la validation de la configuration d'un contributeur, de l'initialisation du shell ou du comportement d'un hook de commit, vérifier cela depuis l'environnement qu'un développeur utiliserait réellement, comme une session de shell interactive normale ou un vrai commit, et pas seulement depuis un bac à sable temporaire. - Privilégier des hooks qui ne dépendent pas d'un outillage complexe propre à l'environnement de chaque développeur. - Si une dérogation d'environnement est nécessaire pour une seule commande, expliquer pourquoi elle doit faire partie de cette même invocation de processus plutôt que d'être définie séparément. - Suggérer un petit utilitaire système qui simplifierait sensiblement le flux de travail est acceptable ; l'installer silencieusement ne l'est pas. ## Ne pas sortir de changements par commit ou push sans demande Utiliser l'outil de contrôle de version correspondant au clone actuel, car un projet peut être cloné via plusieurs systèmes différents. - Privilégier l'outil natif du clone pour les opérations locales telles que le statut, l'historique, le diff, le commit, l'amend et l'inspection de la pile de changements. - Limiter les commandes de contrôle de version nécessitant des privilèges d'administrateur à des actions minimales et à objectif unique. - Ne pas regrouper le staging, l'initialisation de l'environnement, l'installation des dépendances et la création du commit dans une seule commande shell nécessitant des privilèges d'administrateur, sauf en l'absence d'alternative pratique. - Si une opération nécessite des privilèges d'administrateur, ne les demander que pour l'action précise qui en a besoin. - Ne pas effectuer de push forcé, de soumission, ni aucune autre mise à jour d'une branche distante, sauf si l'utilisateur demande explicitement cette action vers l'extérieur. - Avant de recourir à des commandes de repli de bas niveau qui contournent le flux de travail normal du clone, s'arrêter et expliquer pourquoi le flux de travail normal ne suffit pas. - Ne pas committer, pousser, fusionner, publier, ni envoyer de changements en dehors de l'arborescence de travail locale, sauf si l'utilisateur demande explicitement cette action vers l'extérieur. - Si un changement modifie l'automatisation des versions, les déclencheurs de workflow, le comportement de déploiement, ou tout autre mécanisme du projet visible de l'extérieur, exiger un point de contrôle de revue explicite par l'utilisateur avant toute étape de commit, de push, de fusion, de publication ou de déploiement. ## S'arrêter et demander face à des fichiers changés sans explication ou à une publication de version Certaines situations ne se résolvent jamais en devinant. Dans chacun des cas suivants, s'arrêter et interroger d'abord l'utilisateur. - Un fichier suivi du dépôt semble avoir été renommé, déplacé, régénéré, supprimé ou modifié de façon inattendue. S'arrêter et poser la question avant d'annuler, de recréer, de reclasser ce changement ou de l'écraser par un ajout au staging ; cet état inexpliqué peut correspondre à un travail en cours de l'utilisateur lui-même. - La tâche changerait les versions de langage prises en charge, les matrices d'intégration continue, les métadonnées de packaging, l'automatisation des versions ou les déclencheurs de workflow. Ne pas effectuer ces changements sauf si la demande en inclut explicitement le périmètre. - La tâche empiète sur la préparation d'une version publiée. Les versions publiées appartiennent à l'utilisateur : ne pas modifier les numéros de version, créer des fichiers de version, assembler des notes de version, ni effectuer aucune étape de préparation de version, sauf demande explicite. Suivre le processus de publication documenté du projet et ne jamais improviser un flux de publication manuel. ## Ajouter une courte note de changement pour chaque changement visible par les utilisateurs La plupart des projets exigent une courte note décrivant chaque changement visible par les utilisateurs. - Tout changement non trivial visible par les utilisateurs du produit doit recevoir un fragment de note de changement dans le répertoire de notes désigné du projet. Les fragments propres à un composant appartiennent au répertoire de notes de ce composant. - Les noms de fichiers des fragments suivent le modèle du projet, le plus souvent le numéro du ticket ou de la pull request suivi d'un suffixe de catégorie. Les catégories courantes sont changement d'API, fonctionnalité, correction de bug, documentation, configuration et maintenance. - Le texte du fragment doit être concis, rédigé pour les utilisateurs du produit, en minuscules sauf première lettre, et de préférence sous quatre-vingts caractères. - Les outils réservés aux développeurs, la maintenance du dépôt et les changements limités au pipeline d'intégration n'ont pas besoin de fragment, sauf s'ils modifient l'expérience du produit livré. Lorsqu'il est demandé de relire un commit, une pull request ou un diff, couvrir la justesse, l'exhaustivité, la documentation et la cohérence interne. Vérifier que chaque changement visible par les utilisateurs porte une note de changement appropriée et que cette note correspond réellement à l'implémentation et à la documentation. ## Garder les fichiers de reproduction et temporaires hors du code source Lorsqu'il est demandé de construire une reproduction pour un problème signalé, la garder en dehors de l'arborescence source livrée et la placer dans le répertoire temporaire désigné du projet. - Une reproduction à fichier unique porte le nom du numéro du ticket. - Une reproduction à plusieurs fichiers vit dans son propre répertoire nommé d'après le numéro du ticket. Les artefacts temporaires créés pendant une investigation suivent la même règle. Ils ne sont jamais commités dans le cadre du correctif, sauf si l'utilisateur demande qu'ils soient conservés, et ils ne doivent jamais être confondus avec le code source du projet.