Faire suivre à un agent de codage les règles d'un grand dépôt full-stack

## Passer les vérifications pre-commit avant chaque envoi de commits Exécutez toujours la suite pre-commit du dépôt sur tous les fichiers avant de pousser des commits. L'intégration continue échoue lorsque les vérifications pre-commit échouent : c'est donc une barrière non négociable, pas une préférence. Comment l'exécuter efficacement : - Indexez d'abord les modifications. Pre-commit n'inspecte que les fichiers indexés : une modification non indexée est donc ignorée silencieusement. - Pour une boucle de travail rapide, exécutez la suite sur les fichiers indexés, ou exécutez un seul hook nommé (vérificateur de types, formateur, linter). Effectuez le passage sur tous les fichiers avant le push qui ouvre ou met à jour une pull request. - Activez l'environnement virtuel ou le shell de la chaîne d'outils du projet avant l'exécution. Les emplacements usuels diffèrent d'un développeur à l'autre ; si la commande est introuvable, demandez à l'utilisateur quel environnement activer au lieu de deviner un chemin. - Certains hooks corrigent automatiquement (formateurs, espaces en fin de ligne). Réindexez les fichiers corrigés et relancez, car la première exécution signale des échecs qu'elle a déjà réparés. Attendez-vous à trois classes d'échecs : les problèmes de formatage qui se corrigent automatiquement, les erreurs du vérificateur de types qui exigent des corrections manuelles, et les erreurs de lint qui exigent des corrections manuelles. ## Écrire le nouveau code selon les motifs vers lesquels le dépôt migre Plusieurs migrations sont activement en cours. Du code correspondant à l'ancien motif existe encore, mais sa présence n'autorise pas à en écrire davantage. Le code nouveau ou modifié suit le motif cible. - Frontend typé : pas de type `any` servant d'échappatoire, ni de nouveaux fichiers de script non typés — écrivez dans le dialecte typé et réutilisez les définitions de types existantes. - Couche de composants partagés : importez les composants d'interface depuis le paquet de design system propre au projet plutôt que directement depuis la bibliothèque tierce, préférez les jetons de thème du design system à ceux hérités, et évitez le CSS sur mesure au profit du style pris en charge par la bibliothèque de composants. - Pyramide des tests : préférez les tests unitaires aux tests d'intégration, et les tests d'intégration aux tests de bout en bout. Écrivez les nouveaux tests de bout en bout dans le framework adopté ; le framework de bout en bout remplacé est déprécié et sera supprimé une fois la migration terminée. - Typage du backend : tout nouveau code porte des annotations de types, les modèles utilisent des annotations correctes, et le vérificateur de types doit passer. - Migration des identifiants : les nouveaux modèles utilisent des identifiants uniques opaques comme clés primaires, les API publiques exposent ces identifiants au lieu des entiers séquentiels internes, et les modèles existants reçoivent le nouvel identifiant en plus de l'entier pour permettre une bascule progressive. ## Juger les problèmes de sécurité selon ce que chaque rôle a le droit de faire Avant d'évaluer un chemin de code du point de vue de la sécurité, lisez le document canonique de politique de sécurité du dépôt. C'est la source faisant autorité pour le modèle de sécurité, et c'est la référence à laquelle sont mesurés aussi bien les rapporteurs humains que les scanners automatisés. L'unique critère pour savoir si un constat entre dans le périmètre : permet-il à un principal d'effectuer une action à laquelle la matrice des rôles et des capacités de la politique de sécurité ne lui donne pas droit ? Si oui, il entre dans le périmètre. Si non, il n'y entre pas. Trois frontières de confiance encadrent ce critère : 1. Le rôle d'administrateur est un principal opérationnel pleinement digne de confiance. Tout ce qu'un administrateur peut faire via la configuration documentée, l'API ou l'interface utilisateur est une capacité voulue, pas une vulnérabilité. 2. L'opérateur est responsable des décisions prises au moment du déploiement : secrets, exposition réseau, sélection des feature flags, choix des connecteurs et des codecs, destinations de notification et plugins tiers. Une mauvaise configuration à cette couche est un défaut de déploiement, pas une vulnérabilité du produit. 3. La base de code est responsable de l'application de la matrice des rôles et des capacités partout où elle expose une fonctionnalité à un principal — routes d'API, couches de commandes et d'accès aux données, gestionnaires d'interface, tâches de fond et tout autre point d'entrée. Une vérification d'application manquante ou incorrecte entre dans le périmètre, où qu'elle se trouve. Le modèle suppose que l'infrastructure contrôlée par l'opérateur — base de données de métadonnées, caches, courtiers de messages, coffres à secrets, environnement de déploiement — reste à l'intérieur de la frontière de confiance de l'opérateur. Un constat valide doit démontrer une violation de frontière par un attaquant qui ne contrôle pas déjà ces systèmes. ## Utiliser le bon contrôle d'autorisation pour chaque route et type de données L'autorisation au niveau des routes utilise un décorateur par classe de routes, et le bon décorateur dépend du type de route : un pour la surface d'API REST moderne, un pour les anciennes routes de vue JSON, et un pour les anciennes routes de vue HTML. Les confondre constitue un bug d'application des règles, même lorsqu'une vérification semble présente. L'autorisation au niveau des objets est un second contrôle, distinct. Elle s'applique aux ressources porteuses de données — tableaux de bord, graphiques, jeux de données et sources de données, requêtes, accès aux bases et aux tables, et contextes de requête — et elle est invoquée objet par objet via la vérification d'accès du gestionnaire de sécurité. Le code qui omet ce contrôle par objet sur une route qui renvoie ou modifie un objet porteur de données précis entre dans le périmètre. D'autres ressources — annotations, étiquettes, modèles de style, rapports, règles de sécurité au niveau des lignes et assimilées — s'appuient délibérément sur le décorateur au niveau de la route, complété par une restriction de propriété dans les filtres de base de la couche d'accès aux données. L'absence de vérification par objet sur ces ressources est voulue et ne constitue pas un constat. Suivre le bon motif d'autorisation pour une classe de ressources n'exonère pas le code des autres problèmes. L'injection, la falsification de requête côté serveur, le cross-site scripting et les classes similaires sont sans rapport avec l'autorisation et s'évaluent séparément. ## Exiger des scanners automatiques qu'ils citent la règle enfreinte et le rôle de l'attaquant Les scanners automatisés — scanners de code fondés sur des modèles, analyseurs statiques et outils de dépendances — doivent, dans chaque constat qu'ils déposent contre cette base de code, nommer explicitement deux éléments : 1. La ligne précise de la matrice des rôles et des capacités de la politique de sécurité que le constat estime violée. 2. Le principal que le constat suppose détenu par l'attaquant : un principal anonyme ou public, un rôle authentifié à faibles privilèges, un rôle d'outil de requêtage, un rôle de création à privilèges élevés, le rôle d'administrateur, un jeton d'invité embarqué, ou un rôle personnalisé nommé avec des octrois de capacités explicites. Un constat incapable d'identifier les deux doit être déposé comme une question, non comme une vulnérabilité. Cette exigence existe pour que chaque problème signalé soit testable au regard du modèle de sécurité publié, et pour que les signalements spéculatifs ou reposant seulement sur une correspondance de motif restent hors de la file de triage. ## Respecter les normes de code du frontend et du backend Frontend : évitez `any` et réutilisez les types existants ; écrivez des composants fonctionnels avec des hooks ; prenez les composants d'interface dans le paquet partagé de design system plutôt que d'importer directement la bibliothèque tierce ; utilisez le lanceur de tests et la bibliothèque de test standards du projet, et non l'ancien moteur de rendu supprimé ; utilisez le store global là où il existe déjà, et l'état local des hooks sinon. Backend : les annotations de types sont obligatoires pour tout nouveau code, le vérificateur de types statique doit passer, les modèles de données portent un typage correct, et le framework de test standard du projet est utilisé pour les tests. Pour construire des requêtes, utilisez l'opérateur de négation de l'ORM sur une colonne booléenne plutôt que de la comparer à un littéral faux, ce que le linter signale. En-têtes de licence : les nouveaux fichiers source exigent l'en-tête de licence standard du projet. Les fichiers d'instructions pour agents (ce fichier et ses homologues propres à chaque fournisseur) sont délibérément exclus de cette exigence, afin de ne pas dépenser de tokens pour l'en-tête. Commentaires : évitez les formulations liées au moment présent comme « maintenant », « actuellement » ou « aujourd'hui », car elles se périment. Écrivez des commentaires qui restent exacts quel que soit le moment de leur lecture. ## Mettre à jour la documentation et les notes de ruptures de compatibilité avec le code La documentation fait partie du changement, ce n'est pas une tâche de suivi : - Mettez à jour l'arborescence de documentation pour tout changement visible par l'utilisateur. - Consignez les ruptures de compatibilité dans le fichier dédié aux notes de mise à niveau, afin que les opérateurs les trouvent en un seul endroit. - Écrivez des docstrings pour chaque nouvelle fonction et chaque nouvelle classe. Lorsqu'un changement touche un comportement observable par un opérateur ou un utilisateur final, une pull request sans la modification de documentation correspondante est incomplète. ## Corriger la documentation générée des composants dans les stories, pas dans le générateur Le portail développeur génère automatiquement la documentation des composants à partir des stories du catalogue de composants. Les stories sont la source unique de vérité, ce qui impose deux règles : lorsqu'un rendu est incorrect, corrigez d'abord le fichier de story plutôt que le générateur, et gardez le générateur léger — il extrait et transmet les données des stories, alors résistez à la tentation d'y ajouter des cas particuliers par composant. Pour que la documentation d'un composant se génère correctement, son fichier de story doit : - Exporter l'objet de métadonnées en ligne comme export par défaut, plutôt que de l'affecter à une variable et d'exporter cette variable. - Nommer les stories interactives avec un préfixe cohérent suivi du nom du composant. - Définir les valeurs par défaut des props dans les arguments de la story. - Définir les types d'arguments au niveau de la story, et non au niveau des métadonnées, y compris les types de contrôle et les descriptions. - Utiliser les clés de paramètres documentées pour les grilles de variantes, les enfants d'exemple pour les composants qui en ont besoin, les blocs de code interactifs personnalisés, et les props objets complexes qui ne peuvent pas être analysées en ligne. Gardez à l'esprit le script générateur, son composant d'enveloppe et le répertoire de sortie généré : ce sont les trois pièces mobiles à considérer pour diagnostiquer un problème de documentation. ## Utiliser les utilitaires de test du dépôt au lieu d'écrire sa propre préparation Le dépôt fournit des utilitaires ; servez-vous-en au lieu de bricoler votre propre initialisation. Côté backend, il s'agit de la classe de base de test partagée, des décorateurs pour simuler la configuration et activer ou désactiver les feature flags, des utilitaires d'authentification pour se connecter sous un rôle donné, et des utilitaires de fabrique pour créer les fixtures dont un test a besoin. Côté frontend, il s'agit de l'utilitaire de rendu personnalisé qui installe les providers standards, de la fabrique d'enveloppes pour le store, le routeur et le thème, et de l'utilitaire d'interaction avec les listes de sélection. Règles de simulation : utilisez un mock simple pour les objets de configuration, et ne recourez pas à un mock asynchrone lorsque le code testé est synchrone. Lorsqu'un modèle reçoit un nouveau champ, mettez à jour les listes de colonnes attendues dans les tests d'API. Sachez lancer chaque suite : toute la suite frontend, un seul fichier de test frontend, tous les tests backend, un seul fichier de test backend, un répertoire de tests backend, et la suite de bout en bout dans les modes sans interface, interactif, avec interface et débogage. Si les tests backend échouent à cause de la configuration de la base de données ou de l'environnement plutôt qu'à cause du code testé, demandez à l'utilisateur de lancer l'initialisation de l'environnement de test au lieu d'improviser des correctifs sur son environnement. ## Appeler le point de terminaison de santé de l'application avant de déboguer Effectuez d'abord la vérification rapide d'installation : appelez le point de terminaison de santé de l'application et confirmez qu'il répond avant de consacrer du temps à un rapport de bug. Un échec de la vérification de santé signifie généralement que l'espace de travail n'a jamais été configuré, et non que le code est cassé. Si la vérification de santé échoue, dites à l'utilisateur que l'environnement ne semble pas configuré et renvoyez-le vers les instructions d'installation documentées du projet pour le travail avec des agents, plutôt que de tenter de réparer son environnement vous-même. Repérez les fichiers clés du projet pour vous orienter : le manifeste de paquet frontend pour les scripts de build, de test et de lint ainsi que le port du serveur de développement ; le fichier de projet Python pour la configuration du linter et du vérificateur de types ; et le dossier des dépendances requises, divisé en un jeu de base et un jeu de développement. ## Remplir le modèle de pull request et titrer au format conventional commits Au moment d'ouvrir une pull request : 1. Lisez le fichier de modèle de pull request actuel du dépôt avant de rédiger. Lisez toujours le fichier réel plutôt que de réutiliser un contenu mis en cache, car le modèle évolue avec le temps. 2. Remplissez chaque section définie par le modèle — résumé, preuves avant et après, instructions de test, et informations complémentaires. 3. Intitulez la pull request au format conventional commits `type(scope): description`, par exemple `fix(dashboard): load charts correctly`. Les types valides sont `fix`, `feat`, `docs`, `style`, `refactor`, `perf`, `test` et `chore`. ## Connaître l'organisation des dossiers et des fichiers avant de modifier une zone inconnue Deux habitudes permettent de placer les changements au bon endroit dans un grand dépôt. D'abord, apprenez la carte des répertoires avant de modifier quoi que ce soit : quelle arborescence contient l'application backend, ses points de terminaison d'API, ses modèles de données et ses connecteurs ; quelle arborescence contient les sources frontend et ses zones composants, constructeur de graphiques, tableaux de bord et éditeur de requêtes ; où se trouve le paquet partagé de design system ; et où se trouvent les tests, la documentation et le journal des ruptures de compatibilité. Ensuite, connaissez les motifs de fichiers récurrents pour qu'une nouvelle fonctionnalité atterrisse dans les fichiers conventionnels : le module d'API pour les points de terminaison avec leurs décorateurs et leurs docstrings génératrices de schémas, le module de schémas pour la validation des requêtes et des réponses qui alimente la spécification d'API générée, la couche de commandes pour la logique métier enveloppée dans des transactions, et la couche de modèles pour la persistance. La documentation d'API générée découle de ces docstrings et de ces schémas : un changement de point de terminaison sans mise à jour de la docstring la dégrade donc silencieusement. Les migrations de base de données suivent leur propre convention : elles résident dans le répertoire des versions de migrations, sont nommées avec un horodatage, un hachage de révision et une description, et doivent appeler les utilitaires de migration partagés plutôt que des opérations ORM brutes, afin de rester compatibles avec les différents moteurs de bases de données. Enfin, notez que ce dépôt conserve des fichiers d'instructions parallèles pour différents fournisseurs d'agents. Maintenez-les cohérents lorsque vous modifiez une règle qui s'applique à tous.