Guide

Que mettre dans AGENTS.md et CLAUDE.md ?

Que mettre dans AGENTS.md et CLAUDE.md d’après les benchmarks d’agents : commandes utiles, contraintes opérationnelles, pièges coûteux et ce qu’il faut omettre.

Un fichier d’instructions de dépôt peut vite devenir à la fois un README compressé, un essai sur l’architecture et une liste de beaux principes d’ingénierie. L’agent reçoit alors tout ce contenu à chaque tâche — même quand l’essentiel n’a rien à voir avec elle.

Les résultats récents des benchmarks suggèrent un rôle plus restreint pour ces fichiers. Utilisez AGENTS.md et CLAUDE.md comme de courts manuels d’exploitation : commandes exactes, opérations coûteuses, étapes de vérification, limites et faits difficiles à déduire du code. N’attendez pas d’une description de projet plus longue qu’elle apporte un jugement d’ingénierie que le modèle n’a pas déjà.

Réponse rapide

Placez un fait dans le fichier d’instructions racine quand les trois conditions suivantes sont réunies :

  1. Il s’applique à la plupart des travaux dans ce périmètre.
  2. L’agent ne peut pas le découvrir rapidement et de façon fiable à partir du dépôt.
  3. Le suivre change une action ou une vérification observable.

Voici de bons exemples :

  • pnpm test --filter api est la commande de test rapide pour les modifications de l’API.
  • La suite d’intégration complète prend 25 minutes et ne doit tourner qu’une fois, après la réussite des tests ciblés.
  • Les fichiers sous generated/ doivent être modifiés via pnpm generate.
  • Ajouter une dépendance de production ou modifier une migration de base de données nécessite une confirmation.
  • Une modification n’est pas terminée tant que la vérification de types et le test ciblé pertinent ne passent pas.

Laissez de côté les déclarations générales du type « écris du code propre », les listes de paquets recopiées et les descriptions que l’agent peut obtenir en lisant le manifeste et l’arborescence des sources. Utilisez un prompt de tâche pour les exigences ponctuelles, un skill pour une procédure à la demande, et des tests, des hooks ou la CI pour les règles qui doivent être appliquées mécaniquement.

AGENTS.md et CLAUDE.md se ressemblent, sans être identiques

Les deux fichiers fournissent des instructions persistantes au niveau du dépôt, mais leurs règles de découverte et de portée dépendent de l’agent qui les lit.

AGENTS.md de Codex CLAUDE.md de Claude Code
Fichier racine du projet AGENTS.md CLAUDE.md ou .claude/CLAUDE.md
Réglages personnels par défaut ~/.codex/AGENTS.md ~/.claude/CLAUDE.md
Consignes plus spécifiques AGENTS.md imbriqué ou AGENTS.override.md CLAUDE.md imbriqué ou règles .claude/rules/ limitées à des chemins
Combinaison des fichiers Chaîne allant de la racine au répertoire de travail ; les fichiers les plus proches s’appliquent en dernier Les fichiers parents se chargent au lancement ; les fichiers imbriqués se chargent quand Claude travaille dans ce sous-arbre
Recommandations de taille actuelles Limite de découverte combinée de 32 Kio par défaut Anthropic recommande moins de 200 lignes par fichier

Codex construit sa chaîne d’instructions une fois par exécution ou par session TUI lancée. Il consulte les consignes globales, puis parcourt l’arborescence de la racine du projet jusqu’au répertoire de travail courant. Un fichier plus proche apparaît plus loin dans le prompt combiné et prime donc sur les consignes plus générales. L’ordre de découverte exact et le fonctionnement des surcharges sont décrits dans la documentation AGENTS.md de Codex.

Claude Code traite CLAUDE.md comme du contexte plutôt que comme une configuration imposée. Sa documentation recommande des instructions précises et concises, et explique que des fichiers volumineux ou contradictoires sont moins bien respectés. Voir Comment Claude mémorise votre projet.

Si une équipe utilise les deux agents, gardez les instructions partagées dans AGENTS.md et importez-les depuis un petit CLAUDE.md :

@AGENTS.md

## Claude Code only

- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.

Anthropic documente explicitement ce schéma d’import. Un lien symbolique peut aussi fonctionner, mais l’import laisse de la place pour quelques consignes propres à Claude et se révèle plus portable sous Windows.

Ce qu’a testé la dernière étude portant sur deux agents

La prépublication de juillet 2026 Do Context Files Help Coding Agents? a transformé des pull requests fusionnées de trois dépôts Python — PDM, firebase-admin-python et opshin — en 17 tâches de codage. La description de la PR servait de prompt, tandis que les tests introduits par la vraie PR restaient cachés et servaient à juger l’implémentation de l’agent.

Claude Code et Codex ont chacun travaillé dans trois conditions :

  • aucun (none) : pas de fichier de contexte du dépôt ;
  • permanent (always on) : le fichier AGENTS.md complet était inséré à chaque tour ;
  • sélectif (selective) : l’agent recevait une indication et pouvait lire au besoin des fichiers de wiki organisés par thème.

