---
title: "Que mettre dans AGENTS.md et CLAUDE.md ?"
seoTitle: "AGENTS.md et CLAUDE.md : ce qui aide vraiment les agents"
navTitle: "AGENTS.md et CLAUDE.md"
description: "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."
slug: agents-md-claude-md-best-practices
lang: fr
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "AGENTS.md et CLAUDE.md rendent-ils les agents de codage plus précis ?"
    a: "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."
  - q: "Claude Code peut-il utiliser un fichier AGENTS.md existant ?"
    a: "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."
  - q: "Quelle longueur doit faire un fichier AGENTS.md ou CLAUDE.md ?"
    a: "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."
---

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](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

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](https://code.claude.com/docs/en/memory).

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

```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?](https://arxiv.org/abs/2607.27250)
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](https://arxiv.org/abs/2601.20404)
  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](https://arxiv.org/abs/2602.11988) 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 :

```md
## 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 :

```md
## 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

```md
# 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](/articles/skills-sh-install-skills-ai-coding-agents).
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.
