AGENTS.md et CLAUDE.md : Comment rédiger un fichier de config que votre agent utilise vraiment

Rédiger un bon fichier de config est le geste le plus rentable et le moins coûteux du développement agentique. Vous posez le contexte une fois, et chaque session en bénéficie : l'agent cesse de deviner votre commande de test, cesse de reformater selon ses propres valeurs par défaut, cesse d'éditer le répertoire que vous lui avez déclaré hors-limites. Cette page constitue le savoir-faire concret derrière la compétence "contexte & configuration" AI-Native — l'une des 17 compétences AI-native que nous évaluons à travers les niveaux. Conserver une mémoire de projet durable dans CLAUDE.md / AGENTS.md est le signal distinctif d'un Développeur Agentique de Niveau 3, autant dire que ça vaut la peine de le faire bien.

L'idée centrale est la même dans tous les outils, même si les mécaniques diffèrent : un fichier de config transporte ce qu'un agent ne peut pas déduire du code lui-même. Le modèle connaît déjà votre langage. Il ne sait pas que vos tests exigent une option particulière, que vous avez migré hors d'une bibliothèque il y a trois mois, ou que infra/ est généré et ne doit jamais être modifié à la main. C'est ce vide que le fichier comble.

Le paysage : une philosophie, de nombreux fichiers

Chaque agent majeur lit un fichier de contexte de projet. Ils partagent une philosophie mais divergent sur le nom de fichier et les mécaniques de chargement. Voici la cartographie pour 2026 :

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 outils	Standard ouvert et multioutil
CLAUDE.md	Claude Code	Format natif de Claude Code
GEMINI.md	Gemini CLI	Format natif de Gemini
.github/copilot-instructions.md	GitHub Copilot	Instructions de dépôt pour Copilot
.cursor/rules (anciennement .cursorrules)	Cursor	Format de règles de Cursor

Le constat : AGENTS.md est la source de vérité unique qui s'impose — une spec ouverte que ~20 outils lisent déjà. La nuance importante : Claude Code ne lit pas AGENTS.md nativement ; il ne lit que CLAUDE.md. Le schéma canonique « une seule source de vérité » consiste donc à garder AGENTS.md comme référence et à faire le pont vers Claude avec un CLAUDE.md minimal qui l'importe :

@AGENTS.md

<!-- Claude-specific notes can go below -->

Un lien symbolique fonctionne aussi (ln -s AGENTS.md CLAUDE.md), mais sous Windows préférez l'@import — les symlinks y exigent des droits administrateur. Vous ne maintenez ainsi qu'un seul fichier, et les deux écosystèmes le lisent.

Ce qu'il faut vraiment y mettre

L'analyse GitHub de plus de 2 500 dépôts (« How to write a great AGENTS.md ») montre que les configs qui améliorent mesuralement les agents partagent six sections. Par ordre de priorité décroissante :

1. Commandes — placées tôt, avec les commandes exécutables exactes et leurs options (npm test, npm run build, pytest -v), pas seulement les noms d'outils. C'est la section au meilleur ROI : les agents savent déjà que pytest existe ; ils ignorent les options requises par votre projet. Mettez-la en haut.
2. Pratiques de test — comment vous testez, ce qu'il faut lancer avant de committer, vos attentes en couverture.
3. Structure du projet — où les choses se trouvent, pour que l'agent cesse de chercher.
4. Style de code — montrez un vrai extrait de code, pas trois paragraphes de prose.
5. Workflow Git — nommage des branches, conventions de commits, règles de PR.
6. Limites — ce que l'agent ne doit jamais toucher (répertoires générés, secrets, code vendored, migrations).

Notez l'ordre de priorité. « Commandes avec options » est en premier pour une raison : c'est la seule chose que le modèle ne peut pas deviner de façon fiable et se trompe le plus fréquemment. Si vous ne rédigez rien d'autre avec soin, rédigez ça.

Inclure / exclure : le test ligne par ligne

La documentation mémoire d'Anthropic trace une ligne explicite à deux colonnes. Utilisez-la comme filtre pour chaque ligne que vous êtes tenté d'ajouter.

Include	Exclude
Commandes Bash que l'agent ne peut pas deviner	Tout ce qui est déductible du code
Règles de style qui diffèrent des valeurs par défaut	Conventions de langage standard que le modèle connaît déjà
Instructions de test / lanceur de tests privilégié	Documentation d'API détaillée (mettez un lien plutôt)
Étiquette du dépôt (nommage des branches, conventions de PR)	Informations qui changent fréquemment
Décisions architecturales propres au projet	Explications longues et tutoriels
Particularités d'environnement de développement (variables d'environnement requises)	Descriptions fichier par fichier de la base de code
Pièges non évidents	Pratiques évidentes comme « écrire du code propre »