Après trois répétitions, 288 exécutions disposaient d’un résultat d’exactitude valide :

Stratégie Claude Code Codex
Sans contexte 53,3 % 58,8 %
Permanent 55,6 % 56,9 %
Sélectif 55,6 % 52,9 %

Les différences n’étaient pas statistiquement significatives. Lors de la revue manuelle menée par les auteurs, les quasi-réussites échouaient à cause de la conception de la fonctionnalité, du choix de pattern ou d’un mauvais câblage — et non faute d’un fait sur le dépôt que le vrai AGENTS.md aurait contenu. Ajouter ou réorganiser ce contexte n’a pas transformé ces échecs en réussites.

Ce résultat ne prouve pas que les fichiers d’instructions n’améliorent jamais l’exactitude. L’échantillon ne comprend que trois dépôts Python et 15 à 17 tâches par agent. Selon l’analyse de puissance de l’article, détecter un effet de 10 points de pourcentage nécessiterait environ 120 à 200 tâches. L’étude a en outre testé une injection plus forte et artificielle, au lieu de simplement laisser le fichier à son emplacement naturel dans l’espace de travail : Claude recevait un ajout à son prompt système, tandis que Codex recevait un texte placé avant le prompt de l’utilisateur.

La condition sélective présente une autre limite. Son wiki ne correspondait au fichier AGENTS.md d’origine que pour opshin ; les deux autres dépôts ont reçu des wikis générés plus larges, environ 10 et 18 fois plus longs. La récupération sélective ne constitue donc pas une comparaison rigoureuse du même contenu fourni autrement.

Le résultat utile était opérationnel

Le fichier AGENTS.md d’opshin précise que la suite de tests complète prend plus de 20 minutes. Sans cet avertissement, Claude a lancé la suite entière en moyenne 3,67 fois par cellule. Avec le contexte permanent, 2,44 fois ; avec le contexte sélectif, 1,67. La durée d’exécution moyenne est passée de 2 689 secondes à 2 066 et 2 032 secondes — soit une réduction d’environ 24 % — sans amélioration correspondante de l’exactitude.

C’est un bon argument en faveur d’un type précis d’instruction : indiquer à l’agent le coût d’une action et lui donner un chemin correct moins coûteux. Ce n’est pas une preuve générale d’exécution plus rapide. L’analyse était exploratoire, ne portait que sur Claude dans un seul dépôt et manquait de puissance statistique avec cinq tâches. La durée pour Codex est restée stable, et un autre dépôt a légèrement évolué dans le sens inverse.

La conclusion prudente est la suivante :

Un fichier d’instructions de dépôt peut améliorer la façon dont un agent travaille, même s’il n’améliore pas ce que l’agent est capable de résoudre.

Les autres données sont mitigées

Deux études antérieures de 2026 sont arrivées à des résultats différents en matière d’efficacité :

  • On the Impact of AGENTS.md Files a étudié 10 dépôts et 124 pull requests. La présence d’un fichier AGENTS.md était associée à une durée d’exécution médiane inférieure de 28,64 % et à 16,58 % de jetons de sortie en moins, avec un taux d’achèvement comparable.
  • Evaluating AGENTS.md a testé des fichiers générés et des fichiers écrits par des développeurs, avec différents agents et modèles. L’étude n’a trouvé aucune amélioration générale du taux de réussite des tâches, et un coût d’inférence supérieur de plus de 20 % en moyenne, même si les agents suivaient bien les instructions non standard.

Le nouvel article sur deux agents suggère que des mécanismes d’injection différents et une difficulté des tâches propre à chaque agent pourraient expliquer cette contradiction. C’est une hypothèse, pas une réconciliation établie. Au vu des trois articles, la pratique la plus défendable consiste à juger un fichier sur les comportements qu’il change, plutôt que de supposer que davantage de contexte vaut forcément mieux.

Ce qui a sa place dans un fichier de contexte utile

Les commandes exactes et le chemin rapide

Donnez des commandes prêtes à l’emploi, avec le bon répertoire de travail et les options utiles. Distinguez la vérification ciblée de la suite finale coûteuse :

## Verification

- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.

« Lance les tests » n’apporte pas grand-chose. Nommer la bonne commande, son coût et l’ordre d’exécution évite à l’agent de deviner.

Des limites accompagnées d’une raison ou d’une alternative sûre

Consignez les zones non évidentes que l’agent ne doit pas modifier directement :

## Boundaries

- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.

Un chemin sûr est plus utile qu’une simple interdiction.

Les invariants propres au dépôt

Incluez les conventions importantes, surprenantes et non appliquées mécaniquement. Par exemple : une règle inhabituelle de correspondance des erreurs, une exigence de compatibilité que les tests ne couvrent pas, ou le seul service qui doit utiliser une commande différente.

