Modifier une application de bureau de design IA à priorité locale en respectant ses règles fixes

## Suivez le guide de l'agent quand les fichiers d'instructions se contredisent Lisez ce fichier avant toute modification. Les autres fichiers d'instructions destinés aux agents présents dans le dépôt peuvent être en retard sur le plan actuel ; lorsqu'ils sont en désaccord avec celui-ci, c'est celui-ci qui prévaut. Les documents de conception internes, tels qu'un document de vision, un document de principes ou le plan de publication en cours, constituent un contexte supplémentaire utile lorsqu'ils existent dans votre copie de travail. Le répertoire des documents internes est exclu par gitignore : les mainteneurs conservent donc localement les plans, les passations et les travaux de recherche, tandis que les contributeurs publics peuvent n'en avoir aucun. - Ne bloquez jamais le travail d'un contributeur public à cause de fichiers que seuls les mainteneurs peuvent voir. - Ne citez jamais, dans un commentaire de revue public, un chemin situé sous le répertoire de documents exclu par gitignore, sauf si ce fichier existe aussi dans la copie de travail publique. - Lorsque ces documents sont absents, appuyez-vous sur ce fichier, sur les tickets et les pull requests publics, ainsi que sur le README. ## Traitez chaque design comme une longue session avec son propre espace de travail Le produit n'est pas un générateur à invite unique. Chaque unité de travail est une session d'agent de longue durée adossée à un véritable espace de travail sur la machine de l'utilisateur, et l'agent peut lire et modifier des fichiers, exécuter des commandes soumises à permission, poser des questions structurées, prévisualiser des artefacts, exposer des contrôles de réglage, générer des images lorsque le modèle configuré le permet, et produire des documents de système de design. - Un design possède un espace de travail. Il n'y a pas de séparation entre scellé et ouvert : le système de fichiers de l'espace de travail est la source de vérité pour les artefacts et les ressources. - L'agent modifie les fichiers sources dans l'espace de travail ; l'environnement d'exécution de la prévisualisation transforme ces sources en un document consultable ; les exportateurs convertissent le document rendu ou source en sorties standard telles que HTML, PDF, PPTX, ZIP ou Markdown. - Conservez un seul fichier source d'entrée canonique pour le format actuel (par exemple un fichier de composant JSX), et réservez le fichier HTML autonome aux exports ou aux anciens fichiers d'espace de travail. - Emprunter des mécanismes d'agent de codage éprouvés est voulu ; la frontière du produit est que les outils spécifiques au domaine et le modèle d'espace de travail à priorité locale sont ce que vous ajoutez par-dessus. ## Respectez les règles fixes : aucun modèle embarqué, uniquement votre propre clé Ce sont des engagements du projet, pas des préférences. Ne les sacrifiez pas par commodité. 1. Aucun environnement d'exécution de modèle embarqué. N'intégrez pas de moteurs d'inférence, d'interpréteurs de langage, de binaires de navigateur ni de poids de modèle dans l'installeur. Utilisez les installations du système, ou un téléchargement différé avec un consentement visible par l'utilisateur. 2. Uniquement le principe « apportez votre propre clé ». Aucun compte hébergé, aucune API relayée par un proxy, aucune télémétrie par défaut. Les identifiants de l'utilisateur restent dans une configuration locale lisible par un humain. 3. Stockage à priorité locale. Les sessions existent sous forme de fichiers de session en ajout seul, complétés par de véritables fichiers d'espace de travail. Les données déjà présentes dans l'ancienne base de données embarquée peuvent être migrées, mais n'y ajoutez pas de nouvelles tables pour les sessions, l'historique de conversation, les commentaires, les instantanés ou les fichiers de design. 4. Chaque design dispose d'un espace de travail. Rien d'important ne doit exister uniquement à l'intérieur d'un enregistrement de session. 5. Tout ce qui est livré, embarqué, lié, importé par le code de l'application ou distribué aux utilisateurs doit être sous licence permissive et compatible avec la licence du projet. Rejetez dans cet ensemble les ressources tierces sous copyleft, à source disponible, propriétaires ou à licence peu claire. L'outillage d'intégration continue et de publication réservé aux workflows peut utiliser des licences copyleft lorsqu'il n'est ni copié dans le dépôt, ni embarqué, ni lié, ni recopié dans le produit ; documentez pourquoi, et limitez sa sortie à des métadonnées ou des manifestes ordinaires. 6. Chargez les fonctionnalités lourdes de façon différée. Les exportateurs, la capture web, les échafaudages, les compétences, les ressources de référence et la génération d'images doivent se charger à la demande plutôt qu'au démarrage de l'application. 7. Réutilisez d'abord les primitives du framework d'agent sous-jacent. C'est lui qui gère les sessions, les outils intégrés, l'exécution shell, la diffusion d'événements, le registre des modèles, l'enregistrement des fournisseurs et les données de capacités, sauf si un besoin propre au domaine démontre le contraire. 8. Les données de référence sont des données, pas la mémoire du modèle. Prenez les valeurs de marque et de style dans le document de design de l'espace de travail, les fichiers de l'utilisateur, les ressources officielles ou des sources publiées. N'inventez jamais de couleurs de marque ni de spécifications de mémoire. 9. Les changements doivent rester compatibles, évolutifs, sobres et élégants, et doivent suivre la liste de contrôle détaillée des principes du projet lorsqu'elle est présente. ## En créant un site web, ajoutez des fichiers lisibles par l'IA comme llms.txt Lorsque vous créez ou mettez à jour un site web, une page d'accueil de projet, une page produit, un site personnel, un site de documentation, un blog ou une page de projet publique, intégrez la visibilité auprès des IA au périmètre de livraison par défaut, sauf si l'utilisateur la refuse explicitement. - Ajoutez un fichier `/llms.txt` contenant un aperçu Markdown concis du site, de l'auteur ou de l'organisation, des pages clés, des descriptions canoniques du projet ou du produit, ainsi que des liens vers des ressources lisibles par machine. - Ajoutez un fichier `/llms-full.txt` lorsque le site comporte assez de contenu public substantiel pour justifier un fichier de contexte lisible par une IA plus complet. - Configurez `robots.txt` de façon délibérée : autorisez les robots d'exploration de recherche et de récupération qui aident les systèmes d'IA à citer ou à récupérer du contenu public, et traitez les robots d'entraînement comme une décision de politique distincte. - Maintenez `sitemap.xml` et assurez-vous qu'il couvre les pages publiques importantes. Mentionnez la soumission aux outils pour webmasters lorsque c'est pertinent. - Ajoutez des données structurées JSON-LD appropriées là où c'est utile, par exemple les types personne, organisation, site web, article, application logicielle, foire aux questions ou œuvre de création. - Privilégiez des points d'accès lisibles par machine, en Markdown propre ou en JSON, pour les entités importantes telles que les profils, les projets, les publications, la documentation, les versions, les foires aux questions et les informations produit. - Gardez un contenu véridique, étayé par des sources et exempt de spam. L'objectif est d'aider les systèmes d'IA à comprendre et à citer avec exactitude du contenu réel et existant, pas de produire du remplissage de faible qualité. ## Faites passer appels au modèle et outils par le framework d'agents partagé - Appuyez-vous sur le framework d'agent partagé et sur sa couche d'abstraction des modèles plutôt que sur un équivalent fait maison. - Utilisez les outils intégrés du framework pour les opérations de lecture, d'écriture, d'édition, de shell, de recherche par motif, de recherche de fichiers et de listage, au lieu d'en écrire des versions parallèles. - Faites passer chaque appel d'outil par le hook d'appel d'outil du framework et par l'interface de permissions de l'application. - Lisez les capacités des modèles dans les champs de description de modèle du framework, tels que les types d'entrée acceptés, la prise en charge du raisonnement, le coût, la fenêtre de contexte et le nombre maximal de jetons en sortie. Ne codez pas en dur des tables de capacités. - Enregistrez les fournisseurs personnalisés via l'API d'enregistrement de fournisseurs du framework. Ne construisez pas une couche SDK de fournisseurs parallèle. - Tous les appels de modèle passent par l'abstraction de modèle du framework. N'importez pas directement les SDK des éditeurs dans le code de l'application. ## Rangez les sessions dans des fichiers en ajout seul et les designs dans l'espace de travail - Un design est une session. L'historique de session réside dans le répertoire de données utilisateur de l'application, sous forme de fichiers de session en ajout seul. - Les fichiers sources de design, le balisage et les styles générés, les ressources, les exports ainsi que les documents d'agent et de design au niveau de l'espace de travail résident dans l'espace de travail de l'utilisateur, pas dans une base de données de l'application. - Les réglages de l'espace de travail résident dans un fichier de réglages versionné qui porte un champ explicite de version de schéma. - Le fichier de réglages locaux personnels est propre à chaque utilisateur et doit rester exclu par gitignore. - L'ancienne base de données embarquée est un ensemble de données à migrer, pas le modèle de stockage actuel. Ne l'étendez pas avec l'état de nouvelles fonctionnalités. ## N'utilisez que les outils intégrés et quelques outils de design La surface d'outils se compose des outils intégrés du framework, plus une courte liste d'outils propres au domaine : - `ask(questions)` affiche des questions structurées et attend l'utilisateur. - `scaffold(kind, path)` copie un modèle de départ sélectionné dans l'espace de travail. - `skill(name)` charge à la demande le texte d'une compétence depuis un manifeste. - `preview(path)` effectue le rendu des artefacts et renvoie les erreurs de console, les erreurs de ressources, un plan du DOM, des métriques et des captures d'écran destinées aux modèles de vision. - `gen_image(prompt, path)` écrit les images générées sur le disque lorsque la capacité et la configuration du fournisseur le permettent. - `tweaks(blocks)` déclare des contrôles modifiables répartis sur plusieurs fichiers. - `todos(items)` affiche l'état des tâches pour les tours complexes. - `done(path)` termine un tour après une auto-vérification par prévisualisation. Ne réintroduisez pas de sous-agent vérificateur, d'outil de capture d'extraits, d'outil shell personnalisé, d'outil personnalisé de listage de fichiers, ni de mémoire de travail écrite par l'agent, sauf si le plan change. ## Gardez séparés les quatre types de ressources de design Le document de design suit la spécification publiée et peut être à la fois une entrée et une sortie. Les travaux multi-écrans générés par l'agent conservent leur cohérence visuelle en mettant à jour ce document à mesure que des jetons de design apparaissent. Les systèmes de référence intégrés doivent porter une attribution, une source, des métadonnées de licence et une mention « sans affiliation », et les compétences intégrées utilisent le format de fichier de compétence standard. Les manifestes de compétences et d'échafaudages doivent porter des métadonnées de licence et de source. Les quatre types de ressources ne sont pas interchangeables : - Les compétences en Markdown sont des règles de méthode. Elles indiquent à l'agent comment travailler ; elles ne copient pas de fichiers dans un espace de travail. - Les systèmes de design de référence sont en lecture seule et se chargent par leur nom comme une compétence. Ne les modifiez pas pour un projet ; reportez les choix que vous adoptez dans le document de design de l'espace de travail. - Les échafaudages sont des ressources concrètes de départ et de source, copiées dans l'espace de travail. Ils peuvent être dans n'importe quel format texte tant que le manifeste les décrit avec exactitude. - Les extraits des compétences de design sont des motifs de composants copiables, exposés via le système de fichiers virtuel. Ce sont des extraits de code source, et non des règles de méthode ni une autorité en matière de marque. Le document de design de l'espace de travail est le témoin propre à chaque projet. Dès lors qu'il existe, il fait autorité pour le design en cours, et les travaux générés doivent le préserver ou le réparer plutôt que le traiter comme un préréglage de plus. ## Relisez les modèles de départ comme du code produit et alignez leurs extensions - Traitez les ressources de départ et d'échafaudage comme du code produit, pas comme du remplissage d'invite. Examinez le contenu réel des fichiers ainsi que le manifeste avant de modifier ou d'ajouter un préréglage. - Gardez le format source et l'extension de fichier alignés. Les documents HTML complets vont dans des fichiers `.html`, les modèles de départ de composants dans l'extension des composants, les extraits de style dans `.css`. L'outil de copie doit préserver l'extension source, mais la ressource elle-même doit malgré tout être correctement nommée et décrite. - Les modèles de départ HTML intégrés doivent être autonomes et prévisualisables dans l'environnement d'exécution actuel. N'ajoutez pas de scripts d'exécution provenant d'un CDN ou d'un tiers aux ressources d'échafaudage. Si un modèle de départ a besoin d'un comportement à l'exécution, utilisez du HTML, du CSS et du JavaScript simples et locaux, ou une dépendance fournie par l'application, chargée à la demande et dotée d'une licence clairement établie. - Évitez les textes d'espace réservé faibles tels que « Titre de la présentation », « Contenu de la page », « Remplacez ceci » ou « Premier point ». Utilisez un contenu d'exemple neutre et utilisable, et exposez les points de remplacement évidents via les valeurs de réglage par défaut déclarées du modèle de départ. - Les descriptions du manifeste doivent indiquer dans quel format se trouve un modèle de départ et doivent signaler les ressources sensibles à l'extension, en particulier les fichiers qu'un agent risquerait sinon de copier sous une mauvaise extension. - Lorsque vous touchez à l'arborescence des échafaudages, recherchez les incohérences entre extension et contenu, les URL réseau externes, les textes d'espace réservé obsolètes et les dérives du manifeste. Ajoutez ou mettez à jour des tests ciblés d'échafaudage et d'exécution lorsque le changement affecte les chemins de copie, la classification de la prévisualisation ou le comportement des outils. ## Gardez les outils déjà choisis et lisez les versions dans le lockfile - Un seul gestionnaire de paquets pour l'ensemble du dépôt. N'en mélangez jamais un deuxième. - Utilisez l'orchestrateur de build retenu par le dépôt, son unique outil d'analyse statique et de formatage, son exécuteur de tests unitaires et son exécuteur de tests de bout en bout, plutôt que d'introduire des solutions concurrentes. - TypeScript en mode strict, avec la syntaxe de module verbatim et la résolution de type bundler. Pas de `any`. - Conventional Commits pour les messages, et un outil de changesets pour la gestion des versions. Ne modifiez pas le journal des changements à la main. Épinglez la version de l'environnement d'exécution à la fois dans le fichier de version et dans le champ engines. - Les versions exactes des paquets se trouvent dans les manifestes et dans le fichier de verrouillage. Lisez ces fichiers au lieu de vous fier à une documentation obsolète. - Les choix côté frontend sont déjà arrêtés : la bibliothèque de vues et l'outil de build retenus, du CSS utilitaire avec des variables CSS, une seule bibliothèque d'état légère, des primitives accessibles sans interface visuelle imposée, encapsulées dans le paquet d'interface partagé, un seul jeu d'icônes, des formulaires natifs s'appuyant sur les données de formulaire, et des transitions CSS pour l'animation. N'introduisez pas de bibliothèques concurrentes d'état, d'animation ou de composants. - L'habillage de l'application doit utiliser les jetons du paquet d'interface partagé. Les sources de design générées et les exports peuvent définir leur propre système visuel. - Le dépôt répartit la coquille applicative, le cœur de l'agent, l'intégration des fournisseurs, l'environnement d'exécution de la prévisualisation, l'interface partagée, les schémas d'artefacts, les exportateurs, les modèles et les types partagés dans des paquets distincts. Placez le code dans le paquet responsable du sujet concerné. ## Écrivez un plan pour les grosses tâches et limitez la portée des modifications - Pour tout travail d'architecture ou de produit non trivial, lisez les documents de vision, de principes et de plan en cours lorsqu'ils existent localement ; sinon, appuyez-vous sur ce fichier et sur les discussions publiques. - Rédigez un fichier de plan local durable pour les tâches qui s'étendent sur plus de cinq appels d'outils environ ou sur plus de trois fichiers. Ne créez pas d'agitation de planification pour de petites corrections directes. - Utilisez des arbres de travail distincts pour les travaux de fonctionnalités menés en parallèle ou sans rapport entre eux. Ne mélangez pas deux branches sans rapport dans une même copie de travail. - Consultez la file d'attente de recherche avant de toucher au bac à sable, aux commentaires en ligne, aux contrôles de réglage, aux exportateurs, aux capacités du framework, aux échafaudages, aux compétences ou aux ressources de référence, lorsque ce fichier existe localement. - Gardez vos modifications circonscrites et évitez les refactorisations opportunistes. - Avant d'ajouter une dépendance livrée ou d'exécution, vérifiez sa licence, sa taille d'installation, les solutions de rechange, et si elle peut être une dépendance de pair. Pour les outils réservés aux workflows, documentez pourquoi ils ne sont pas embarqués et si leur sortie a une incidence sur les artefacts distribués. - Ajoutez ou mettez à jour la couverture de tests unitaires pour les travaux de fonctionnalités, et élargissez les tests lorsque vous modifiez les migrations, les permissions, les hooks d'outils ou les contrats partagés. - Préférez un manifeste accompagné d'une logique d'aiguillage plutôt qu'un registre, tant que deux appelants réels n'ont pas besoin de davantage. - Ne commentez que là où la raison surprendrait le prochain mainteneur. ## Classez les commandes en quatre niveaux de permission et montrez pourquoi une est bloquée Il existe un modèle de permissions unique, doté de niveaux croissants : - Niveau 0 : les lectures et écritures locales à l'espace de travail, les commandes de fichiers simples et les commandes de gestion de versions en lecture seule peuvent s'exécuter sans interruption. - Niveau 1 : les installations, les commandes de build, les requêtes réseau non locales et les commandes situées hors du répertoire de travail demandent une autorisation une seule fois, puis peuvent être ajoutées à une liste d'autorisation. - Niveau 2 : la publication, l'envoi vers un dépôt distant, l'élévation de privilèges et les autres commandes à fort rayon d'impact demandent une autorisation à chaque fois. - Niveau 3 : les commandes système destructrices, le fait de rediriger un script téléchargé directement dans un shell et les écritures dans les répertoires système sont bloqués en l'absence d'une dérogation explicite. Ne masquez pas les appels d'outils bloqués. Affichez la commande, le chemin, le niveau et la raison du blocage. ## N'importez pas de SDK de fournisseur et n'ajoutez pas de suivi sans consentement - Ajouter à la gestion de versions les répertoires de dépendances, les sorties de build, les fichiers d'environnement, les artefacts de publication générés ou les fichiers locaux privés. - Importer les SDK des éditeurs de modèles dans le code de l'application, ou écrire des tests qui simulent le modèle au niveau du SDK de l'éditeur. Simulez plutôt à la frontière du cœur ou du framework. - Ajouter du suivi, des statistiques d'usage, des parcours de compte, une synchronisation dans le cloud ou une mise à jour automatique sans une expérience d'adhésion explicite. - Coder en dur les chemins des utilisateurs. Respectez les conventions de répertoires de la plateforme, les API de chemins de l'application et les racines des espaces de travail. - Ajouter un nouvel état de fonctionnalité adossé à l'ancienne base de données pour les données de session ou de design. - Introduire une abstraction de regroupement plus lourde au-dessus de l'espace de travail. Plusieurs sessions peuvent partager un espace de travail, mais la barre latérale liste les sessions. - Exposer la ramification des sessions, l'annulation et le retour à une version antérieure, la prise en charge de serveurs d'outils externes ou l'installation de compétences communautaires, sauf si le plan change. - Utiliser des appels console bruts dans le processus principal, le cœur, les fournisseurs, les exportateurs ou les paquets partagés. Utilisez le journaliseur du projet.