Il existe un test qui condense toute la table en une habitude :

Le test par ligne : « Supprimer cette ligne ferait-il commettre des erreurs à l'agent ? Si non, supprimez-la. »

Appliquez ce test à chaque ligne. « Use TypeScript » — l'agent voit les fichiers .ts ; supprimez-le. « Run database migrations with npm run db:migrate, never edit migrations/ by hand » — il ne pouvait pas deviner ça, et se tromper corromprait l'état ; gardez-le.

Écrire à la bonne altitude

Les recommandations d'Anthropic sur l'ingénierie de contexte distillent une bonne rédaction en quatre principes.

1. Spécificité / vérifiabilité. Rédigez des règles suffisamment concrètes pour pouvoir les vérifier sur la sortie de l'agent. Des consignes vagues ne peuvent pas être vérifiées, et donc pas fiablement suivies.

• « Use 2-space indentation » — pas « Format code properly. »
• « Run npm test before committing » — pas « Test your changes. »
• « API handlers live in src/api/handlers/ » — pas « Keep files organized. »

2. Bonne altitude. Visez entre la logique rigide et les généralités creuses : « suffisamment spécifique pour guider le comportement, suffisamment flexible pour constituer une heuristique solide. » Trop rigide et ça casse au premier cas limite ; trop vague et ça ne guide rien.

3. Minimal-mais-suffisant. Minimal ne signifie pas court. Cela signifie donner assez de contexte en amont pour que l'agent n'ait pas à deviner ni à redécouvrir — et rien de plus. Élaguez le remplissage, gardez les détails structurants.

4. Structure. Utilisez des sections nommées — titres Markdown ou balises XML. Un fichier scannable est un fichier que l'agent (et vos collègues) parcourt vraiment.

Rester concis

La vraie raison de rester concis, c'est le budget en tokens. Le fichier de config se charge intégralement à chaque session. Il n'est pas récupéré à la demande ; il est préfixé au contexte au lancement. Le gonflement a donc un coût direct et mesuré : un CLAUDE.md gonflé réduit mesuralement l'adhérence aux instructions. La formule d'Anthropic est sans détour — les CLAUDE.md gonflés poussent Claude à ignorer vos vraies instructions. Chaque ligne inutile que vous ajoutez affaiblit vos bonnes lignes.

Les objectifs sont concrets :

• Anthropic vise moins de ~200 lignes comme objectif indicatif pour CLAUDE.md.
• Codex impose un plafond strict de 32 KiB sur AGENTS.md (project_doc_max_bytes) ; les fichiers trop grands sont tronqués, et tout ce qui dépasse le plafond ne se charge tout simplement pas.

Un piège mérite d'être nommé : les imports n'économisent pas le budget. Un fichier @importé se charge quand même dans le contexte au lancement — vous avez découpé le fichier, pas réduit l'empreinte. Pour réduire réellement ce qui se charge à chaque session, déplacez le contenu conditionnellement pertinent :

• Règles scopées par chemin pour les préoccupations transversales qui touchent de nombreux fichiers — elles ne se chargent que lorsque l'agent travaille dans ce chemin.
• Skills pour les procédures à la demande — elles ne se chargent que lorsqu'elles sont invoquées.
• Liens pour le matériel de référence long ou détaillé — pointez-y plutôt que de l'insérer.

Le principe est le même que celui qu'applique le test par ligne, appliqué au niveau des sections : si c'est seulement parfois pertinent, ça ne devrait pas figurer dans le fichier chargé en permanence.

DESIGN.md : une convention d'équipe, pas un standard

Un DESIGN.md est l'application scolaire du principe « gardez la config concise, liez le détail ». C'est un doc de design/architecture séparé — les décisions clés, le modèle de domaine, les patterns architecturaux, le pourquoi c'est conçu ainsi — que votre AGENTS.md @importe ou référence plutôt que d'insérer. La config chargée en permanence reste ainsi courte, tandis que le contexte approfondi reste à un saut de distance.

Soyez honnête sur son statut, cependant : contrairement à AGENTS.md et CLAUDE.md, il n'existe aucune source primaire établissant DESIGN.md comme fichier de config agent standard. C'est une convention d'équipe efficace, pas un standard documenté. Utilisez-le parce que ça fonctionne pour votre équipe, pas parce qu'une spec l'impose.

Portée & hiérarchie

Les deux écosystèmes superposent les fichiers du plus général au plus spécifique, mais résolvent la précédence différemment.

