Modifier un générateur de documents à agents IA sans confondre sa pile actuelle et l’ancienne

## Trouver d’abord dans le code les vraies commandes de démarrage et la configuration Commencez par les métadonnées des paquets, les points d’entrée de la console, les chargeurs de configuration, le traitement des variables d’environnement et le code qui crée les espaces de travail à l’exécution. En cas de conflit, ces surfaces exécutables prévalent sur la documentation rédigée. - Confirmez quelle commande lance l’application principale. - Confirmez quelle commande expose un éventuel service hérité ou compatible avec MCP. - Remontez de chaque commande jusqu’à son module et sa fonction réels. - Localisez les modèles de configuration et le comportement par défaut de l’espace de travail. - Vérifiez que chaque chemin mentionné existe dans la copie de travail actuelle. Traitez une présentation obsolète comme un contexte historique, non comme une preuve de la voie de démarrage actuelle. ## Décider si le changement relève de la pile actuelle ou de l’ancienne Un dépôt peut distribuer la pile actuelle du produit avec une bibliothèque d’une génération antérieure qui dessert encore un point d’entrée spécialisé. Identifiez la pile responsable avant toute modification. La pile actuelle peut prendre en charge : - l’interface en ligne de commande et le parcours de prise en main ; - l’orchestration et l’exécution de plusieurs agents ; - les agents de recherche, de génération et de conception ; - les outils de type MCP pour la recherche, la réflexion, la conversion et la gestion des tâches ; - les utilitaires de configuration, de journalisation et d’espace de travail ; - la conversion HTML par navigateur et un outil auxiliaire en Node ; - les tests orientés vers l’intégration. La pile héritée peut encore prendre en charge la génération guidée par des gabarits, l’induction de mise en page, l’analyse syntaxique, l’évaluation et un serveur de compatibilité. Ne supposez pas que la modification d’un concept commun dans une pile actualise l’autre. ## Garder une conception simple avec moins de cas particuliers et des fonctions courtes Préférez les conceptions qui transforment les cas limites en cas ordinaires plutôt que d’accumuler des branches conditionnelles. Résolvez le problème réel du dépôt, non un problème d’architecture hypothétique. - Choisissez une solution directe et légère à exploiter lorsqu’elle répond au besoin réel. - Gardez les fonctions courtes, ciblées et clairement nommées. - Traitez toute complexité inutile comme un défaut. - Plus de 3 niveaux d’indentation indiquent que le code doit être restructuré. - Ne dissimulez pas le flux de contrôle normal dans de larges blocs de gestion des exceptions sans mode de défaillance concret. - Maintenez la critique sur le plan technique et dirigez-la vers le code, la conception ou les hypothèses, non vers les personnes. Un bon jugement se manifeste par moins de cas particuliers, des surfaces plus petites et un comportement facile à vérifier. ## Ajouter des annotations de type et limiter les dépendances au minimum Appliquez des conventions cohérentes dans toute la pile maintenue : - ajoutez des annotations de type aux fonctions et aux méthodes ; - rédigez la documentation technique et les commentaires du code dans la langue déclarée par le dépôt ; - utilisez le gestionnaire de dépendances actuel, les outils de recherche du dépôt, les fonctionnalités du langage et les API de bibliothèque prises en charge ; - préférez les interfaces actuelles de sérialisation et de validation aux formes obsolètes ; - réduisez au minimum les dépendances et le volume total de code ; - gardez la définition du paquet racine centrée sur le produit principal ; - placez les dépendances des sous-projets réellement isolés dans leurs fichiers de dépendances locaux. Ne déplacez pas une dépendance dans le seul but de ranger la structure. Séparez-la uniquement lorsque la frontière d’exécution et de maintenance est réelle. ## Suivre un changement dans toutes les parties liées, y compris Python et Node Examinez tout le parcours responsable du comportement à modifier : - pour le comportement en ligne de commande, examinez ensemble les définitions des commandes, les fonctions auxiliaires partagées et le chargement de la configuration ; - pour l’orchestration, examinez le coordonnateur principal et l’implémentation de l’agent concerné ; - pour le comportement MCP, déterminez si la responsabilité relève des serveurs d’outils actuels ou du serveur de compatibilité hérité ; - pour l’exportation et la conversion, examinez à la fois le côté orchestration en Python et le côté conversion en Node ; - pour les concepts de génération dupliqués, ne modifiez que la pile responsable, sauf si la tâche couvre explicitement les deux. Gardez la modification bien délimitée. Ne remaniez pas les deux piles au seul motif que des noms semblables figurent dans chacune. ## Garder les noms de configuration et les emplacements de workspace existants Les clés de configuration existantes, les variables d’environnement, le comportement de prise en main, les exemples de configuration et les emplacements des espaces de travail constituent un contrat d’exécution. Préservez leurs noms, sauf si la tâche comprend explicitement une migration. Les dépendances de navigateur et de conteneur peuvent être des exigences normales d’exécution pour les parcours de conversion, et non des compléments de développement facultatifs. Les outils de conversion natifs, les identifiants d’accès aux modèles, l’automatisation du navigateur et les images de conteneur peuvent également déterminer quels tests d’intégration sont exécutables. Lors de la modification d’un parcours d’exécution : 1. Recensez toutes les sources de configuration et leurs valeurs par défaut. 2. Suivez la manière dont la prise en main et les exemples renseignent ces valeurs. 3. Vérifiez l’appelant Python et tout outil auxiliaire externe de conversion. 4. Préservez la compatibilité ou fournissez une voie de migration explicite. ## Vérifier la doc ancienne avec le code et classer les tests selon ce qu’ils exigent Vérifiez les affirmations de la documentation par rapport à l’arborescence actuelle des fichiers et aux points d’entrée exécutables avant de vous y fier. Des documents anciens peuvent encore expliquer des concepts utiles tout en nommant des fichiers supprimés ou des parcours de démarrage obsolètes. Classez les tests selon leurs exigences : - tests unitaires pour la logique isolée ; - tests de l’analyseur syntaxique ou tests marqués pour les parcours de données spécialisés ; - tests d’intégration pour les outils d’environnement isolé, la conversion par navigateur ou en PDF, le traitement des images et les utilitaires externes ; - tests reposant sur un modèle et nécessitant des identifiants d’accès ou des services en réseau. L’absence d’un navigateur, d’une image de conteneur, d’un convertisseur natif ou d’un identifiant d’accès à un modèle constitue une limite de validation, non une preuve que du code sans rapport est défaillant. ## Lancer les plus petits tests utiles et signaler ce qui n’a pas pu tourner Suivez une séquence de modification ciblée : 1. Confirmez quelle pile et quel point d’entrée sont responsables du comportement. 2. Modifiez la plus petite surface complète. 3. Exécutez le plus petit sous-ensemble significatif de tests. 4. Étendez la vérification uniquement aux parcours directement couplés de Python, Node, navigateur, conteneur ou compatibilité. 5. Signalez toute dépendance ou exigence d’environnement ayant empêché la validation. Examinez l’écart final afin de détecter des modifications accidentelles de l’autre pile, des contrats de configuration renommés, des références documentaires obsolètes, des remaniements sans rapport et des frontières interlangages non testées. Indiquez ce qui a changé, quel parcours a été exercé, quelles vérifications ont réussi et lesquelles n’ont pas pu être exécutées. Ne prétendez pas avoir effectué une validation complète lorsqu’une dépendance d’exécution requise n’était pas disponible.