AGENTS.md - Un format ouvert pour les agents de codage IA

 (agents.md)
35 points par GN⁺ 2025-08-21 | 1 commentaires | Partager sur WhatsApp
  • AGENTS.md complète le README et sert de fichier dédié contenant le contexte et les instructions dont les agents de codage IA ont besoin lorsqu’ils travaillent sur un projet
  • Déjà utilisé dans plus de 20 000 projets open source, il regroupe des informations importantes pour les agents, mais inutiles pour les humains, comme le build, les tests ou le style de code
  • Il fournit des instructions dédiées aux agents dans un emplacement clair et prévisible, ce qui permet de garder le README concis tout en renforçant l’efficacité de la collaboration
  • Un seul fichier AGENTS.md est compatible avec divers agents et outils, et dans les grands monorepos, il est possible d’utiliser un AGENTS.md distinct par sous-projet
  • Un standard ouvert conçu grâce à la collaboration de plusieurs écosystèmes, dont OpenAI Codex, Cursor et Google Jules

Why AGENTS.md?

  • README.md est une documentation pour les humains : démarrage rapide, présentation du projet et consignes de contribution
  • AGENTS.md est une documentation complémentaire pour les agents ; il contient un contexte détaillé comme les règles de build, de test et de code, sans alourdir le README
  • Pourquoi un fichier séparé ?
    • Fournir aux agents un emplacement prévisible pour les instructions
    • Garder le README concis et centré sur les contributeurs humains
    • Fournir des instructions précises dédiées aux agents en complément de la documentation existante
  • Adoption d’un nom de standard ouvert que tout le monde peut utiliser, et non d’un format propriétaire
  • Un seul AGENTS.md permet une compatibilité avec plusieurs agents de codage IA et outils

How to use AGENTS.md?

  • 1. Créer le fichier AGENTS.md
    • Le placer à la racine du dépôt (de nombreux agents prennent en charge sa création automatique)
  • 2. Rédiger les sections principales
    • Vue d’ensemble du projet
    • Commandes de build et de test
    • Consignes de style de code
    • Méthode de test
    • Considérations de sécurité
  • 3. Ajouter des instructions supplémentaires
    • Tout ce que vous transmettriez à un membre de l’équipe : règles de commit/PR, précautions de sécurité, grands jeux de données, étapes de déploiement, etc.
  • 4. Gérer les monorepos
    • Il est possible de placer un AGENTS.md pour chaque package
    • Les agents lisent le fichier le plus proche et suivent les instructions adaptées au sous-projet concerné
    • Exemple : le dépôt d’OpenAI contient 88 fichiers AGENTS.md

FAQ

  • Éléments obligatoires : aucun, le format Markdown classique peut être utilisé librement
  • En cas de conflit : le fichier AGENTS.md le plus proche prévaut, et le prompt explicite de l’utilisateur s’applique en dernier ressort
  • Exécution automatique : les commandes de test indiquées dans le fichier peuvent être exécutées par l’agent pour tenter de corriger les erreurs
  • Possibilité de mise à jour : modifiable à tout moment, à gérer comme un document vivant
  • Migration depuis la documentation existante : conserver la compatibilité via un lien symbolique après changement de nom du fichier
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

À lire aussi

