Guide AGENTS.md : Format open source de « description de projet » pour les agents de codage (AI Agents). AGENTS.md s’agit d’un format d’instruction open-source pour les « agents de codage IA ». C’est comme la « version agent » du README : elle fournit à l’agent des informations clés telles que les builds, les tests, les spécifications de code et les considérations, ce qui aide l’agent à effectuer des tâches de manière plus fiable dans votre base de code. Selon le site, un grand nombre de projets open source ont adopté ce format ; Son objectif de conception est d’être commun à plusieurs agents et outils, adapté aux équipes et aux dépôts open source pour une mise en œuvre rapide.
1. Qu’est-ce que AGENTS.md
1) Positionnement : Un document de documentation pour les agents de codage IA, qui est un complément fonctionnel au README.
2) Objectif : Donner aux agents une entrée fixe et prévisible pour centraliser le contexte et des instructions pour « faire travailler efficacement les agents ».
3) Forme : Markdown pur, pas de champs forcés ; Écrivez à la demande pour la maintenance à long terme et la gestion des versions.
2. Pourquoi avez-vous besoin de AGENTS.md (relation avec README)
1) README s’adresse aux lecteurs humains, en mettant l’accent sur les descriptions de produits, les démarrages rapides et les guides de contribution.
2) AGENTS.md orienté agent, en mettant l’accent sur les commandes de construction/test, le style de code, les exigences CI et les points de sécurité.
3) Avantages de la séparation : gardez le README concis tout en donnant aux agents un document dédié qui « il suffit de regarder ceci et vous pouvez faire le travail ».
3. Conception de base et compatibilité écologique
1) Format ouvert : utilisez n’importe quel titre de sous-section et structure de contenu, analyse proxy par texte, pas de syntaxe propriétaire.
2) Compatibilité multi-agents : La liste officielle des directions d’adaptation pour plusieurs agents/outils (tels que Codex, Amp, Jules, Cursor, Factory, RooCode, etc.).
3) Règle de priorité : En cas de conflit d’instructions, le AGENTS.md le plus proche du fichier cible prend effet ; Les instructions explicites de la boîte de dialogue de l’utilisateur ont priorité sur les instructions génériques.
4) Monorepo friendly : soutien au placement de AGENTS.md « à proximité » dans des sous-packs ; Les grands entrepôts peuvent gérer les descriptions d’agents pour différents sous-projets dans des couches.
4. Comment adopter (quatre étapes)
1) Ajouter des fichiers : Créez un AGENTS.md dans le répertoire racine de la base de code ; Si nécessaire, mettez-en une copie dans le sous-pack.
2) Objectif de couverture : aperçu du projet, commandes de construction et de test, style de code, spécifications de test, points de sécurité et de conformité.
3) Règles supplémentaires : informations de soumission et spécifications de relations publiques, téléchargements de données et de ressources de modèle, étapes de déploiement et pièges courants.
4) Maintenance itérative : Traitez-le comme un « document vivant » et mettez-le à jour au fur et à mesure que la structure CI/dépendance/répertoire est mise à jour.
5. Le modèle minimum disponible
# AGENTS.md ## Aperçu du projet - Espace de travail Monorepo + PNPM。 La langue principale est TypeScript. ## Configuration et construction - Installer : installation pnpm - Dev : pnpm dev - Test : test pnpm - Charpie : peluche pnpm ## Style de code - Mode TS strict ; guillemets simples, pas de points-virgules ; Les expressions fonctionnelles ont la priorité. ## Tests - CI chez .github/workflows ; Tous les cas d’utilisation doivent être transmis localement avant d’être validés. ## Règles de relations publiques - Titre : [<pkg>] <titre> ; Vous devez exécuter lint et tester avant de vous engager. ## Sécurité - Ne soumettez pas de fichier .env ; Les clés sont injectées à l’aide de secrets d’entrepôt ou d’injections locales.
6. Cas d’utilisation typiques
1) Référentiel open source : laissez l’agent qui entre en contact avec celui-ci « out of the box et testez » et effectuez automatiquement une vérification de build/test unique/statique.
2) Collaboration d’équipe : Des « conventions implicites » explicites (style de codage, processus de soumission) pour réduire les frictions entre les agents et les personnes.
3) Gouvernance des grands entrepôts : Répartissez les AGENTS.md par sous-projets pour obtenir des instructions à proximité et des processus différenciés.
4) Sécurité et conformité : Écrivez clairement les « données/modèles non téléchargeables » et la ligne rouge de sécurité pour réduire le risque d’opérations automatisées.
7. Suggestions d’implémentation et avertissements de risques
1) Commencez par le « modèle minimum » : uniquement des règles de construction, de test, de style et de relations publiques, puis affinez progressivement.
2) Alignez-vous avec CI : synchronisez les raccourcis clavier de CI vers AGENTS.md pour éviter que l’agent ne s’exécute mais que CI ne puisse pas.
3) Gestion explicite des conflits : Écrivez en haut du fichier que « s’il y a un conflit avec l’instruction de l’utilisateur, l’instruction de l’utilisateur prévaudra ».
4) Affirmation incertaine : Lorsqu’il s’agit d’indicateurs tels que « combien de projets ont été adoptés », il est recommandé de marquer « selon l’auto-déclaration du site » pour éviter les erreurs de lecture des données.
FAQ Q&R
Q : Y a-t-il des champs obligatoires ou des modèles standard pour AGENTS.md ?
R : Non. Il s’agit d’une instruction Markdown générique qui encourage l’organisation des chapitres en fonction des besoins réels du projet.
Q : Comment répartissez-vous le travail avec le README ?
R : Le README est pour les gens ; AGENTS.md Orienté agent. Le premier parle de « quoi/comment commencer » et le second parle de « comment l’agent exécute les builds/tests/spécifications ».
Q : Comment Monorepo organise-t-il plusieurs AGENTS.md ?
A : Mettez la description générale dans le répertoire racine, et mettez la description la plus proche dans le sous-paquet ; Les agents privilégient généralement la lecture de la copie la plus proche du fichier cible.
Q : Prenez-vous en charge plusieurs outils proxy ?
R : D’après la page du projet, il est conçu pour être compatible avec plusieurs agents et outils, et en principe, « un document, plusieurs agents sont disponibles ».
