Faire respecter à un agent de codage IA les règles de branches et de commits sans casser les releases

## Garder un seul fichier d'instructions de l'agent et vérifier quelle partie du dépôt modifier - Conservez un seul fichier d'instructions canonique pour l'agent. Quand un harnais attend un nom de fichier différent, pointez-le vers le fichier canonique via un lien symbolique plutôt que de dupliquer le contenu : un second fichier réel finit par diverger avec le temps et peut casser les validateurs qui traitent le chemin alternatif comme un type d'artefact différent. Préservez le lien symbolique ; ne le laissez pas être matérialisé en un fichier normal. - Une même modification peut toucher plusieurs surfaces à la fois — contenu produit livré, métadonnées de catalogue ou de configuration, code de build ou de CLI. Ne présumez pas qu'un changement est « juste du code » ou « juste de la documentation » sans vérifier quelle surface possède chaque fichier modifié, et modifiez la surface propriétaire du comportement plutôt qu'une surface adjacente. - Considérez les fichiers d'instructions du dépôt lui-même comme du contexte de rédaction pour ce dépôt. Toute règle devant affecter un artefact livré à l'exécution doit se trouver dans cet artefact, pas dans le fichier d'instructions du dépôt, car les utilisateurs finaux exécutent l'artefact avec leurs propres instructions. ## Travailler sur une branche de fonctionnalité et fusionner uniquement par pull request - Créez une branche de fonctionnalité pour tout changement non trivial. Si vous êtes déjà sur la bonne branche pour la tâche, continuez à l'utiliser ; ne créez pas de branches ou d'arbres de travail supplémentaires sans demande explicite. - Faites passer tout changement vers la branche par défaut par une pull request. Les push ou merges directs contournent la validation et les contrôles de release et provoquent une dérive de version nécessitant ensuite une récupération en plusieurs étapes ; appuyez-vous sur la protection de branche pour l'imposer plutôt que de la contourner. - Laissez les releases à l'automatisation de release. Ne modifiez pas manuellement les numéros de version gérés par la release et ne rédigez pas manuellement les notes de release dans le travail courant, et utilisez des titres de commit conventionnels pour que l'automatisation puisse classer l'intention du changement. ## Lancer tous les tests et séparer les tests automatiques des évaluations - Exécutez la suite de tests complète après tout changement affectant l'analyse syntaxique, la conversion, la sortie ou les conventions mécaniques. La suite locale est la même que celle exécutée par la CI ; il n'existe pas de voie locale distincte que vous pourriez ignorer. - Répartissez les vérifications selon leur nature. Les invariants déterministes — schéma et frontmatter, sécurité des chemins, forme de la sortie, contrats « greppables » — vivent dans la suite automatisée et doivent passer en CI. Le comportement non déterministe, comme le jugement et la retenue, est validé par évaluation, pas simulé par un test de chaîne fragile. - Quand un relecteur trouve un invariant « greppable » que la suite a manqué, préférez resserrer une garde existante plutôt qu'ajouter une nouvelle suite, et fixez la plus petite unité falsifiable — un token, un chemin ou une fixture qui aurait échoué sur le changement régressif — plutôt que de figer tout le contenu d'un fichier. ## Choisir où vont les fichiers temporaires et garder plans et documents dans le dépôt - Envoyez par défaut les fichiers temporaires jetables vers le dossier temp du système : un répertoire temporaire par exécution que l'OS récupère, pour les fichiers consommés une fois puis abandonnés. - Pour les fichiers temporaires devant survivre entre plusieurs invocations, utilisez un préfixe stable appartenant à l'utilisateur courant plutôt qu'un répertoire temp aléatoire, afin que les exécutions ultérieures puissent le retrouver. Créez la racine en privé (propriétaire uniquement), rejetez-la si c'est un lien symbolique ou si elle appartient à un autre utilisateur, et gardez un répertoire par exécution sauf si des exécutions ultérieures énumèrent intentionnellement des artefacts finaux voisins. - Ne liez l'espace temporaire au dépôt de travail que lorsque l'artefact est véritablement inséparable de ce dépôt ou de cette branche, qu'il est destiné à être géré directement par l'utilisateur, ou qu'un chemin relatif au dépôt est lui-même essentiel à la sortie. - Les sorties durables — plans, spécifications, documentation, livrables finaux — ont leur place dans un emplacement suivi par le dépôt, jamais dans l'un des deux niveaux temporaires. ## N'utiliser que l'ASCII dans les noms et séparer les tableaux Markdown par des barres verticales - Gardez les identifiants — noms de fichiers, de commandes et d'agents — strictement en ASCII, car les convertisseurs et les motifs regex en dépendent. - Écrivez les tableaux Markdown avec des lignes délimitées par des barres verticales, jamais avec des caractères de dessin de boîte. - L'Unicode est acceptable dans le texte courant ; préférez les flèches ASCII (-> et <-) dans les blocs de code et les exemples de terminal afin que les commandes copiées restent portables. ## Choisir le préfixe de commit fix ou feature selon ce que fait le changement - Choisissez le préfixe conventionnel selon ce que fait le changement, pas selon le type de fichier. Un contenu situé dans un répertoire docs ou skills peut quand même être du code produit ; réservez le préfixe docs aux fichiers dont le seul but est la documentation. - Quand les préfixes fix et feature semblent tous deux convenir, privilégiez fix par défaut : corriger un comportement cassé ou manquant est un fix même si cela passe par l'ajout de code. Réservez le préfixe feature à une capacité que l'utilisateur ne pouvait pas accomplir auparavant, sans que rien ne soit cassé. Heuristique : si un test de régression écrit aujourd'hui aurait échoué avant le changement, il s'agit d'un fix. - Indiquez le périmètre de composant utile le plus étroit — le nom de la compétence, du module ou de la zone — et ne portez jamais un commit sur l'ensemble du projet. N'ajoutez jamais de marqueur de changement cassant sans confirmation explicite de l'utilisateur, car cela déclenche une montée de version majeure automatique que l'utilisateur peut ne pas vouloir. ## Utiliser des chemins relatifs pour que chaque unité livrée marche dans tout outil d'IA - Gardez chaque unité livrable autonome : ne référencez que des fichiers situés dans sa propre arborescence, avec des chemins relatifs. Ne traversez jamais vers une unité voisine et ne codez jamais en dur un chemin d'installation absolu — les emplacements d'installation sont versionnés et imprévisibles, et le packaging copie chaque unité de façon isolée. Dupliquez un fichier partagé dans chaque unité plutôt que de dépendre d'autres répertoires. - Ne comptez pas sur des variables spécifiques à l'hôte — substitutions skill-directory, session-id ou plugin-root — sans repli fonctionnant lorsque la valeur est vide ou non résolue ; plusieurs ne sont renseignées que sur un seul harnais et restent silencieusement vides ailleurs. - Pour une commande shell exécutée qui lance un script intégré, rendez la résolution déterministe : définissez un répertoire de base absolu directement dans la même commande (l'état du shell ne persiste pas entre les appels) et référencez le script à partir de celui-ci, plutôt qu'un chemin relatif nu qui se résout par rapport au répertoire de projet de l'utilisateur au lieu de celui de l'unité. ## N'écrire que des règles vérifiables dans les instructions et trier les retours de revue avant de modifier - N'acceptez une ligne que si elle énonce une contrainte falsifiable, contrecarre une tendance par défaut connue ou un raccourci observé, ou apporte une connaissance de domaine qui change une décision. Supprimez le langage vague sur l'effort ou la qualité tel que « soyez minutieux » ; remplacez-le par une règle observable ou abandonnez-le. N'ajoutez pas de justification motivationnelle à une directive qui se suffit déjà à elle-même. - Ne répétez une instruction qu'à un point de dérive démontré, où son emplacement change si elle se déclenche ou non, et protégez un doublon réellement nécessaire par un test de parité. - Traitez l'application des retours de relecture comme une révision substantielle : classez chaque point comme Changer, Vérifier ou Envisager, et n'éditez que les points Changer ; corrigez chacun au niveau qui le possède avec le mécanisme le plus petit possible ; puis relisez le bloc et supprimez le texte devenu redondant ou obsolète du fait du changement. La formulation du relecteur est une hypothèse sur la correction, pas une autorité sur celle-ci. ## Chercher les conventions du projet dans le contexte déjà chargé, sans nommer de fichiers d'instructions - Quand une unité doit découvrir une convention de projet — gestionnaire de tickets, format de commit, commande de lint, limites de périmètre — décrivez ce qu'il faut chercher dans le contexte déjà chargé de l'agent, pas quel fichier ouvrir. Sur le chemin de lecture, ne nommez pas les fichiers d'instructions cachés (dotfiles) : l'hôte injecte déjà le fichier d'instructions racine, son nom de fichier diffère selon le harnais, et demander à un agent d'ouvrir des fichiers d'instructions nommés est exactement la forme que les défenses anti prompt-injection signalent. - Ne nommez un fichier concret que lorsqu'une référence de contexte ne peut pas exprimer le besoin — écrire une convention dans une cible, ou lire un contenu qu'un sous-agent nouvellement créé n'hérite réellement pas. - Décrivez une capacité par catégorie (« le gestionnaire de tickets du projet, par exemple GitHub Issues, Linear ou Jira » et « quelle que soit l'interface qu'il expose »), et ne considérez jamais l'absence d'un binaire, d'une variable d'environnement ou d'un connecteur comme la preuve que la capacité est indisponible. ## Comparer le contenu, pas la version, pour savoir si la session a votre dernière modification - Après avoir modifié un contenu qu'une session de longue durée a chargé au démarrage, supposez que la session exécute toujours la copie d'avant modification. Les caches capturent l'état au moment du chargement, et les modifications au sein d'une release ne changent pas de numéro de version, donc une version correspondante prouve seulement que le cache provient de cette release, pas qu'il a capturé votre dernière modification. - Confirmez quelle copie est active en comparant le contenu du fichier chargé à votre copie de travail, pas en lisant la chaîne de version. Une correspondance identique signifie que la copie en cours d'exécution est à jour et fiable ; une différence signifie qu'il faut redémarrer ou utiliser un chemin de chargement frais avant de faire confiance à un test comportemental. - Les chemins de code mécaniques — scripts, analyseurs syntaxiques, tout ce que la suite de tests exerce — exécutent toujours la source actuelle. Seule la couche d'instructions et de texte chargée au démarrage porte ce risque d'obsolescence.