Amener un agent de codage IA à livrer du code sans avertissement et des comptes rendus honnêtes dans un dépôt au build strict

## Compiler seulement le module modifié pendant l'itération et tout valider avant le push Utilisez le wrapper de build versionné dans le dépôt plutôt qu'une chaîne d'outils installée globalement, afin que chaque contributeur et chaque agent compile de manière identique. Pour itérer rapidement, compilez et testez uniquement le module que vous avez modifié plutôt que l'ensemble du build multi-module ; il existe généralement un profil « rapide » qui saute les contrôles d'analyse statique, ainsi qu'une option qui saute les tests. Ces raccourcis sont réservés aux boucles de développement locales. Avant de committer, vous devez exécuter une compilation complète du module concerné avec les contrôles activés et confirmer l'absence totale d'avertissements — ne committez jamais en vous appuyant sur un build où les contrôles ont été sautés. Avant de pousser, exécutez l'étape de validation du projet, qui est sensible au diff : elle classe la modification (documentation seule, module unique, ou changement de configuration racine) et ne compile que les modules concernés ainsi que leur fermeture de dépendances, tandis qu'une modification de la configuration de build racine force une compilation complète. La validation laisse une marque temporaire que le hook de push vérifie. Annulez les exécutions de pipeline devenues obsolètes sur votre branche avant de pousser, afin de ne pas gaspiller les runners partagés. ## Ne jamais contourner les hooks Git et écrire des messages de commit courts sans signature d'IA Activez le chemin des hooks du dépôt au début de chaque session de travail ; les sessions peuvent être archivées puis reprises, ce n'est donc pas une configuration à faire une seule fois. Ne contournez jamais les hooks — ni option de saut de vérification, ni contournement de la signature. Les hooks imposent les en-têtes de licence, l'absence d'imports inutilisés ou dupliqués, et le format des messages de commit. Rédigez les sujets de commit au format conventionnel type(scope): description, en utilisant des types tels que feat, fix, docs, refactor, test et chore. Limitez chaque message à deux lignes non vides au maximum, la première ligne comptant moins d'environ 100 caractères. N'ajoutez aucune ligne de fin — ni mention de co-auteur, ni ligne de validation, et surtout aucune signature indiquant une paternité ou une génération par IA, quelle qu'elle soit ; le hook de message de commit les rejette. Les corrections de bugs vont directement sur la branche de développement principale ; les nouvelles fonctionnalités utilisent des branches dédiées. ## Suivre le style du code environnant et traiter chaque avertissement comme une erreur Respectez le style du code environnant et effectuez le plus petit changement raisonnable pour atteindre le résultat visé. Chaque fichier source doit porter l'en-tête de licence requis. Préférez la composition à l'héritage ; utilisez une construction try-with-resources pour chaque ressource fermable ; retournez un wrapper optionnel plutôt que null depuis les API publiques ; n'utilisez l'inférence de type locale que lorsque le type est évident d'après le contexte ; préférez les expressions switch et le filtrage par motif aux longues chaînes if/else ; utilisez des types scellés et des porteurs record immuables lorsque cela convient ; paramétrez toujours les génériques ; annotez les méthodes redéfinies ; construisez les chaînes de caractères avec un builder à l'intérieur des boucles ; et construisez les collections non modifiables avec les méthodes utilitaires standard. Traitez tout avertissement du compilateur, de dépréciation ou d'analyse statique comme une erreur. Le build s'exécute avec tous les contrôles de lint activés et échoue en cas d'imports inutilisés ou dupliqués ; zéro avertissement est donc requis pour livrer. N'introduisez pas de nouvelles annotations de suppression d'avertissement sans un commentaire justifiant pourquoi elle est inévitable, et ne supprimez jamais un commentaire de code sauf si vous pouvez prouver qu'il est activement faux. ## Seul le créateur d'une ressource la ferme, et les limites de capacité ne sont jamais ignorées Les invariants suivants bloquent la mise en production quelle que soit l'ampleur de la fonctionnalité ; en violer un bloque la release, même pour un changement minime. **Propriété des ressources** — Seul le créateur d'une ressource peut la libérer, la fermer ou l'arrêter. Suivez la propriété de manière explicite, et lorsque vous acceptez un exécuteur, un pool ou une connexion fourni de l'extérieur, encapsulez-le pour que les appels de cycle de vie ne puissent pas détruire quelque chose que vous n'avez pas créé. Chaque routine de démarrage a besoin d'une routine d'arrêt symétrique qui annule chaque enregistrement — listeners, handlers, hooks — et chaque buffer doit être libéré sur tous les chemins terminaux et d'erreur. **Exhaustivité des chemins terminaux** — Chaque chemin de sortie (succès, échec, annulation, timeout, rejet) doit laisser le système dans un état terminé : résoudre les futures, réinitialiser les indicateurs, libérer les buffers. Rendez la fermeture idempotente avec un motif compare-and-set ou close-once. Si une garde vérifie un compteur, un chemin doit réellement incrémenter ce compteur. **Contre-pression** — N'ignorez jamais les signaux de rejet ou de capacité. Vérifiez la valeur de retour d'une insertion bornée, gérez les exécutions rejetées et gérez les écritures partielles. Chaque cache et chaque buffer a besoin d'une limite de taille ou d'une politique d'éviction ; une structure non bornée alimentée par une entrée externe constitue un vecteur de déni de service. ## Valider les entrées à chaque frontière et n'annoncer que ce qui tourne vraiment Ces invariants bloquent également la mise en production quelle que soit l'ampleur de la fonctionnalité. **Sécurité aux frontières** — À chaque frontière (réseau, système de fichiers, shell, URL, HTTP), validez et encodez avant d'interpréter. Ne décodez du texte qu'à partir de messages complets et délimités, jamais à partir de fragments bruts de transport. Normalisez et validez les chemins du système de fichiers — résolvez, normalisez, puis vérifiez que le résultat reste sous la racine prévue, en rejetant les segments de répertoire parent, les séparateurs et les segments vides. Utilisez des tableaux d'arguments pour les appels shell, encodez en URL les parties dynamiques de chemin et de requête, comparez les types de contenu sans tenir compte de la casse, et renvoyez une erreur client plutôt qu'une erreur serveur pour une entrée malformée en interceptant les échecs d'analyse à la frontière. **Vérité d'exécution** — N'annoncez et ne signalez que l'état d'exécution confirmé, jamais une simple intention de configuration ou une simple présence dans le classpath. Les indicateurs de capacité et les points de découverte doivent refléter ce qui est réellement en cours d'exécution, et l'annonce d'une fonctionnalité doit être supprimée en cas d'échec au démarrage. **Sécurité** — Toute surface mutante ou d'administration exige une authentification et une autorisation explicites, avec refus par défaut. La vérification d'intégrité doit échouer de façon fermée (fail closed) ; tout mode d'échec ouvert (fail open) doit être explicite et non activé par défaut. Ne livrez jamais de valeurs par défaut non sécurisées sur les chemins de production — verrouillez-les derrière une activation explicite accompagnée d'un avertissement au démarrage — et les exemples ne doivent pas régresser sur ce point. **Parité des modes** — Si une fonctionnalité existe dans plusieurs modes d'invocation (synchrone, asynchrone, streaming), la sémantique doit être identique : gestion des erreurs, événements de cycle de vie, observabilité et comportement de complétion. Documentez et testez toute différence intentionnelle, et lorsque vous ajoutez une fonctionnalité à un chemin, vérifiez-la sur tous les chemins. ## Ajouter un test de régression aux bugs graves et interdire les tests vides Chaque correction de bug à sévérité élevée doit être livrée avec un test de non-régression qui reproduit le scénario en échec. Aucun test factice ou sans effet n'est autorisé dans les pistes CI obligatoires — un test qui se contente d'affirmer une évidence triviale est interdit, et chaque test doit vérifier précisément le comportement qu'il prétend tester. Les tests de bout en bout doivent vérifier la fonctionnalité testée, pas seulement le fait qu'un serveur a démarré. Si vous devez mettre en quarantaine un test instable, il lui faut un responsable, une date d'expiration et un ticket de suivi, et il doit continuer à s'exécuter dans une piste planifiée. Les filtres de chemin des workflows doivent inclure chaque script et chaque emplacement de configuration affectant le comportement de la zone modifiée, sinon la CI ignorera silencieusement le code même qui a été modifié. ## Faire appeler la vraie API par les exemples au lieu de la simuler Les applications d'exemple sont la première chose que voient les utilisateurs ; elles doivent donc être de qualité production, et non de simples ébauches. Utilisez réellement l'intégration que vous prétendez démontrer : si un exemple porte le nom d'une capacité réelle, il doit appeler cette API réelle, et non la simuler avec un substitut en mémoire. Si vous ne parvenez pas à faire fonctionner l'intégration réelle, dites-le et demandez de l'aide plutôt que de livrer un simulacre déguisé — des commentaires du type « dans une vraie application, vous appelleriez ceci » sont un signal d'alarme indiquant que l'exemple n'est pas la vraie application. Avant d'écrire du code d'intégration avec une bibliothèque tierce, lisez son API réelle — inspectez les artefacts de la dépendance et lisez les signatures publiques — et n'inventez jamais d'appels de méthode. Préférez l'auto-configuration fournie par la bibliothèque au câblage manuel. Chaque exemple doit compiler et être livré avec un court README expliquant ce qu'il fait, comment l'exécuter, et ce que montre le code essentiel. Ne créez pas un exemple par variante de backend lorsqu'une seule dépendance interchangeable est précisément l'objet de l'abstraction. ## Vérifier chaque affirmation dans le code ou l'historique Git avant de l'écrire Chaque affirmation factuelle dans la documentation, les entrées de changelog, les messages de commit et les textes destinés aux utilisateurs doit correspondre à quelque chose qui existe réellement dans le code ou dans l'historique git. N'inventez ni fonctionnalités, ni noms de méthodes, ni ensembles de capacités, ni chiffres de métriques, ni commits de correction ; chaque invention coûte de la crédibilité et doit ensuite être traquée puis annulée. Toute affirmation numérique exige une source — vérifiez un chiffre par rapport au code réel avant de l'écrire. Les puces « corrigé » et « ajouté » du changelog doivent correspondre à de vrais commits : cherchez le changement dans le journal et conservez le hash du commit dans votre brouillon avant de le publier ; si vous ne trouvez pas le commit, c'est que la correction n'a pas eu lieu. Les affirmations sur la surface d'API exigent de lire d'abord le code source réel (listes de champs, noms de méthodes). Affirmer qu'une chose est livrée, câblée ou intégrée exige un véritable consommateur en production sur un chemin atteint par une action utilisateur, et non simplement une interface fournisseur de service ou une implémentation de référence. Lorsqu'un fait ne peut pas être vérifié, retirez-le ou marquez-le explicitement comme non vérifié et demandez avant de publier. Si vous vous surprenez à inventer, arrêtez-vous, ne committez pas, signalez la fausse affirmation par rapport à la vérité terrain, et corrigez chaque occurrence. ## Ne pas se cacher derrière des règles contradictoires ni déclarer la tâche finie en cours de route Au-delà de l'honnêteté factuelle, évitez la malhonnêteté comportementale — des formulations où chaque phrase prise isolément est défendable, mais où l'ensemble induit en erreur. N'inventez pas de conflit entre deux règles pour justifier le chemin le plus facile ; lorsque des règles semblent se contredire, c'est presque toujours celle qui exige le travail le plus difficile et le plus sûr qui l'emporte. Ne choisissez pas sélectivement quelle directive citer alors qu'une autre la contredit ; réconciliez-les ouvertement. Ne signalez pas un statut que les règles demandent de corriger silencieusement — si un pipeline partagé est cassé, corrigez-le et annoncez la réussite plutôt que de raconter la panne. « C'était déjà cassé » ou « ce n'est pas ma régression » est une description, pas une excuse : la responsabilité des branches partagées se transmet à chaque changement. Ne demandez pas la permission pour une action déjà exigée par les règles — agir vaut mieux que demander, alors faites simplement le travail requis et continuez sur les points ouverts jusqu'à ce qu'on vous redirige. Ne déclarez pas victoire en cours de tâche ; le signal honnête liste ce qui n'est pas encore fait autant que ce qui l'est. Lorsque la concision entre en conflit avec une règle de correction ou de sécurité, c'est la règle de sécurité qui l'emporte : mieux vaut être verbeux mais correct que concis mais dangereux. Lorsque vous repérez l'un de ces schémas, nommez-le, effectuez le travail réellement exigé par la règle, et rappelez-vous que s'excuser ne remplace pas le travail. ## Ranger décisions et plans dans la base de connaissances partagée, pas seulement dans le chat Considérez une base de connaissances partagée comme le foyer durable des résultats structurés, car une discussion en chat n'est pas durable. Consultez-la d'abord pour connaître les décisions, conceptions et contexte antérieurs avant de commencer un travail structuré, et écrivez-y les résultats durables au lieu de les laisser uniquement dans une conversation. Orientez selon le type de document : les décisions d'architecture et les fiches de conception, les plans par phases, les runbooks et procédures d'astreinte, ainsi que les audits, analyses et passations de relais ont chacun une destination désignée ; les docs de référence sont livrés directement avec le code, et les spécifications propres à un répertoire vivent dans le README de ce répertoire. Gardez les identifiants privés ou locaux — pseudonymes personnels, noms de jeu de rôle, chemins spécifiques à une machine — hors de tout artefact commité. Utilisez des noms génériques neutres dans les tests et les exemples, et un identifiant réel uniquement lorsqu'il désigne véritablement un compte public. Lorsque le stockage durable n'est pas disponible, repliez-vous sur un lien partageable et notez-le, afin qu'une session ultérieure puisse le classer au bon endroit.