Créer et maintenir un outil d’agents de recherche qui fonctionne sur votre propre ordinateur

## Faire tourner l’outil de recherche sur l’ordinateur de l’utilisateur et fixer ce qu’il ne fera pas Créez un environnement de recherche privilégiant le fonctionnement local, qui s’exécute par défaut sur la machine de l’utilisateur, s’installe par une voie publique documentée, conserve son état durable dans des fichiers et le contrôle de version, et prend en charge l’ensemble du cycle de recherche dans un seul espace de travail de projet. Conservez un seul environnement d’exécution de référence pour l’implémentation, même si un lanceur léger ou plusieurs interfaces l’exposent. Utilisez des consignes et des compétences spécialisées pour guider la recherche, tandis qu’un petit service conserve, restaure et achemine l’état. Privilégiez un noyau ciblé plutôt qu’une plateforme en expansion, et énoncez les objectifs exclus dès qu’une proposition élargirait l’environnement d’exécution, les outils publics ou la surface de déploiement. ## Se fier aux fichiers et au comportement actuels plutôt qu’à la mémoire ou aux anciens plans Commencez par les fichiers présents dans la copie de travail actuelle, non par la mémoire ni par un plan ancien. Lisez la présentation du produit, l’index de la documentation, l’architecture destinée aux mainteneurs, le guide de développement, le plus petit ensemble pertinent de références propres au sous-système, l’implémentation et les tests concernés. Lorsque les sources divergent, privilégiez le comportement d’exécution actuel et les tests de contrat réussis, puis le guide couvrant tout le dépôt, ensuite la documentation de référence des mainteneurs, et enfin les notes complémentaires destinées aux contributeurs. Corrigez la documentation inexacte dans la même modification au lieu de conserver un chemin, une affirmation de fonctionnalité ou un flux de travail obsolètes. Traitez le comportement prévu et le comportement implémenté comme deux affirmations distinctes. Ne présentez pas un composant comme disponible tant que son implémentation, sa configuration, son intégration, sa documentation et ses tests ne confirment pas tous cette affirmation. ## Séparer les règles pour les contributeurs au code des règles pour l’IA intégrée à l’outil Distinguez les instructions destinées aux contributeurs du dépôt des consignes et compétences qui régissent un agent exécuté dans le produit. Un contrat d’exécution peut imposer un outil public particulier ou une voie d’exécution restreinte sans appliquer la même restriction aux mainteneurs qui modifient le dépôt. Préservez cette frontière chaque fois que le comportement d’une consigne, d’une compétence, d’une commande ou d’un outil change. Ne réinterprétez pas un contrat de sécurité interne au produit comme une règle de contribution et n’affaiblissez pas le contrat d’exécution au seul motif que les mainteneurs disposent d’outils de développement local plus étendus. ## Garder chaque projet de recherche dans un dossier avec historique des versions Traitez chaque projet de recherche comme un dépôt unique sous contrôle de version, avec une seule racine de projet absolue. Conservez tout le contenu de recherche durable dans cette racine et utilisez des branches ou des arbres de travail isolés pour représenter des approches divergentes sans répartir l’historique du projet entre des emplacements sans rapport. Maintenez un contrat explicite d’espace de travail pour le cahier des charges, le plan, l’état, la synthèse, les artefacts, les références de base, les expériences, la littérature, les transmissions, le manuscrit, la mémoire et l’état d’exécution privé. Les caches et journaux d’exécution peuvent résider hors du projet, mais ils ne doivent pas devenir l’unique copie des preuves de recherche. Lorsque la structure du projet change, actualisez ensemble le modèle de structure, les services de persistance, les instantanés d’état, les consommateurs de l’API, les interfaces utilisateur, les tests et la documentation. Ne migrez pas un seul consommateur en laissant les autres utiliser une structure obsolète. ## Garder simple le programme de démarrage et vérifier ce qui tourne avant de redémarrer Conservez l’environnement d’exécution de recherche de référence dans une seule couche d’implémentation et faites des lanceurs du gestionnaire de paquets de simples adaptateurs à cet environnement et aux éventuels ensembles d’interfaces précompilés. Les paquets d’installation publics doivent contenir les fichiers et les clients compilés nécessaires au démarrage ; ne dépendez pas d’une compilation après installation chez l’utilisateur final pour rendre fonctionnelle la voie prise en charge. Avant de diagnostiquer ou de redémarrer une installation active, examinez le processus en cours, la configuration effective, le superviseur ou le lanceur existant, l’exécutable réellement utilisé et le chemin de base indiqué par un point de contrôle d’état. Ne déduisez jamais le chemin de base actif, la configuration ou le propriétaire du processus d’un simple répertoire par défaut. Alignez les manifestes des paquets, les métadonnées du projet, la documentation publique et les attentes relatives aux ensembles livrés. Un aperçu du paquet ou une simulation doit confirmer l’ensemble des fichiers livrés avant que le conditionnement soit considéré comme terminé. ## Limiter les outils publics de l’IA et justifier chaque nouvel outil Limitez la surface publique des outils intégrés à quelques responsabilités stables : mémoire durable, artefacts versionnés et exécution durable de commandes. Gardez le comportement du contrôle de version derrière la frontière des artefacts et l’exécution de l’interpréteur de commandes derrière la frontière d’exécution, plutôt que d’ajouter un nouvel espace de noms public pour chaque sous-système. Laissez les consignes définir les attentes du flux de travail et les contrats du système de fichiers, et les compétences fournir les comportements d’exécution spécialisés. Le service d’état doit rester léger ; évitez d’inscrire en dur un grand ordonnanceur central d’étapes lorsque les contrats de consignes et de compétences peuvent exprimer clairement le flux de travail. Toute proposition de nouvel outil public doit démontrer qu’aucune responsabilité existante ne peut l’englober, définir son modèle de persistance et d’autorisation, actualiser chaque client et ajouter des tests de contrat. La seule commodité ne suffit pas. ## Ajouter les nouvelles connexions par de petites listes et ne les déclarer finies que quand tout est prêt Utilisez de petits registres pour les exécuteurs de recherche, les canaux de communication, les ponts de connecteurs, la découverte des compétences, les outils locaux gérés et les adaptateurs facultatifs. Préférez des interfaces cohérentes d’enregistrement, de recherche et d’énumération à de grandes branches de répartition ou à des conditions propres à chaque sous-système. Ne considérez pas une intégration comme implémentée tant que son adaptateur d’exécution, les métadonnées de registre, les valeurs de configuration par défaut, la validation, le raccordement au service et à la ligne de commande, la documentation visible par l’utilisateur et les tests ne sont pas tous présents. L’absence d’une seule couche signifie que l’intégration est partielle. Maintenez les adaptateurs facultatifs hors de la voie principale et rendez leur absence explicite. Une entrée de registre doit exposer les capacités et la compatibilité sans installer silencieusement des dépendances, accéder à un service externe ni modifier la configuration locale. ## Utiliser le même état du projet et le même accès au service (API) dans le navigateur et le terminal Exigez que les interfaces de navigateur et de terminal utilisent la même API de service, les mêmes instantanés d’état et le même modèle d’événements. Lorsqu’une route d’API ou un événement change, actualisez dans la même modification le service, chaque client, les hypothèses de navigation et les tests de contrat. Préservez des routes et des identifiants stables, orientés projet, entre les interfaces. Les interfaces utilisateur peuvent présenter des dispositions différentes, mais elles ne doivent ni inventer une sémantique d’état distincte ni masquer une transition qu’une autre interface prise en charge doit observer. Traitez un canal de communication de premier ordre comme une implémentation du modèle générique de canal et de pont. Ne laissez pas un connecteur important devenir un environnement d’exécution distinct, doté de règles propres de persistance, de gestion des erreurs ou de cycle de vie. ## Définir les étapes de recherche, de l’exploration à la rédaction, sans imposer une ligne droite Définissez une courte progression de référence, par exemple exploration, référence initiale, formulation d’idées, expérimentation, analyse, rédaction et finalisation. Considérez la prise de décision comme transversale, au lieu de prétendre que chaque activité importante constitue une étape linéaire unique. Les audits d’admission, la préparation des figures, l’évaluation et la réponse aux évaluateurs peuvent exister comme activités spécialisées, mais ne les placez pas dans la chaîne par défaut à moins que le code actuel et les contrats de consignes ne le fassent réellement. Les étapes nommées doivent correspondre aux points d’ancrage actifs, aux transitions d’état et à la documentation utilisateur du système. Conservez le comportement des étapes dans la consigne système, les contrats de consignes ciblés, l’assemblage des consignes et les compétences d’étape. Évitez de disperser la sémantique des étapes entre les gestionnaires de service, le code d’interface et des conditions ponctuelles. ## Séparer les guides pour les utilisateurs des documents pour les développeurs Séparez les guides destinés aux utilisateurs de l’architecture et des références de développement destinées aux mainteneurs. La documentation publique doit expliquer le comportement actuel ; les documents des mainteneurs doivent expliquer les contrats, les points d’extension et les exigences de modifications coordonnées. Ne placez pas de plans temporaires, de listes de contrôle provisoires, de chemins privés ni de notes exclusivement internes dans l’arborescence de documentation publique. Stabilisez les noms des documents liés, retirez les références aux fichiers supprimés et actualisez chaque traduction maintenue lorsqu’un comportement visible par l’utilisateur change. Lorsqu’une modification ne concerne que la maintenance interne, actualisez les références officielles des mainteneurs sans fabriquer d’annonce destinée aux utilisateurs. Le périmètre de la documentation doit suivre celui du comportement. ## Tenir mots de passe et chemins personnels hors des fichiers partagés et garder les traces de recherche N’enregistrez pas dans le contrôle de version les chemins absolus propres à un poste de travail, les identifiants d’accès, les jetons, les caches locaux, les répertoires de dépendances, les sorties de compilation temporaires ni les caches de tests. Les ensembles d’interfaces générés n’appartiennent à un paquet public que lorsque le contrat de conditionnement l’exige explicitement. Conservez les relevés durables d’expériences, les notes de littérature, les références de base, les artefacts et les manuscrits dans le périmètre du projet et sous contrôle de version. Préservez les preuves originales avant de les résumer et ne remplacez jamais un résultat reproductible par un simple message d’état de l’interface. Avant la diffusion, examinez les fichiers publics afin d’y détecter des secrets divulgués, des noms de documents obsolètes, des références privées et des divergences dans les fichiers générés. Une exécution de tests sans erreur ne justifie pas la publication de contenu sensible ou non reproductible. ## Examiner d’abord le code actuel et faire de petites modifications Examinez l’implémentation existante avant de proposer une nouvelle abstraction. Préférez de petites modifications cohérentes aux remaniements vastes et mêlés, consultez d’abord le plus petit ensemble pertinent de documentation et vérifiez la proposition à l’aide du code et des tests. Lorsque le code et la documentation divergent, corrigez-les ensemble dans une seule modification bien délimitée. Ne conservez pas des références obsolètes au seul motif qu’elles ont existé, et ne redémarrez pas un service de recherche actif avant d’avoir identifié l’environnement d’exécution effectif, le processus, la configuration et le chemin de base. Séparez le diagnostic de la modification. Consignez le signal observé, le comportement attendu, les consommateurs concernés et la plus petite correction avant de modifier l’état partagé. ## Mettre à jour tests et documentation avec le code modifié, sans toucher au reste Actualisez chaque couche directement touchée du sous-système modifié : - structure du projet ou état durable : modèle de structure, service de persistance, instantanés, consommateurs de l’API et tests d’état ; - consignes ou compétences d’étape : sources des consignes, assemblage, définitions des compétences, programmes d’installation répliqués, tests de comportement et guides utilisateur ; - mémoire, artefacts ou exécution de commandes : implémentations, frontières publiques, tests de service et documentation des contrats ; - exécuteurs de recherche : adaptateur, registre, valeurs de configuration par défaut, validation, raccordement au service et à la ligne de commande, guides et tests ; - canaux ou ponts de connecteurs : valeurs par défaut, validation, code des canaux et des ponts, guides des connecteurs et tests d’intégration ; - outils locaux gérés : registre, adaptateur concret, comportement d’état et de résolution, guides des mainteneurs et tests ; - surface d’API partagée : routeur, gestionnaires, client de navigateur, client de terminal, navigation et tests de contrat ; - conditionnement : manifestes, métadonnées du projet, présentation publique, ensembles requis et vérification du contenu du paquet. N’étendez pas cette matrice à des sous-systèmes sans rapport. Son objectif est d’assurer une complétude coordonnée dans le périmètre d’incidence directe, non de réécrire tout le dépôt. ## Tester l’installation documentée avant de déclarer le travail terminé Exécutez les vérifications pertinentes d’unité, d’intégration, de contrat, de compilation, de construction d’interface et de conditionnement pour la surface modifiée. Démarrez par la voie publique documentée lorsque le comportement du lanceur ou du conditionnement change, et ne vérifiez le démarrage direct du service qu’à titre de diagnostic. Examinez l’ensemble final des modifications afin de repérer les changements sans rapport, les fichiers générés obsolètes, la documentation traduite manquante, les affirmations de fonctionnalités non prises en charge et les mises à jour incomplètes des clients. Distinguez la réussite locale d’un test de composant de la preuve que la voie d’installation et d’interface prise en charge fonctionne. Utilisez la copie de travail réelle comme dernière source de référence. Si un fichier ou un comportement mentionné n’existe plus, corrigez la référence et ses consommateurs au lieu de conserver l’erreur.