Comment écrire d'excellents agents.md : un résumé de l'expérience acquise sur plus de 2 500 bases de code. L'idée principale est que les directives vagues comme « vous êtes un assistant de programmation utile » sont inefficaces. Ce qui fonctionne réellement, c'est une définition précise du rôle, par exemple en indiquant explicitement « vous êtes un ingénieur de test qui écrit des tests spécifiquement pour les composants React, suit des exemples précis et ne modifie jamais le code source ». Le fichier agents.md sert de manuel de travail complet pour la définition des agents intelligents : positionnement des rôles, connaissance de la pile technologique, structure des fichiers de projet, flux de travail, commandes exécutables, exemples de style de code et, surtout, des limites opérationnelles claires. L'analyse a révélé cinq éléments clés que les fichiers agents.md performants suivent généralement : 1. Préfixer les commandes place la commande exécutable au début du fichier, y compris les paramètres et options de commande complets, tels que npm test, pytest -v, au lieu du simple nom de l'outil. 2. Utilisez des exemples de code plutôt que du texte. Un extrait de code concret est plus efficace que trois paragraphes descriptifs. Démontrez directement le style de sortie attendu. 3. Définissez des limites claires et indiquez explicitement à l'IA le contenu auquel elle ne doit absolument pas accéder, comme les informations sensibles, les répertoires de fournisseurs, les configurations de production, etc. « Ne jamais soumettre de clés » est la contrainte la plus courante et la plus efficace. 4. La pile technologique spécifique doit être écrite comme « React 18 + TypeScript, utilisant Vite et Tailwind CSS », plutôt que le général « projet React », et doit inclure le numéro de version et les principales dépendances. 5. Couverture de six domaines essentiels : commandes, tests, structure du projet, style de code, flux de travail Git et limites opérationnelles — la couverture de ces domaines permettra à vos fichiers de configuration d'atteindre le plus haut niveau. L'exemple pratique fournit une configuration complète d'un agent d'analyse documentaire, illustrant comment appliquer les principes susmentionnés à un scénario réel. Cette configuration comprend : • Définissez votre rôle : Expert en documentation technique, maîtrisant Markdown et TypeScript • Connaissance du projet : versions spécifiques de la pile technologique et structure des répertoires. • Commandes disponibles : `npm run docs:build` et `npx markdownlint docs/` • Système de limites à trois niveaux : ce qu’il faut toujours faire, ce qu’il faut demander en premier et ce qu’il faut absolument interdire. Plusieurs agents intelligents dédiés qui méritent d'être construits @docs-agent : Lit le code et génère la documentation, en écrivant uniquement dans le répertoire docs/. @test-agent : Lors de la rédaction de tests, les cas de test ayant échoué ne doivent pas être supprimés. @lint-agent : Corrige la mise en forme du code sans en modifier la logique. @api-agent : Une consultation est nécessaire avant de créer des points de terminaison d’API et de modifier le schéma de la base de données. @dev-deploy-agent : Gère les builds et les déploiements locaux, environnement de développement uniquement. Il est recommandé de commencer par des tâches simples et d'éviter de créer un outil « généraliste ». Privilégiez des tâches spécifiques telles que la rédaction de la documentation des fonctions, l'ajout de tests unitaires ou la correction des erreurs de code. La configuration la plus simple ne requiert que trois éléments : le nom de l’agent, une brève description et la définition précise de son rôle. Vous pouvez également laisser Copilot générer la configuration initiale, puis l’adapter aux besoins du projet. L'essentiel est de retenir que les meilleurs fichiers de configuration d'agent s'améliorent progressivement, plutôt que d'être conçus d'un seul coup. Commencez par des configurations simples, testez-les et ajoutez des détails au fur et à mesure que l'agent rencontre des erreurs. La clé du succès réside dans la fourniture de définitions de rôles précises et de manuels d'utilisation détaillés, plutôt que d'instructions vagues. Adresse du blog :
