Garder les documents de compétences d’IA en un seul endroit et les écrire pour que l’IA les consulte

## Modifier seulement le fichier source et régénérer les copies avec le générateur Identifiez le document canonique de la compétence et traitez les intégrations générées, les manifestes et les projections propres aux plateformes comme des artefacts dérivés. Modifiez la source et ses références, puis régénérez les dérivés avec le générateur du dépôt. Ne modifiez jamais à la main les résultats gérés par l'intégration continue. Conservez-y un mode de vérification qui régénère en mémoire ou dans une zone temporaire et échoue lorsque les dérivés enregistrés dans le dépôt s'écartent de la source. Lorsque la même compétence est distribuée sur plusieurs plateformes, partagez le contenu au lieu de maintenir des variantes divergentes. Consignez quel fichier fait autorité pour le contenu, les métadonnées et les valeurs de version afin que les contributeurs ne créent pas de sources concurrentes. Maintenez l'installation et l'utilisation par les utilisateurs finaux hors des instructions destinées aux contributeurs. La documentation des contributeurs doit expliquer la maintenance, la validation, les tests et le fonctionnement des livraisons sans reproduire le guide du produit. ## Garder les choix dans le document principal et les détails dans des fichiers de référence Utilisez le document principal de la compétence comme point d'entrée de la récupération et ne chargez les références détaillées qu'en cas de besoin. Répartissez le contenu ainsi : - les cadres de décision et les modèles fréquents dans le document d'entrée ; - les guides détaillés, les modèles et les exemples étendus dans les fichiers de référence ; - les scénarios de référence et les traces de justification dans la documentation de test ; - l'installation et l'utilisation dans la documentation destinée aux utilisateurs ; - les détails du processus de contribution dans le guide de contribution. Utilisez des liens relatifs stables entre le document d'entrée et les références voisines. Préservez les ancres de référence de premier niveau utilisées par les tables de routage, même lors de la restructuration des sous-sections de niveau inférieur. Appliquez une règle de placement : si un élément détermine le chemin à choisir, conservez-le près du point d'entrée ; s'il explique en détail comment exécuter un chemin déjà choisi, déplacez-le dans une référence. ## Écrire des consignes courtes et directes, avec les tables de décision en tête Optimisez le contenu pour un agent qui classe l'intention, sélectionne une branche et exécute, et non pour un lecteur qui parcourt le guide du début à la fin. Lorsque plusieurs approches sont valides, placez une table de décision compacte avant le guide opératoire. Organisez chaque section ainsi : 1. table de décision ; 2. procédure par défaut ; 3. solutions de remplacement ; 4. règles concises et points de vigilance. Employez le mode impératif et exprimez un seul fait par puce. Transformez les formulations de conseil telles que « vous devriez envisager », « notez que » ou « gardez à l'esprit » en actions directes. Pour les distinctions peu évidentes, préférez de brèves règles affirmatives et négatives. Chaque table, exemple et bloc de code doit ajouter un fait qui n'a pas encore été énoncé. Lorsque la procédure transmet déjà l'instruction, retirez les différences avant-après, les justifications répétées, les apartés pédagogiques et les exemples présents uniquement par souci d'exhaustivité. Limitez la justification à une seule phrase d'ouverture. Fixez une cible de tokens pour chaque sous-section et scindez ou compressez celles qui la dépassent sans retirer les critères de décision, les actions requises, les contraintes ni les exceptions. ## Vérifier la structure du document et tester le comportement de l’IA après chaque changement Adaptez la validation à l'artefact. Les compétences centrées sur la documentation peuvent ne pas nécessiter de compilation, mais elles exigent tout de même des contrôles structurels automatisés et des tests manuels de comportement. Automatisez les contrôles des champs frontmatter obligatoires, des règles de nommage, des limites de lignes ou de tokens, des liens internes, de la synchronisation des artefacts générés et des règles de lint propres au dépôt. Traitez les objectifs de taille souples comme des avertissements et les contraintes strictes d'intégrité comme des échecs. Pour une modification de contenu : 1. modifiez la compétence canonique ou une référence ; 2. exécutez la validation structurelle locale ; 3. rechargez la compétence dans son environnement hôte ; 4. exécutez des requêtes utilisateur réalistes qui parcourent la branche modifiée ; 5. comparez le comportement aux scénarios de référence pour détecter les régressions. Exigez dans la demande de fusion des preuves avant-après pour les scénarios affectés. Pour les modifications importantes de l'architecture de l'information, obtenez une évaluation indépendante centrée sur la structure de récupération, la compression et les branches de décision manquantes. ## Exiger des contrôles sur les pull requests et laisser la version à la publication automatique Protégez la branche principale : exigez des demandes de fusion, des contrôles de validation et un titre valide conforme aux conventions. Si les modifications sont intégrées par une fusion avec squash et que le titre de la demande devient le commit de livraison, validez ce titre, car il détermine le versionnage. Associez les types de modification conventionnels aux incréments de version, en prévoyant un signal explicite de changement majeur. Faites en sorte que le flux de livraison mette à jour le journal des modifications, les métadonnées de la version canonique, les manifestes de plateforme et les artefacts générés dans une seule modification de livraison. Ne modifiez jamais manuellement les numéros de version synchronisés. Conservez une seule source canonique pour la version et laissez la chaîne de livraison la propager avant de créer l'étiquette. Avant la fusion, confirmez les points suivants : - les résultats générés correspondent à la source canonique ; - les tables de décision précèdent les guides opératoires à embranchements ; - les formulations superflues et les exemples redondants ont été retirés ; - les ancres utilisées pour le routage restent stables ; - les scénarios de référence modifiés contiennent des preuves ; - les contrôles obligatoires de validation et du titre sont réussis.