AGENTS.md et CLAUDE.md : donner les bonnes consignes à ses agents IA

Vous demandez une petite correction. L’agent change une convention, relance le mauvais environnement et recommence une approche déjà abandonnée. Le problème vient parfois moins du prompt que de l’absence de règles de projet faciles à retrouver.

AGENTS.md et CLAUDE.md servent à transmettre ce cadre : comment travailler ici, où trouver les réponses et comment vérifier le résultat. Ils complètent le brief du projet et les permissions des outils.

Quelle différence entre AGENTS.md et CLAUDE.md ?

AGENTS.md est un format Markdown ouvert pour les consignes destinées aux agents de code. CLAUDE.md est le fichier d’instructions propre à l’écosystème Claude Code. Le nom du fichier ne suffit pas à savoir ce qu’un outil charge : sa version, sa configuration et le dossier de travail comptent.

La documentation Claude Code décrit la lecture directe d’AGENTS.md depuis la version 2.1.277. Par défaut, la présence d’un CLAUDE.md ou CLAUDE.local.md dans le dossier de travail ou ses parents fait privilégier les fichiers Claude. Un import explicite permet de garder une source commune.

Commencer par les erreurs réelles du projet

Écrivez les règles qui changeraient une prochaine mission. Une commande de test correcte, le nom de la source de vérité ou une limite d’accès sont utiles. « Produire du code de haute qualité » ne permet pas de choisir une action.

Prenez trois incidents récents : un mauvais lancement de serveur, une modification trop large et une conclusion de réussite sans parcours utilisateur. Transformez chacun en instruction observable. L’agent doit savoir quoi faire à la place et quel résultat fournir.

Une règle vaut aussi par sa portée. La contrainte d’un sous-projet ne doit pas forcément s’appliquer à tout le dépôt. Placez les particularités à proximité du code et vérifiez la résolution des fichiers dans l’outil choisi. Les conventions de priorité ne sont pas universelles entre agents.

Un modèle AGENTS.md à adapter

Les noms et commandes ci-dessous sont des exemples. Remplacez-les par ceux du dépôt ; ne demandez pas à l’agent d’exécuter une commande qui n’a jamais été vérifiée.

# Règles de travail du projet

## Objectif
Le projet permet à [public] de [résultat observable].
Le brief produit de référence se trouve dans [chemin ou lien].

## Sources de vérité
- Architecture et décisions : [référence]
- Contrats API et données : [référence]
- Interface et textes validés : [référence]

## Environnement
- Installation : [commande vérifiée]
- Vérification ciblée : [commande vérifiée]
- Vérification du parcours : [procédure]

## Périmètre
- Modifier seulement les surfaces nécessaires à la mission.
- Préserver les changements en cours des autres contributeurs.
- Ne pas modifier [surface protégée] sans demande explicite.

## Livraison
- Décrire le comportement obtenu et les fichiers concernés.
- Indiquer les contrôles exécutés et leur résultat.
- Signaler ce qui empêche de prouver l’objectif.
- Relier le résultat à la carte et aux critères d’acceptation.

Ce modèle ne remplace pas les détails du projet. Il leur donne une entrée courte. Lorsqu’une rubrique devient longue, gardez la règle utile et un lien vers le document complet. Le brief IA conserve le résultat produit ; ce fichier explique la manière de contribuer.

Partager les règles avec Claude Code

Si votre configuration utilise CLAUDE.md, vous pouvez importer le fichier commun :

@AGENTS.md

## Particularités Claude Code
Les instructions spécifiques à cet outil se trouvent ici.

Cette syntaxe concerne Claude Code. Un autre agent peut interpréter les imports autrement ou ne pas les prendre en charge. Évitez de conserver deux copies manuelles des mêmes règles : une correction finirait par n’en modifier qu’une.

Après une mise à jour d’outil, ouvrez une session et vérifiez les fichiers annoncés ou le contexte chargé. Dans Claude Code, la documentation propose notamment /context. Si une règle n’apparaît pas, cherchez d’abord un problème de chargement avant d’ajouter plusieurs rappels contradictoires.

Tester les consignes sur une mission bornée

