CLAUDE.md et AGENTS.md : donner ses règles à l'agent IA

À quoi servent CLAUDE.md et AGENTS.md ?

CLAUDE.md pour Claude Code et AGENTS.md pour Codex sont des fichiers Markdown que l’agent lit avant de travailler. Ils lui donnent l’objectif du projet, la stack, les commandes de build et de test, les interdits et la définition de « terminé ». Dix lignes précises suffisent à éviter les erreurs de débutant les plus coûteuses.

CLAUDE.md est un fichier Markdown placé à la racine du projet, lu automatiquement par Claude Code au début de chaque session source : Anthropic Academy, 2026. AGENTS.md est son équivalent pour Codex, qui construit une chaîne d’instructions au démarrage de chaque exécution source : OpenAI, 2026.

Ces fichiers sont du texte libre : aucune syntaxe imposée, aucun champ obligatoire. L’agent les lit comme des consignes écrites. Ce tutoriel s’adresse à ceux qui démarrent un site ou une application avec l’un de ces deux outils.

Prérequis

• Claude Code ou Codex installé (voir le guide de démarrage de Claude Code ou celui de Codex).
• Un projet versionné avec Git.
• Les commandes d’installation, de build et de test du projet, testées à la main au moins une fois.

Étape 1 : crée le fichier au bon endroit

Crée le fichier à la racine du dépôt, puis versionne-le : toute l’équipe en profite, et Anthropic recommande ce commit.

Côté Codex, la documentation officielle précise le chargement. Il part de la racine du projet et descend jusqu’au répertoire courant. Dans chaque dossier, il cherche d’abord AGENTS.override.md, puis AGENTS.md, puis des noms de repli configurables. Les autres noms sont ignorés. Le cumul des fichiers est plafonné à 32 KiB par défaut source : The Prompt Shelf, 2026, et au-delà les fichiers les plus spécifiques risquent d’être tronqués.

Étape 2 : écris l’objectif et la stack

Deux à quatre lignes suffisent : ce que le projet doit faire, pour qui, en quelle langue, avec quelles technologies. Indique le framework et sa version, pour que l’agent ne propose pas un autre outil en cours de route. Ajoute une phrase qui interdit les nouvelles dépendances sans demande.

Étape 3 : donne les commandes et définis « terminé »

Liste les commandes exactes : installation, lancement local, build, lint, test. Sans elles, l’agent les devine, et un agent qui devine invente.

La définition de « terminé » compte autant. Chez Peechy, le fichier de règles que nous donnons à Claude Code contient notamment ces cinq consignes :

• toujours une branche, jamais de commit direct sur la branche principale ;
• toute suppression se confirme avant d’être lancée ;
• une clé manquante arrête le travail avec une demande précise, jamais une valeur factice ;
• « terminé » veut dire build passé et comportement observé ;
• un test rouge accuse le code, pas le test.

Chacune répond à une erreur de débutant classique. Sans la première, l’agent modifie la branche principale et le site de production s’en ressent. Sans la deuxième, il supprime un dossier qu’il juge inutile. Sans la quatrième, il annonce « c’est fait » sans avoir rien exécuté. D’autres pièges du même type sont décrits dans les erreurs à éviter avec Claude Code ou Codex et dans les risques de sécurité du vibe coding.

Étape 4 : copie ce modèle et adapte-le

Ce modèle est générique : remplace les crochets par les valeurs de ton projet.

# Projet
Site [type] pour [activité], en français. Objectif : [une phrase].

## Stack
[framework et version], [langage], [style]. Aucune nouvelle dépendance sans demande.

## Commandes
- Installer : [commande]
- Lancer en local : [commande]
- Build : [commande]
- Tests : [commande]

## Règles
- Travaille toujours sur une branche, jamais de commit direct sur la branche principale.
- Demande confirmation avant toute suppression de fichier ou de dossier.
- Si une clé ou une variable manque, arrête-toi et indique laquelle : jamais de valeur factice.
- Ne dis « terminé » qu'après un build réussi et le comportement observé.
- Si un test échoue, corrige le code, pas le test.
- Ne jamais écrire de secret dans ce fichier ni dans le code.

Aucune source publique ne chiffre l’effet de telles règles. Le plus honnête est de tester toi-même : lance la même tâche sur un petit dépôt avec et sans le fichier, et compare.

Étape 5 : vérifie que l’agent le lit

Pour Codex, la documentation officielle propose cette commande depuis la racine du dépôt : codex --ask-for-approval never "Summarize the current instructions.". Elle affiche les consignes dans leur ordre de précédence. Codex construit la chaîne une fois par exécution, donc relance une session après chaque modification.

Pour Claude Code, la commande /memory ouvre les fichiers en édition, d’après un guide tiers. Demande aussi à l’agent de résumer ses règles, et vérifie qu’il cite les tiennes. Pour aller plus loin dans la configuration, voir comment ajouter des Skills à Claude et Claude Code.

Pièges courants

• Mettre des secrets dans le fichier. CLAUDE.local.md est ajouté au .gitignore selon BuildCamp, mais il reste du texte en clair. Une clé d’API n’a sa place dans aucun de ces fichiers.
• Écrire un pavé. Un guide recommande de rester sous environ 200 lignes par fichier, avec des règles assez précises pour être vérifiables source : ClockedCode, 2026. Côté Codex, la limite de 32 KiB peut tronquer la fin.
• Rester vague. « Code propre » ne se vérifie pas ; « le build passe sans avertissement » se vérifie.
• Se contredire d’un niveau à l’autre. Pour Claude Code, les guides tiers divergent : concaténation des fichiers pour l’un, « le plus spécifique prime » pour l’autre. Évite les règles opposées entre fichier global, projet et sous-dossier.
• Mal nommer le fichier. Codex ignore tout nom absent de sa liste, par exemple TEAM_GUIDE.md sans configuration de repli.

Ouvre ton dépôt, colle le modèle, remplace les crochets et lance une première tâche : tu verras en dix minutes si l’agent respecte tes règles.