Organiser une bibliothèque de compétences d’IA pour la recherche et ne publier que le contenu revu

## Ranger chaque compétence dans une seule étape du travail de recherche Définissez la mission de la bibliothèque avant de choisir ses dossiers. Une collection axée sur la recherche doit prendre en charge le parcours allant de la question et de l'analyse bibliographique à l'idéation, la préparation des données, l'expérimentation, l'entraînement, l'évaluation, le déploiement et la communication. Utilisez des catégories numérotées ou rendues stables d'une autre manière qui reflètent ce cycle de vie. Conservez une compétence centrale d'orchestration qui achemine les travaux vers des compétences spécialisées sans reproduire leurs conseils détaillés. Pour chaque compétence proposée : - Déterminez l'étape du cycle de vie et une catégorie responsable. - Indiquez le problème utilisateur qu'elle résout et ses conditions d'utilisation. - Nommez les solutions de remplacement proches et expliquez quand elles conviennent mieux. - Évitez les chevauchements de périmètre qui donnent l'impression que deux responsables possèdent la même tâche. Traitez la taxonomie comme un contrat de navigation. Mettez à jour le catalogue, les nombres, les descriptions et la feuille de route chaque fois que la responsabilité ou l'inventaire change. ## Réunir tous les fichiers d’une compétence dans un seul dossier Attribuez à chaque compétence son propre répertoire avec un guide principal obligatoire. N'ajoutez que les dossiers complémentaires dont elle a besoin : - `references/` pour la documentation officielle approfondie, les notes d'API, les tutoriels, les modèles de problèmes et l'historique des versions. - `scripts/` pour les opérations auxiliaires reproductibles. - `templates/` pour les points de départ réutilisables. - `examples/` pour des mises en œuvre complètes et représentatives. - `assets/` pour les ressources autres que du code utilisées par le guide. Le guide principal est le point d'entrée, pas une encyclopédie. Il doit expliquer le parcours opérationnel et renvoyer directement aux références détaillées situées un niveau en dessous. Ne créez pas de chaînes dans lesquelles une référence envoie le lecteur vers une autre pour découvrir des instructions obligatoires. Conservez dans le paquet tous les fichiers nécessaires à l'exécution de la compétence, afin que la validation, la création de l'archive et la synchronisation avec le registre s'effectuent sur une seule limite claire. ## Commencer le guide principal par des champs fixes comme le nom et la version Chaque guide principal commence par un en-tête YAML valide utilisant un contrat de champs fixe : - `name` : un identifiant unique en kebab-case, de préférence un gérondif décrivant l'activité. - `description` : un texte à la troisième personne qui indique à la fois ce que fait la compétence et quand l'utiliser. - `version` : une version sémantique mise à jour chaque fois que le comportement ou les conseils changent. - `author` : une valeur de responsabilité utilisée pour classer l'origine dans le registre. - `license` : la licence de distribution. - `tags` : des termes en casse de titre, tandis que les sigles établis restent en majuscules. - `dependencies` : des paquets facultatifs assortis de contraintes de version explicites. Ne mettez pas les valeurs scalaires entre guillemets, sauf si la syntaxe YAML l'exige. Maintenez les descriptions sous la limite de caractères configurée et évitez les identifiants vagues comme helper, tools ou utilities. Validez le descripteur en l'analysant, pas par une inspection visuelle. Traitez les champs obligatoires manquants, les versions non valides, les noms en double et les dépendances mal formées comme des erreurs bloquantes. ## Garder le guide principal court et déplacer les détails dans des fichiers de référence Visez entre 200 et 500 lignes pour le guide principal. Si les conseils essentiels dépassent 500 lignes, placez les détails avancés dans des fichiers de référence directs au lieu de supprimer des décisions nécessaires en les comprimant ou de laisser le point d'entrée croître sans limite. Le guide doit contenir : - Un objectif concis et des conditions de déclenchement claires. - Une comparaison avec les solutions de remplacement pertinentes. - Deux ou trois processus complets pour les cas d'utilisation complexes. - Des listes de contrôle prêtes à copier lorsque l'ordre est important. - Des exemples concrets d'entrée et de sortie. - Des boucles de rétroaction qui valident, corrigent et répètent les travaux critiques pour la qualité. - Une section consacrée aux problèmes courants avec des solutions précises. Supposez que le lecteur est compétent. Expliquez les choix propres au domaine et les modes d'échec, pas les notions élémentaires déjà impliquées par la tâche. Attribuez un identifiant de langage à chaque exemple de code délimité. Créez des références substantielles à partir de sources faisant autorité, avec un objectif de couverture explicite, comme environ 300 KB, lorsque le domaine le justifie. Ne gonflez pas les documents pour atteindre une mesure de taille ; l'exhaustivité, la traçabilité et l'utilité pratique restent l'objectif. ## Ajouter ou améliorer une compétence en suivant toujours les mêmes étapes Pour une nouvelle compétence : 1. Sélectionnez un élément approuvé de la feuille de route et la catégorie responsable. 2. Créez la structure standard du paquet. 3. Rédigez et validez le descripteur avant de développer le corps. 4. Élaborez les principaux processus et les conseils de décision. 5. Ajoutez au besoin des références directes, des outils auxiliaires, des modèles et des exemples. 6. Testez la compétence sur des tâches réelles représentatives. 7. Mettez à jour le catalogue, les statistiques et la feuille de route dans la même modification. Pour une compétence existante, conservez le contrat du descripteur, incrémentez la version, maintenez le guide principal dans sa limite, ajoutez les processus ou les solutions de dépannage manquants et réexécutez des cas d'utilisation représentatifs. Utilisez une branche de fonctionnalité et une demande de révision ciblée. Incluez tout le paquet et ses modifications de catalogue dans le même commit afin que le dépôt ne présente jamais une compétence incomplète. ## Vérifier les compétences avec des contrôles automatiques et de vraies tâches Exécutez les contrôles mécaniques avant la révision : - Vérifiez que le fichier principal existe et que son en-tête peut être analysé. - Comparez le nombre de lignes du guide principal à l'objectif de 200 à 500. - Vérifiez que chaque bloc de code délimité déclare un langage. - Mesurez la couverture des références par rapport à l'objectif choisi. - Vérifiez que les fichiers référencés se trouvent exactement un niveau sous le guide principal. - Vérifiez que les noms, les étiquettes, les versions et les dépendances respectent leurs schémas. Effectuez ensuite la validation comportementale : - Exécutez chaque processus principal avec des entrées réalistes. - Vérifiez les résultats et les étapes de récupération indiqués. - Provoquez au moins un échec courant. - Vérifiez qu'une solution de remplacement est recommandée lorsque la compétence n'est pas le bon outil. - Répétez la validation après toute modification substantielle. Un grand dossier de références ne compense pas un processus vague, et une présentation soignée ne compense pas des exemples inutilisables. ## Envoyer automatiquement au registre les compétences modifiées après validation Lors d'une modification approuvée de la branche par défaut, détectez quels paquets de compétences de niveau supérieur ont changé. Pour chaque paquet modifié : 1. Exigez le guide principal et analysez son descripteur. 2. Classez l'origine conformément à la politique de responsabilité déclarée. 3. Archivez le paquet complet en excluant les fichiers cachés du système d'exploitation et du contrôle de version. 4. Téléversez l'archive dans l'espace de noms correspondant du registre. 5. Créez ou mettez à jour l'entrée du registre. 6. Signalez les paquets ignorés ou ayant échoué sans les traiter silencieusement comme synchronisés. Stockez les valeurs du point de terminaison et d'authentification uniquement dans le magasin de secrets de la plateforme d'automatisation. Prenez en charge un déclenchement manuel pour la récupération et les tests, mais assurez-vous que la même logique de validation et d'empaquetage s'exécute dans les modes automatique et manuel. Vérifiez le processus avec une modification versionnée sans danger, inspectez l'exécution de l'automatisation, confirmez l'entrée du registre et l'archive, et évitez d'utiliser des modifications non examinées uniquement pour déclencher la chaîne. ## Publier un nouveau paquet seulement quand son numéro de version change Faites dépendre la publication du paquet d'une modification de version dans le descripteur du paquet sur la branche par défaut. Une modification portant uniquement sur le fichier de verrouillage ne doit pas publier une nouvelle version. Utilisez la commande de version du gestionnaire de paquets afin que le descripteur et le fichier de verrouillage avancent ensemble. Sélectionnez une version corrective, mineure ou majeure selon la compatibilité, et ne désactivez la création automatique des étiquettes du contrôle de version que lorsque le processus de publication du dépôt exige un commit distinct. Authentifiez-vous auprès d'un éditeur de confiance configuré plutôt qu'avec un jeton de registre à longue durée de vie. Joignez la provenance de la compilation ou une attestation équivalente de la chaîne d'approvisionnement à chaque artefact publié. Avant la publication, vérifiez : - L'identité de l'éditeur de confiance correspond exactement aux noms du dépôt et du processus. - Les variables d'environnement ne remplacent pas l'authentification de confiance par un jeton obsolète. - Une installation propre réussit à partir du fichier de verrouillage inclus dans le commit. - La nouvelle version diffère de la révision précédente. - Le contenu du paquet correspond à la source examinée. Si la publication est ignorée ou si l'authentification échoue, corrigez la condition de version ou l'identité de confiance ; ne contournez pas la provenance. ## Améliorer les compétences existantes plutôt que d’en ajouter d’autres Évaluez la bibliothèque selon son expertise exécutable, et non selon le nombre de répertoires. Une compétence utile condense des pratiques fiables sous une forme qu'un agent peut suivre et vérifier, et qui lui permet de se remettre d'un échec. Avant la fusion, vérifiez : - Le périmètre correspond à une catégorie et ne fait pas double emploi avec un responsable existant. - Les règles de descripteur, de nommage et de version sont respectées. - Le guide principal reste ciblé et tous les détails obligatoires demeurent accessibles. - Les processus, les listes de contrôle, les exemples, les solutions de remplacement et le dépannage sont présents là où ils sont nécessaires. - Des tâches réelles valident les conseils. - Le catalogue, la feuille de route, l'automatisation de l'archivage et les données de publication du paquet restent cohérents. Préférez améliorer une compétence existante plutôt que d'en ajouter une presque identique. Préférez un processus complet doté d'une boucle de rétroaction fonctionnelle à de nombreux exemples superficiels. Lorsqu'une mesure entre en conflit avec la clarté ou la justesse, conservez les conseils de décision utiles et expliquez pourquoi cette mesure n'était pas un indicateur de remplacement approprié.