Votre README est pour les humains. Votre AGENTS.md est pour les agents de codage

Pourquoi un AGENTS.md séparé est important

Les développeurs s'appuient depuis longtemps sur les fichiers README pour communiquer l'objectif du projet, les instructions d'installation et les lignes directrices de contribution aux lecteurs humains. Bien que cela reste essentiel, les flux de travail de développement modernes impliquent de plus en plus des agents de codage alimentés par l'IA qui ont besoin d'un type de documentation différent. Un fichier AGENTS.md comble ce fossé en fournissant à l'agent le contexte, les contraintes et les limites opérationnelles que les humains comprennent intuitivement à partir d'un README, mais que les machines ne peuvent pas déduire du seul langage naturel.

Contrairement à un humain, un agent ne possède pas d'expérience de vie, de bon sens ni la capacité de poser des questions de clarification. Il fonctionne sur la base de modèles qu'il a observés lors de son entraînement et des instructions explicites que vous lui donnez. En créant un AGENTS.md dédié, vous transférez la responsabilité de l'interprétation de l'intention de l'agent vers un format structuré et lisible par la machine. Cette séparation garde votre README propre pour les humains tout en garantissant que l'agent reçoit les directives précises dont il a besoin pour agir efficacement et en toute sécurité.

Que doit-on inclure dans votre AGENTS.md

Commencez par une vue d'ensemble concise du projet qui capture le domaine de l'agent : ce que fait la base de code, ses flux de données principaux et toutes les dépendances externes avec lesquelles il doit interagir. Cette description de haut niveau aide l'agent à formuler ses attentes avant de plonger dans les détails de la mise en œuvre.

Ensuite, définissez les conventions de codage. Énumérez les conventions de nommage préférées, les normes de formatage et tous les idiomes spécifiques au langage que votre équipe suit. Incluez une brève note sur la philosophie de test, les attentes en matière de couverture et la manière dont l'agent doit gérer les cas limites. Une référence rapide à vos outils de linting, de formatage et d'analyse de sécurité empêche l'agent de générer du code qui échouerait ensuite aux vérifications automatisées.

Fournissez une section intitulée « Commandes et outils autorisés ». Énumérez ici les utilitaires CLI, les API et les SDK que l'agent peut invoquer, ainsi que les limites de débit ou les exigences d'authentification. Si le projet utilise une gestion des secrets, décrivez le processus pour référencer les variables d'environnement ou les fichiers de configuration. Enfin, décrivez les limites et contraintes : les répertoires en lecture seule, les fichiers qui ne doivent pas être modifiés et toutes les règles réglementaires ou de conformité qui s'appliquent à la base de code. Des limites claires protègent à la fois le projet et l'utilisateur contre les effets secondaires involontaires.

Écrire pour la machine

Gardez le langage direct et impératif. Utilisez des puces pour les listes de commandes ou d'extraits de configuration, et étiquetez chaque élément avec un tag de courte description. Par exemple :

• Installation – Installer les dépendances via pip install -r requirements.txt
• Exécuter les tests – Exécuter pytest --cov=src pour vérifier les modifications
• Déployer – Utiliser aws s3 sync dist/ bucket/ --exclude '*.tmp' pour les mises en production

Évitez les formulations ambiguës telles que « essayez de » ou « si possible ». Remplacez-les par des instructions concrètes comme « invoquer build.sh avant de valider ». Incluez une sous-section « Dépannage » qui répertorie les erreurs courantes de l'agent et les actions correctives correspondantes, permettant à l'agent de se corriger sans intervention humaine.

N'oubliez pas de versionner votre AGENTS.md en même temps que le reste du dépôt. À mesure que le projet évolue, mettez à jour le fichier pour refléter les nouveaux outils, les scopes étendus ou les contraintes modifiées. Un AGENTS.md vivant garantit que chaque nouvelle génération d'agents hérite des lignes directrices opérationnelles les plus à jour.

En traitant l'AGENTS.md comme un contrat entre votre équipe de développement et l'assistant IA, vous gagnez en cohérence, en sécurité et en productivité. L'agent peut se concentrer sur l'écriture du code, tandis que vous conservez le contrôle sur la direction générale et la qualité du travail.

Pour aller plus loin : https://dev.to/johnnylemonny/your-readme-is-for-humans-your-agentsmd-is-for-coding-agents-16kg