CLAUDE.md a quatre portées, chargées du plus général au plus spécifique :

1. Politique gérée — définie par votre organisation / IT, s'applique à l'ensemble de l'organisation.
2. Utilisateur — ~/.claude/CLAUDE.md, s'applique à tous vos projets.
3. Projet — ./CLAUDE.md, versionné dans git et partagé avec l'équipe.
4. Local — ./CLAUDE.local.md, ignoré par git, pour vos remplacements personnels.

Dans les monorepos, les fichiers des répertoires parents se chargent automatiquement et les fichiers des sous-répertoires se chargent à la demande. Les imports utilisent la syntaxe @path/to/file (relative ou absolue), s'emboîtent jusqu'à 4 niveaux de profondeur, et le parseur ignore les blocs de code — un chemin dans un bloc fenced n'est pas traité comme un import.

AGENTS.md résout par proximité — le plus proche l'emporte. Codex remonte depuis la racine Git jusqu'à votre répertoire de travail courant et concatène les fichiers trouvés, racine en premier. Les fichiers les plus proches apparaissant en dernier, ils remplacent — le fichier le plus proche l'emporte. Dans un monorepo, vous conservez un AGENTS.md par package, et celui au plus près du code en cours d'édition a la précédence. Au-dessus de tout : une instruction explicite dans le chat prend le dessus sur tous les fichiers.

Et le pont multioutil évoqué plus tôt relie les deux systèmes : gardez AGENTS.md comme référence, ajoutez un CLAUDE.md qui fait @AGENTS.md, et votre hiérarchie est partagée entre les outils sans duplication.

Consultatif, pas coercitif

Voici la nuance qui vous évite une fausse impression de sécurité : ces fichiers sont un contexte consultatif, pas une application déterministe. Ils orientent l'agent ; ils ne le contraignent pas.

Les mots d'emphase comme IMPORTANT et YOU MUST améliorent mesuralement l'adhérence — mais ils ne la garantissent pas. Pour les exigences qui doivent se produire à chaque fois (lancer le formateur, bloquer un commit qui échoue aux tests, ne jamais écrire sur main), le garde-fou déterministe ce sont les hooks (dans Claude Code), pas une formulation plus forte dans la config.

La règle empirique : utilisez la config pour les consignes et les heuristiques ; recourez aux hooks dès que « l'agent fait généralement ça » ne suffit plus et que vous avez besoin de « l'agent fait toujours ça ».

Le maintenir comme du code

Un fichier de config est un artefact vivant, pas une écriture ponctuelle. Traitez-le comme le reste du dépôt.

• Amorcer avec /init. Laissez l'outil générer un premier jet à partir de votre base de code, puis affinez-le à la main — la version générée est un point de départ, pas le fichier final.
• Réviser quand les choses tournent mal. Chaque fois que l'agent fait une bêtise, demandez-vous si une ligne manquante ou trompeuse dans la config en est la cause.
• Élaguer régulièrement. Réappliquez le test par ligne sur tout le fichier. Des lignes structurantes le trimestre dernier peuvent être du poids mort aujourd'hui.
• Tester les modifications par le comportement. Ne supposez pas qu'une modification a aidé — observez si le comportement de l'agent a vraiment changé. Si vous ne voyez pas de différence, la ligne ne fait probablement pas de travail.
• Le versionner dans git. Une config partagée et versionnée signifie que toute l'équipe contribue et en bénéficie, et que les changements apparaissent en revue.

L'habitude la plus précieuse est la boucle d'auto-amélioration : quand l'agent fait une erreur, ajoutez une seule règle d'une ligne pour éviter qu'elle se répète. Sur quelques semaines, cette boucle fait converger votre config exactement vers les pièges réels de votre projet — ni plus, ni moins.

Un AGENTS.md de démarrage

Voici un squelette réel, prêt à copier-coller, avec les six sections à fort ROI remplies de valeurs réalistes. Remplacez par vos spécificités et supprimez tout ce qui ne passe pas le test par ligne.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Pour une source de vérité unique entre les outils, déposez un `CLAUDE.md` d'une ligne à côté contenant `@AGENTS.md`, et liez vos notes d'architecture approfondies (un `DESIGN.md`, vos ADR) plutôt que de les coller dedans.

## Par où continuer

Un fichier de config concis et précis est l'un des comportements concrets qui distingue les développeurs assistés par IA des développeurs genuinement AI-native. [Trouvez votre niveau AI-native](/quiz) en trois minutes — il évalue exactement ce type de savoir-faire — et quand vous êtes prêt à câbler votre outillage, commencez par [la stack ProCoders recommandée](/stack).