1 commentaires

 
GN⁺ 2025-08-21
Avis Hacker News

  • Pour les petits projets, un seul fichier .md suffit, mais d’expérience, pour les projets complexes, une structure de dossiers hiérarchique avec un index.md est bien plus efficace
    Une structure composée d’un index.md et de fichiers enfants comme auth.md ou performance.md est aussi plus facile à maintenir, et permet à un LLM ou à un agent d’extraire uniquement le contexte pertinent sans gaspiller inutilement des tokens
    Les fichiers .docs deviennent adaptés à la fois aux humains et aux LLM, et index.md peut aussi contenir de brèves indications sur chaque fichier ainsi qu’un guide d’organisation
    En revanche, un nom comme .agents me paraît moins bon que .codebots ou .context, qui sont plus intuitifs

    • Je ne pense pas qu’il soit nécessaire de cacher les fichiers et répertoires importants
      Surtout pour la documentation, la cacher la rend au contraire plus opaque ; c’est peut-être une habitude héritée de la tradition, mais ce n’est pas un bon modèle
      Je me demande si un nom comme robot_docs ne serait pas mieux

    • En réalité, ces informations recoupent ce que les contributeurs veulent savoir, donc je pense qu’elles devraient à l’origine aller dans CONTRIBUTING.md

    • Cette structure ressemble à une documentation de conception logicielle / guide de style de code pour humains et robots
      Moi, je mets ce type de fichiers .md dans le dossier docs/, rédigés directement par Claude Code
      AGENTS.md et CLAUDE.md devraient être réservés uniquement aux robots, et qu’on découpe un gros fichier unique en sections via des en-têtes h2 ou qu’on le répartisse en plusieurs fichiers, chaque approche a ses avantages et ses inconvénients
      Il existe aussi des formats de documentation d’architecture comme Arc42 qui prennent en charge les deux
      Plutôt que de référencer une section précise dans un gros Markdown, il est plus simple et moins sujet aux erreurs d’en faire un fichier séparé puis de le @mentionner
      Quand il faut se concentrer sur une partie précise, mieux vaut aussi pour les agents de code la découper en petits fichiers
      Les petits fichiers sont aussi plus pratiques pour les diff et les revues de PR

    • On peut aussi avoir plusieurs fichiers AGENTS.md dans une même codebase
      L’outillage pourrait lire à la fois le AGENTS.md du répertoire courant et celui de la racine, ce qui permettrait de garder l’information proche du code tout en restant compatible avec l’approche souhaitée

    • J’utilise moi aussi une structure similaire, et j’ai obtenu de très bons résultats en ajoutant à index.md une brève présentation de chaque fichier
      J’expérimente aussi une approche consistant à placer des fichiers de règles de comportement souhaité par répertoire, comme rules.md
      Par exemple, dans un répertoire qui regroupe différents services comme realtime-service.ts et queue-service.ts, j’ajoute un rules.md à côté
      On peut ensuite désigner ce fichier de règles dans le prompt pour générer facilement de nouvelles choses ; il faut encore réfléchir au nom

  • Nous sommes actuellement dans une phase transitoire où il faut écrire des guides spéciaux, au-delà de ce dont les humains ont besoin, pour aider les agents à comprendre la codebase
    Je pense que bientôt ce ne sera plus nécessaire
    Si la documentation de nos projets était dès le départ suffisamment complète, tout le contenu de AGENTS.md pourrait aussi s’y trouver
    Nous devons toujours écrire la documentation pour les humains, et l’avantage des LLM, c’est justement qu’ils peuvent lire ce qu’ont écrit les humains
    Je pense que c’est dans cette direction qu’il faut concevoir les choses

    • Ce n’est pas seulement utile pour comprendre la codebase, mais aussi pour expliciter certaines conventions de style précises (par exemple quelle bibliothèque d’assertions utiliser pour les tests, interdiction des commentaires, usage de logs structurés, etc.)
      Cela peut même être encore plus utile dans un nouveau projet avec très peu de code

    • Je m’attends à voir davantage de règles lisibles par machine apparaître partout dans la société
      On peut prendre l’exemple de la conduite autonome et du code de la route : des panneaux déjà difficiles à interpréter pour les humains selon le contexte (par exemple « virage à droite au feu rouge interdit, jours scolaires 7h–9h ») sont encore plus compliqués pour les machines
      À terme, les administrations devront soit réduire le besoin de contexte, soit adopter des signaux lisibles par machine (QR codes, etc.)
      Sans ce type de changement, les machines enfreindront souvent les règles

    • Dans des domaines comme la logique métier, je pense qu’il faudra toujours des indications spécifiques pour les agents
      Ce qu’on construit, l’intention, l’objectif final du projet : la machine ne peut pas le deviner sans qu’un humain ne le lui explique concrètement
      C’est aussi vrai pour l’architecture : comme chacun a ses propres critères, il faut avoir une représentation structurée en tête pour comprendre réellement les changements, et c’est au fond le vrai goulot d’étranglement

    • Je suis globalement d’accord, mais pour certaines informations (par exemple celles qu’on veut absolument injecter dans le contexte à chaque fois), on peut avoir envie de les forcer dans un fichier séparé

    • Si nous ne documentons pas les règles et hypothèses implicites que nous avons en tête, les LLM ne peuvent pas les connaître
      Ils peuvent en inférer une partie à partir du code, mais jamais à 100 %, donc il est important d’écrire explicitement les exigences

  • AGENTS.md, au fond, joue le même rôle que README.md, mais avec un aspect hype, et il est amusant de voir que les gens remplissent réellement son contenu
    Les gens hésitent à écrire de la documentation pour d’autres humains, mais pour les robots ils s’y mettent avec enthousiasme, ce qui est fascinant
    Cela me rappelle ces cas où un design ergonomique pensé pour une petite minorité finit par mieux convenir à tout le monde

    • C’est plutôt l’inverse : comme les gens ne lisaient pas la documentation, personne n’était motivé à l’écrire
      Un CLAUDE.md destiné aux agents, une fois écrit, sera bientôt lu par 1000 agents, donc on a davantage envie de l’écrire

    • Au fond, ne suffirait-il pas simplement de mettre le minimum dans README.md ?

    • En pratique, même les agents risquent de ne pas lire ce document, ou d’oublier tout son contenu après quelques instructions supplémentaires

    • La situation actuelle vient du fait que les gens essaient activement d’écarter les développeurs humains — eux compris — du processus de développement, ce qui rend indispensable un guidage adéquat des agents
      Parce qu’il y a un désir croissant d’éliminer toute implication humaine dans le développement logiciel

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. L’idée de sortir ce genre d’éléments dans un fichier séparé me donne vraiment le sentiment de ne plus comprendre dans quel monde on vit

  • En plaisantant, on dira que l’ambiance du moment est au vibe coding
    Il me semble aussi avoir déjà vu passer l’idée qu’écrire de la documentation pour les bots n’est au fond pas différent d’écrire une bonne documentation, tout court

  • Au final, on a l’impression qu’on dit simplement « créez un fichier AGENTS.md et remplissez-le de magie », puis qu’on renvoie vers un site externe

  • Dans mon cas, je développe un agent de code qui gère plus de 5 000 dépôts
    L’état de l’agent est stocké dans un répertoire caché .agent, avec des dossiers de configuration par rôle et des instructions clairement séparées selon le rôle
    Dans le dossier du projet, je place un répertoire agents où plusieurs fichiers sont répartis par rôle selon le modèle <Role> <instruction>
    L’agent ne lit que les fichiers correspondant au rôle défini, et l’état est conservé dans un dossier dot<coding agent name>
    L’initialisation se fait avec /init, et au lieu de simplement indexer tout le code du dépôt, on génère un résumé high-level de l’architecture et de la logique globale
    Ce résumé est fourni dans l’éditeur sous forme de « ghost comments » activables, une métadonnée non commitée dans le vrai code
    Un système de mapping sophistiqué relie précisément chaque résumé aux lignes de code correspondantes
    Au départ, je n’obtenais pas les résultats souhaités en appliquant directement le RAG au code, d’où cette structure actuelle
    Aujourd’hui, j’utilise un modèle de recherche hybride combinant une recherche syntaxique rapide basée sur l’AST et une exploration sémantique (RAG) fondée sur les résumés
    Par exemple, si on demande « comment fonctionne l’authentification de cette app ? », la recherche syntaxique ne trouvera que des fonctions contenant des mots comme login, alors que la recherche sémantique, via les résumés, reconstitue tout le flux d’authentification de manière narrative et relie des éléments dispersés dans plusieurs fichiers ; ça fonctionne presque comme par magie

    • Pour aller plus loin, on peut créer une hiérarchie de résumés (sous forme de B-tree ou d’arbre classique)
      Autrement dit, on a un résumé pour chaque méthode / classe / module, et chaque niveau pointe vers le niveau inférieur
      Le RAG peut alors descendre aussi profondément que nécessaire selon la requête sémantique, chaque étape résumant le niveau en dessous pour réduire la quantité d’information tout en conservant le sens essentiel
      Cette approche est particulièrement efficace quand le code présente de bonnes abstractions
      Par exemple, pour une fonction comme add(n1, n2), le nom suffit à transmettre le sens et il n’est pas nécessaire de connaître l’implémentation réelle, mais dans le monde réel les fonctions font souvent plusieurs choses — logs, cache, etc. — donc selon le contexte, il peut être nécessaire d’inclure aussi le code réel

    • J’aimerais beaucoup en savoir plus

  • On a l’impression que les humains sont lentement poussés à enfin rédiger correctement la documentation des projets

    • C’est une blague, mais c’est effectivement un argument que je mets en avant dans l’équipe
      Même si les LLM n’augmentaient pas énormément la productivité en pratique, ils ont au moins pour effet secondaire de nous pousser à bien mieux documenter

    • "Mission. Fucking. Accomplished." xkcd 810

  • Je ne suis toujours pas convaincu qu’il faille absolument séparer README.md et AGENTS.md

  1. le style de rédaction (les emphases en MAJUSCULES dans un document pour agents sont pénibles dans un document pour humains)
  2. concision contre exhaustivité (un document pour agents doit n’emporter que l’essentiel, alors qu’un document pour humains doit documenter le maximum de choses)
  3. la différence d’informations nécessaires (ce dont un LMM a besoin et ce qu’un humain considère comme important ne coïncident pas)
    La principale raison de ne pas les séparer serait :
  4. la gestion de la duplication (la charge de devoir écrire au même endroit deux versions de quelque chose d’essentiellement identique)

  • J’ai l’impression que README.md sert désormais un peu de page marketing / landing page, tandis que AGENTS.md et CLAUDE.md sont les endroits où l’on va chercher le vrai contenu sur le code, l’architecture et l’usage

  • En lisant les exemples, j’ai eu exactement la même impression, et je me demande si un bon README.md unique ne pourrait pas suffire

  • README est pour les humains, AGENTS.md et consorts sont pour les LLM
    Les instructions d’usage et d’installation vont dans le readme ; la compilation, les tests, les décisions d’architecture, les standards de code, la structure du dépôt, etc. vont dans les documents destinés aux agents

  • Il faut aussi penser au problème de capacité du contexte côté LLM
    README.md devient trop volumineux pour être injecté en entier dans le contexte
    Dans AGENT.md, on ne met donc de manière concise que les commandes essentielles pour le LLM, comme les tests et le build
    Il peut y avoir des recoupements avec le README, mais on veut éviter de retransmettre dans le contexte des contenus inutiles ou redondants

  • La promesse de l’IA, ce n’était pas justement qu’on n’aurait pas besoin d’être obsédés par un format précis, qu’on pourrait écrire comme on veut et que la machine s’adapterait ?

    • En pratique, seul le nom de fichier a été standardisé, et c’est probablement le bon choix : aucun format de contenu n’est imposé, chacun peut rédiger comme il veut
      AGENTS.md est un Markdown standard, donc on peut utiliser les titres que l’on veut, et l’agent analysera le texte

    • Malgré tout, un certain degré de structure et de forme garde de l’importance
      Même si on n’est pas au niveau de rigidité d’une syntaxe de code

    • Au final, tout se ramène à la nécessité d’écrire clairement le contenu
      Et plus la documentation s’allonge, plus une approche structurée devient avantageuse pour sa maintenance côté humain

  • Chaque agent utilisé (Claude Code, Gemini, Aider) a un nom de fichier différent
    Ce serait bien qu’il y ait une standardisation, mais pour l’instant j’accepte l’effort supplémentaire consistant à utiliser ruler pour générer automatiquement plusieurs formats
    En particulier, chaque agent consomme aussi différemment les fichiers de configuration MCP, donc je pense qu’une standardisation rapide sera difficile
    ruler

    • Si l’on veut être un peu cynique, on peut y voir une manière de créer du vendor lock-in
      Les entreprises semblent réticentes à la standardisation, sans doute parce qu’elle peut conduire à une forme de banalisation des produits

    • Jules utilise AGENTS.md, ce qui montre que Google adhère aussi à ce standard
      Si Gemini Code Assist continue d’être maintenu, on peut s’attendre à ce qu’il prenne lui aussi en charge AGENTS.md
      Je n’ai pas vu de nom de fichier spécifique mentionné dans la documentation d’Aider ; si tu as un lien, je veux bien
      Anthropic semble être le seul à ne pas encore prendre en charge un nom de fichier standard

    • C’est un peu regrettable qu’un outil comme ruler soit réellement nécessaire

  • Ce site web a quelque chose d’étrange
    Je me demande s’il a été créé par OpenAI pour attirer des visiteurs et se positionner sur le plan marketing
    En réalité, il ne définit aucun format, seulement un nom de fichier
    L’absence d’Anthropic / Claude se remarque aussi ; on pourrait à la rigueur utiliser un lien symbolique pour faire pointer CLAUDE.md vers AGENTS.md

    • En fait, il a été créé par Sourcegraph et existe depuis mai
      Auparavant, c’était agent.md, et maintenant le site redirige en 301 vers agents.md
      Voir l’ancien lien
      Il y a aussi l’annonce officielle
      Ils semblent avoir conclu récemment un partenariat avec OpenAI
      Fait intéressant, c’était au départ agent.md, puis c’est devenu agents.md

    • Si Claude n’apparaît pas dans la liste, c’est simplement parce que Claude ne prend pas encore en charge une convention standard de nom de fichier