Comment rédiger un fichier AGENTS.md ou CLAUDE.md?

Un agent de programmation commence chaque tâche sans rien savoir de votre projet. Il peut lire le code, mais il ne peut pas deviner que les tests se lancent avec une commande précise, qu’un dossier est généré et ne doit pas être modifié, ou que votre équipe rédige ses messages de commit d’une certaine façon. Un fichier d’instructions règle ce problème. Claude Code charge automatiquement un fichier appelé CLAUDE.md dans son contexte au début d’une session. Codex d’OpenAI lit les fichiers AGENTS.md du dépôt dans le même but. Voyez l’un ou l’autre comme un README écrit pour l’agent plutôt que pour un nouveau collègue.

Aucun des deux fichiers n’a de format obligatoire. Anthropic recommande de garder CLAUDE.md concis et lisible par des humains, et OpenAI décrit AGENTS.md comme un fichier texte qui ressemble beaucoup à un README. Du Markdown ordinaire, avec de courts intertitres et des listes à puces, fonctionne bien pour les deux.

Ce qu’on y met

La liste de contenus utiles d’Anthropic fait une bonne liste de vérification pour l’un ou l’autre fichier :

• Aperçu du projet : deux ou trois phrases sur ce que fait le code et sur son organisation.
• Commandes : comment installer, compiler, tester, analyser le style (lint) et vérifier les types, écrites exactement comme vous les taperiez.
• Style de code : les conventions qui comptent et qu’un analyseur de code n’impose pas déjà.
• Consignes de test : quels tests lancer, et quand.
• Usages du dépôt : noms de branches, messages de commit, descriptions des demandes de fusion (pull requests).
• Mises en garde : tout ce qui pourrait surprendre, comme un test lent, un dossier généré ou un fichier qui ne doit pas changer.

Un exemple concret

Voici un fichier complet pour une petite application Web imaginaire, un calendrier d’événements pour un site touristique régional. Tous les noms et toutes les commandes sont donnés à titre d’illustration; utilisez les vôtres.

# Project
Calendrier d'événements pour un site Web touristique régional. Python 3.12, Flask, SQLite.
- app/        routes Web et gabarits
- app/models  modèles de la base de données
- tests/      tests pytest
- static/gen/ GÉNÉRÉ par le script de compilation : ne jamais modifier à la main

# Commands
- Installer : pip install -r requirements.txt
- Lancer en local : flask --app app run
- Tout tester : pytest
- Tester un seul fichier : pytest tests/test_events.py
- Analyser le style : ruff check .

# Rules
- Chaque page doit fonctionner en français et en anglais; le texte va dans app/i18n/, jamais codé en dur.
- Les dates sont stockées en UTC et affichées à l'heure locale.
- Écrire ou mettre à jour un test pour chaque correction de bogue.
- Ne pas ajouter de nouvelles dépendances sans demander.

# Before you finish
- Lancer ruff check . et pytest; les deux doivent réussir.
- Messages de commit : court résumé à l'impératif, par exemple "Corrige le filtre de date de la liste d'événements".

# Secrets
- Les clés et les mots de passe sont dans des variables d'environnement (voir .env.example pour les noms).
- Ne jamais afficher, journaliser ni committer leurs valeurs.

Enregistrez-le sous le nom AGENTS.md, CLAUDE.md ou les deux (voir plus bas). La section « Before you finish » (avant de terminer) vaut la peine : le message système de Codex publié par OpenAI dit à l’agent que, lorsqu’un fichier AGENTS.md contient des vérifications programmatiques, il doit toutes les lancer après avoir fait ses modifications.

Où le placer, et jusqu’où il s’applique

Les deux outils vous permettent d’utiliser plus d’un fichier.

• Claude Code lit le CLAUDE.md à la racine de votre dépôt (faites-en le commit pour que toute l’équipe le partage), les fichiers des dossiers parents, les fichiers des sous-dossiers quand il y travaille, et un ~/.claude/CLAUDE.md personnel qui s’applique à tous vos projets. Un CLAUDE.local.md, tenu à l’écart de Git, contient les notes personnelles. La commande /init vous en rédige une première version, et appuyer sur # pendant une session ajoute une consigne au fichier.
• Codex suit les règles du message système publié : un fichier AGENTS.md s’applique à toute l’arborescence du dossier où il se trouve, le fichier le plus profondément imbriqué l’emporte en cas de consignes contradictoires, et les consignes directes de votre prompt ont priorité sur le fichier.

Pour servir les deux agents dans un même projet, gardez une source unique. Une approche simple : mettez tout le contenu dans AGENTS.md, et faites de CLAUDE.md une note d’une ligne qui demande à l’agent de lire et de suivre AGENTS.md. Vérifiez que chaque outil la suit vraiment avant de compter sur cet arrangement.

Le garder efficace

Anthropic suggère de traiter le fichier comme n’importe quel prompt que vous utilisez souvent : raffinez-le, voyez ce qui améliore le comportement de l’agent et retranchez ce qui ne sert pas. Ses ingénieurs ajoutent parfois de l’emphase, comme « IMPORTANT », aux règles qui étaient ignorées. Une habitude pratique : quand l’agent fait deux fois la même erreur, ajoutez une ligne claire au fichier, et quand une ligne est périmée, supprimez-la. Un fichier court et exact vaut mieux qu’un long fichier à moitié dépassé.

Que ne faut-il jamais y mettre?

Des secrets, d’abord. Pas de clés d’API, de mots de passe, de jetons d’accès, de chaînes de connexion à une base de données contenant des identifiants, ni de certificats privés. Le fichier est fait pour être versé dans Git, et les conseils d’OpenAI sur la sécurité des clés notent que les verser dans le code source est une façon courante de les laisser fuir, surtout dans les dépôts publics, même si les dépôts privés peuvent aussi être exposés. Le fichier est également chargé dans le contexte du modèle à chaque tâche. Nommez les variables d’environnement que le code attend, comme dans l’exemple, et gardez les valeurs hors du dépôt.

Les données personnelles ou celles des clients doivent aussi rester à l’écart : vrais noms de clients, adresses courriel, numéros de téléphone ou extraits d’une base de données de production. Si l’agent a besoin de données d’exemple, dirigez-le vers un dossier de données de test contenant des fiches inventées.

Laissez de côté les consignes qui affaiblissent la sécurité, comme « toujours sauter les vérifications de permission » ou « pousser directement sur main ». Anthropic prévient que laisser Claude Code lancer des commandes sans vérification de permission expose à des pertes de données et à des attaques cachées dans le contenu qu’il lit, et conseille de ne le faire que dans un conteneur sans accès à Internet. Une décision aussi importante relève de la façon dont vous lancez l’outil, pas d’un fichier que chaque session lit par défaut.

Enfin, évitez tout ce que vous ne voudriez pas qu’un nouveau coéquipier lise à sa première journée. Si ce serait déplacé dans le README, c’est déplacé ici.