Modifier une bibliothèque ou un SDK partagé sans casser son API publique

## Lancer tous les tests et builds avant de déclarer une modification terminée Exécutez l'ensemble complet de vérifications du projet avant de déclarer une modification terminée lorsque celle-ci affecte le code d'exécution, les tests ou le comportement de build/test. La vérification s'applique lorsque vous modifiez : - Le code central de la bibliothèque ou des utilitaires partagés. - Les tests, y compris les tests de snapshot. - Les projets d'exemple. - La configuration de build ou de test (manifestes de dépendances, fichiers d'exécution de tâches, configuration de build de documentation, workflows CI). Vous pouvez ignorer la vérification complète pour les modifications portant uniquement sur la documentation ou les métadonnées du dépôt (documentation, guides de contribution, fichiers de métadonnées), sauf si l'utilisateur demande explicitement l'ensemble complet. Décidez si la vérification s'applique en fonction des fichiers réellement modifiés, et non d'une impression subjective de l'ampleur du changement. Relancez l'ensemble complet après avoir appliqué des correctifs — une relance partielle masque les régressions introduites par le correctif lui-même. Lors de l'intégration avec l'API d'une plateforme externe, consultez la documentation faisant autorité de cette plateforme plutôt que de vous fier à des hypothèses génériques sur les API, et inspectez le chemin de code local pour comprendre le comportement propre de la bibliothèque. ## Ne pas changer de branche ou de worktree Git sans l'accord de l'utilisateur Travaillez par défaut dans la copie de travail actuelle de l'utilisateur et sur la branche courante. Si la tâche s'exécute déjà dans un worktree sélectionné, utilisez ce worktree sans demander de permission supplémentaire. Ne créez pas de nouveau worktree et n'en changez pas, et ne créez ni ne changez de branche, à moins que l'utilisateur ne demande explicitement ou n'approuve exactement cette action dans la conversation en cours. Une demande d'implémenter, d'investiguer, de revoir, de tester ou de vérifier des modifications n'autorise pas en soi un changement de worktree ou de branche actif. Si une isolation ou une copie de travail différente est réellement nécessaire, expliquez pourquoi et demandez l'autorisation avant de modifier l'état Git. Cela vaut même lorsqu'une autre règle ou un autre workflow recommande un worktree lié : arrêtez-vous et demandez une approbation au lieu d'en sélectionner ou d'en créer un automatiquement. ## Ajouter les nouveaux paramètres d'API à la fin pour ne pas casser les appels existants L'ordre des paramètres et des champs des API d'exécution exportées est un contrat, pas un détail d'implémentation. - Préservez la signification positionnelle des arguments de constructeur publics existants et des champs de dataclass. N'insérez jamais un nouveau paramètre ou champ au milieu de l'ordre public existant. - Ajoutez les nouveaux champs ou paramètres publics optionnels à la fin, en conservant les champs existants dans leur ordre d'origine. - Si une réorganisation est inévitable, ajoutez une couche de compatibilité explicite ainsi que des tests de régression qui exercent l'ancien schéma d'appel positionnel. - Privilégiez les arguments nommés (keyword arguments) sur les sites d'appel pour réduire les ruptures accidentelles, mais ne vous appuyez jamais sur cela pour justifier une rupture de la compatibilité positionnelle. - Traitez les chemins d'import prévus et les listes d'exports publics comme des contrats. Lors de l'ajout ou du déplacement d'un symbole public, mettez à jour le module propriétaire, les ré-exports de premier niveau ou de sous-package prévus, et un test de régression d'import. - Gardez les imports de premier niveau exempts d'échecs de dépendances optionnelles et d'effets de bord à l'exécution ; utilisez des exports différés (lazy exports) si nécessaire. ## Juger la compatibilité par rapport à la dernière version publiée et planifier les gros travaux Évaluez les changements cassants par rapport à la dernière version publiée, et non par rapport aux évolutions locales non publiées de la branche. Les interfaces introduites ou modifiées après la dernière version publiée peuvent être réécrites directement, sans couche de compatibilité, sauf si elles définissent une limite d'état externe durable publiée ou explicitement prise en charge, ou si l'utilisateur demande explicitement un chemin de migration. Les formats persistés non publiés peuvent être renumérotés ou fusionnés avant la publication lorsque les snapshots intermédiaires ne sont intentionnellement pas pris en charge. Préférez le remplacement direct aux couches de compatibilité pour les évolutions de branche postérieures à une publication. Signalez le risque de compatibilité tôt — mais uniquement lorsque le changement affecte un comportement livré dans la dernière version publiée ou une limite d'état durable publiée et prise en charge — et confirmez l'approche avant de commencer l'implémentation. Utilisez un plan d'exécution lorsque le travail comporte plusieurs étapes, s'étend sur plusieurs fichiers, implique de nouvelles fonctionnalités ou des refactorisations, ou risque de prendre plus d'environ une heure. Maintenez ses sections vivantes (avancement, découvertes, journal des décisions, résultats) à jour au fil de l'exécution, et réécrivez le plan si le périmètre évolue. Si vous omettez intentionnellement un plan pour une tâche complexe, notez pourquoi afin que les relecteurs comprennent ce choix. ## Lire d'abord la référence du sous-système, puis mettre à jour chaque endroit touché par le changement L'exécution d'une bibliothèque est un ensemble de sous-systèmes en interaction — la boucle d'exécution, l'exécution des outils, les adaptateurs de modèles et de fournisseurs, le traçage, les sessions et la persistance, les pipelines temps réel et vocaux, le sandboxing, et l'état d'exécution sérialisé. Avant d'en modifier un, lisez sa référence d'architecture dédiée et assurez-vous de comprendre la limite que vous touchez. Lorsque vous ajoutez ou modifiez une variante qui se répercute sur l'ensemble du système — un nouveau type de sortie de modèle, d'appel d'outil, d'approbation ou d'élément d'exécution — mettez à jour toutes les surfaces concernées : traitement, événements, rejeu, persistance, traçage et sérialisation. Omettre une seule surface produit une corruption subtile et difficile à tracer. Gardez les chemins de streaming et de non-streaming alignés en termes de comportement. Pour tout sous-système possédant des connexions, des tâches ou d'autres ressources, vérifiez la propriété des ressources aussi bien sur le chemin normal que sur le chemin d'échec. Lorsque la forme d'un état d'exécution sérialisé change, respectez les règles de limite de publication, de version de schéma, de lecture rétrocompatible et de tests de régression propres à ce format. ## Aligner la documentation sur le vrai code et garder les données sensibles hors des logs - La documentation est souvent publiée sur un site en ligne, coordonnez donc soigneusement les changements de comportement et les mises à jour de documentation. Si la documentation devait décrire un comportement pas encore publié, différez la modification de la documentation jusqu'à la disponibilité de la publication, ou scindez-la en tâche de suivi. - Traitez les extraits de documentation exécutables comme des vérifications de compatibilité d'API. Avant d'ajouter des exemples de constructeur ou d'API, vérifiez les arguments présentés et la forme d'appel par rapport à l'implémentation réelle. - Ne laissez pas des données de sandbox ou de manifeste non fiables s'exclure elles-mêmes des limites du système de fichiers hôte ou du répertoire de base. Les échappatoires pour la matérialisation locale doivent être contrôlées par du code applicatif de confiance au niveau du site d'appel, jamais par des données de manifeste sérialisées. - Lors de la documentation d'une autorisation ou d'une limite de sécurité, vérifiez que le chemin de code réel l'applique effectivement. N'affirmez pas qu'une autorisation s'applique à un chemin de matérialisation (répertoire local, fichier local, extraction d'archive) à moins que ce chemin ne la consulte réellement. - Lorsque vous masquez des charges utiles sensibles, tenez compte de l'affichage des tracebacks, du chaînage des exceptions, du contexte d'exception conservé, des journaux et de la télémétrie. Supprimer une traceback ne suffit pas si l'objet exception d'origine porte encore l'entrée sensible. ## Passer les contrôles de formatage et de tests, puis rédiger la passation de la PR Étendez les tests chaque fois que vous touchez du code, et assurez-vous que les vérifications pertinentes passent avant de soumettre. - Exécutez la suite de tests complète ; utilisez des exécutions de tests ciblées par motif pendant les itérations. - Exécutez la vérification statique des types ; les annotations de type doivent passer. - Pour les tests basés sur des snapshots, régénérez les snapshots délibérément et relancez la suite ensuite. - La couverture doit rester au-dessus du seuil du projet. - Appliquez le formateur et le linter ; gardez les imports triés ; rédigez les commentaires sous forme de phrases complètes se terminant par un point. - Exécutez les vérifications dans l'ordre obligatoire du projet — formatage, puis lint, puis vérification des types, puis tests. Pour les pull requests et les commits : - Utilisez le modèle de PR du projet : incluez un résumé, un plan de test et le ticket associé le cas échéant. - Rédigez des messages de commit concis à l'impératif ; gardez les commits petits et ciblés. - Ajoutez des tests pour tout nouveau comportement et mettez à jour la documentation pour tout changement visible par l'utilisateur. - Avant votre réponse finale pour un changement éligible, produisez un bloc de transmission de PR (résumé, nom de branche suggéré, titre, description provisoire). Produire cette transmission n'autorise pas en soi la création d'une branche, un commit, un push ou l'ouverture d'une pull request ; omettez-la uniquement pour les tâches triviales ou purement conversationnelles, les tâches méta ou de documentation seule sans impact sur le comportement, ou lorsque l'utilisateur demande de ne pas l'inclure. Les relecteurs recherchent : des vérifications qui passent ; des tests couvrant le nouveau comportement et les cas limites ; un code lisible et cohérent ; des changements d'API publique et visibles par l'utilisateur documentés ; des exemples mis à jour lorsque le comportement change ; et un historique propre avec une description claire.