Placez les faits propres à un service dans un fichier d’instructions imbriqué ou dans une règle limitée à un chemin. Charger les détails du frontend dans chaque tâche backend consomme du contexte et augmente le risque de conflits.

Les erreurs récurrentes, pas les erreurs hypothétiques

Ajoutez une règle quand un agent répète la même erreur coûteuse ou qu’une revue met au jour un fait qu’il ne pouvait raisonnablement pas déduire. Supprimez la règle quand le dépôt ou l’outillage la rend obsolète. Le fichier reste ainsi ancré dans des échecs observés au lieu d’accumuler des conseils spéculatifs.

Ce qu’il faut laisser de côté

  • Les personas génériques : « Tu es un ingénieur senior » n’a pas été évalué directement par ces études, mais ne fournit ni action vérifiable ni fait sur le dépôt.
  • Les idéaux vagues : « Suis les principes SOLID » ou « écris du code propre » laisse l’agent déduire la même décision de conception que celle qu’il allait prendre de toute façon.
  • Un second README : décrivez seulement la structure qui est surprenante ou qui détermine où une modification doit se faire.
  • Les inventaires complets de dépendances : le manifeste est plus à jour et plus facile à inspecter pour l’agent.
  • Les exigences ponctuelles d’une tâche : gardez-les dans le prompt de la tâche pour qu’elles n’influencent pas des sessions sans rapport.
  • Les règles que l’outillage peut faire respecter : formateurs, vérifications de types, tests, hooks et CI sont plus solides que de la prose pour les exigences déterministes.
  • Les secrets ou identifiants personnels : un fichier d’instructions est du contexte de projet ordinaire, pas un coffre-fort à secrets.

Un modèle de départ compact

# Repository instructions

## Fast path

- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)

## Verification

- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.

## Boundaries

- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.

## Known traps

- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.

Remplacez chaque exemple par un fait tiré du vrai dépôt. Un fichier exact de dix lignes vaut mieux qu’un modèle exhaustif rempli de consignes génériques.

Choisir le mécanisme durable le plus léger

Information Meilleur emplacement
S’applique à la plupart des tâches du dépôt AGENTS.md ou CLAUDE.md à la racine
S’applique à un seul sous-arbre Fichier d’instructions imbriqué ou règle limitée à un chemin
Préférence personnelle valable pour tous les dépôts Fichier d’instructions au niveau de l’utilisateur
Procédure en plusieurs étapes nécessaire pour certaines tâches Un skill chargé à la demande
Exigence propre à cette seule tâche Le prompt de la tâche
Règle qui doit toujours s’exécuter Test, formateur, hook, politique ou CI

Pour installer et maintenir des procédures à la demande sur plusieurs agents, voir le guide pratique de skills.sh. Un fichier d’instructions ne doit pas se substituer à toutes les autres surfaces de contrôle.

Évaluer le fichier dans votre propre dépôt

Les moyennes issues de la recherche ne peuvent pas vous dire si une instruction aide votre base de code. Choisissez une tâche reproductible pour laquelle l’instruction devrait changer le comportement, puis lancez plusieurs essais avec et sans elle, avec le même agent et la même version de modèle. Suivez :

  • les résultats de tests cachés ou écrits indépendamment ;
  • les lancements de tests ciblés et de la suite complète ;
  • le temps écoulé et la consommation de jetons ;
  • les modifications de fichiers et les demandes de permission inutiles ;
  • le respect, par l’agent, de la règle visée.

Gardez une instruction quand elle améliore un résultat ou évite un gaspillage mesurable. Réécrivez-la ou supprimez-la quand elle est ignorée, redondante, obsolète, ou qu’elle ne fait qu’allonger le prompt. Le but n’est pas le fichier de contexte parfait ; c’est un petit ensemble de faits sur le dépôt qui améliore le travail de façon fiable.

Questions fréquentes

AGENTS.md et CLAUDE.md rendent-ils les agents de codage plus précis ?

Pas de manière fiable, selon les recherches actuelles. Les études récentes constatent des effets mitigés sur l’efficacité et peu ou pas d’amélioration générale de l’exactitude des tâches. Des instructions opérationnelles concrètes peuvent néanmoins réduire les commandes, le temps et les jetons gaspillés.

Claude Code peut-il utiliser un fichier AGENTS.md existant ?

Par défaut, Claude Code ne charge pas directement AGENTS.md. Placez @AGENTS.md dans un petit fichier CLAUDE.md pour importer les instructions partagées, puis ajoutez en dessous uniquement les consignes réellement propres à Claude.

Quelle longueur doit faire un fichier AGENTS.md ou CLAUDE.md ?

Gardez le fichier racine aussi court que le dépôt le permet. Anthropic recommande actuellement moins de 200 lignes par CLAUDE.md. Codex applique par défaut une limite de 32 Kio à l’ensemble de sa chaîne d’instructions combinée, mais c’est un plafond, pas un objectif de rédaction.

Partager ce guide