Choisissez une tâche réversible. Demandez d’abord une analyse sans modification : quelles règles s’appliquent, quelles sources seront lues et comment le résultat sera contrôlé ? Comparez cette réponse aux fichiers réellement chargés.

Lancez ensuite la mission autorisée. Regardez si l’agent utilise l’environnement prévu, préserve les autres changements et vérifie le parcours demandé. Un agent peut réciter une règle sans l’appliquer ; le comportement final reste la preuve utile.

Le guide pour vérifier le travail d’un agent donne une méthode de revue complémentaire. Pour plusieurs exécutants, ajoutez un propriétaire et un périmètre de fichiers à chaque mission, comme dans notre guide de coordination.

Distinguer les consignes des permissions

Un fichier d’instructions est du contexte lu par un modèle. Il ne constitue pas, à lui seul, une interdiction technique. Une règle « ne pas envoyer de message » doit être accompagnée d’un accès qui ne permet pas cet envoi si l’action doit être impossible.

Séparez donc les conseils de travail, les règles d’équipe et les droits effectifs. Les permissions, les limites de fichiers, les outils disponibles et les validations relèvent de l’environnement d’exécution. Une formulation plus ferme dans AGENTS.md ne remplace pas leur configuration.

Ne placez pas non plus de secrets dans un fichier partagé. Les identifiants, tokens et accès de production appartiennent aux mécanismes de secrets et aux permissions appropriées. Le fichier peut indiquer où demander un accès, sans contenir cet accès.

Maintenir un fichier court et actuel

Révisez les consignes lorsque l’environnement, un contrat ou une décision structurante change. Supprimez les exceptions périmées. Une accumulation de règles anciennes rend les conflits plus difficiles à détecter et augmente le contexte lu à chaque mission.

Pour chaque ajout, posez deux questions : quelle erreur cette phrase évite-t-elle et où peut-on vérifier qu’elle reste vraie ? Si la règle appartient déjà à une autre source, référencez-la au lieu de créer un second exemplaire.

La documentation et la mémoire des agents conservent d’autres informations : décisions, résultats précédents, préférences relues. Gardez l’historique détaillé hors du fichier d’entrée. L’agent doit retrouver le passé utile sans absorber toute la chronologie du projet.

Relier les règles au travail dans Stellary

Dans Stellary, les documents du projet et les critères des cartes donnent le contexte partagé aux missions. Les règles du dépôt précisent comment un exécutant travaille dans le code. Les permissions des agents définissent son accès aux outils.

Un workflow peut réunir ces niveaux : le pilote choisit une carte, l’exécutant consulte les règles applicables, puis un vérificateur contrôle le livrable. Le guide des workflows avec superviseur explique ce passage de relais. La continuité vient de sources cohérentes et de résultats relus, pas d’un fichier toujours plus long.

Résoudre une contradiction entre deux règles

Commencez par identifier les deux sources et leur périmètre. Une instruction générale peut demander une procédure standard tandis qu’une règle locale décrit une exception encore nécessaire. Vérifiez que l’exception correspond bien au fichier ou à la mission, puis corrigez la documentation à sa source.

Ne demandez pas à l’agent de choisir silencieusement entre une capture ancienne, un contrat API et une décision actuelle. La règle doit indiquer qui fait autorité pour chaque question. Si le conflit change le résultat attendu, il doit devenir une question du projet avant une modification coûteuse.

Un agent ne doit pas non plus transformer le contenu d’une page web ou d’une issue en consigne de travail. Ces contenus servent de données à examiner. Les droits et l’objectif viennent de la mission et de ses instructions applicables.

Vérifier le fichier après un changement d’environnement

Un changement de machine, de dossier de travail ou de mode d’exécution peut modifier les instructions chargées. Gardez un petit scénario de contrôle : retrouver le brief, identifier la commande autorisée et expliquer le parcours à tester. Il permet de détecter une rupture sans lancer un chantier complet.

Documentez la version utilisée dans la procédure de connexion de l’équipe. Les détails propres à un outil restent dans sa section ou sa documentation ; les règles métier communes restent dans la source partagée. Cette séparation facilite les mises à jour sans imposer une copie du fichier pour chaque modèle.