Faut-il créer les trois fichiers ?

Non. Commence par le format commun, qui couvre le plus d’outils. N’ajoute un fichier au nom spécifique que si l’outil que tu utilises vraiment le demande.

Où placer le fichier ?

À la racine du projet, c’est-à-dire dans le dossier principal, à côté de tes autres fichiers. Sur un projet découpé en plusieurs parties, chaque partie peut avoir le sien : l’outil lit le plus proche.

Est-ce qu’un long fichier est plus efficace ?

Non, l’inverse. La documentation officielle recommande de rester court. Un fichier long occupe la place de travail de l’outil et se retrouve moins bien suivi qu’un fichier bref et net.

Comment savoir s’il est vraiment lu ?

Ferme tout, rouvre, et demande à l’outil ce que fait ton projet. Une bonne réponse sans que tu aies rien réexpliqué prouve qu’il l’a lu. Une question en retour prouve le contraire.

CLAUDE.md, AGENTS.md, GEMINI.md : qui lit quoi

On t’a dit de créer un fichier CLAUDE.md. Ailleurs on parle d’AGENTS.md, ailleurs encore de GEMINI.md. Tu ne sais pas si tu dois les créer tous les trois, ni lequel ton outil lit vraiment. Tu en fais un au hasard, et tu n’es jamais certain qu’il serve à quelque chose.

Chaque éditeur a d’abord créé son propre nom de fichier d’instructions : CLAUDE.md, GEMINI.md et d’autres. Un format commun, AGENTS.md, est ensuite apparu et est aujourd’hui lu par plus de vingt outils. Le fichier se pose à la racine du projet et se relit à chaque démarrage.

Pourquoi il existe plusieurs noms

L’histoire est simple, et elle explique la confusion actuelle.

Chaque éditeur d’outil de code assisté a eu le même problème au même moment : une IA repart de zéro à chaque session, donc il faut un endroit où poser ce qui doit survivre. Chacun a résolu ça dans son coin, et chacun a choisi son nom de fichier.

D’où la situation d’aujourd’hui : CLAUDE.md pour Claude Code, GEMINI.md pour l’outil de Google, et d’autres formats encore chez Cursor, GitHub Copilot ou Windsurf, chacun avec sa convention.

Un utilisateur qui change d’outil se retrouvait donc à recopier les mêmes consignes sous un autre nom. Ce qui a fini par produire une réponse commune.

Le format commun : AGENTS.md

C’est le point que beaucoup de gens n’ont pas encore intégré, et il simplifie tout.

AGENTS.md se présente comme un format simple et ouvert pour guider les agents de codage — l’équivalent, pour eux, du fichier de présentation qu’on trouve à la racine des projets depuis toujours.

Ce n’est pas la convention d’un éditeur. Le standard a émergé d’un effort collectif, et il est aujourd’hui géré par la fondation Agentic AI, elle-même rattachée à la Linux Foundation. Autrement dit, il n’appartient à personne en particulier.

Côté adoption, c’est ce qui compte : plus de vingt outils le lisent, dont Codex d’OpenAI, Jules de Google, VS Code, Cursor, GitHub Copilot, Zed, Devin et Aider, sur plus de soixante mille projets ouverts.

Claude Code le lit également, tout en gardant CLAUDE.md comme son format natif, plus riche.

Où poser le fichier

À la racine du projet. C’est-à-dire dans le dossier principal, au même niveau que tes autres fichiers — pas dans un sous-dossier, pas rangé dans un coin.

C’est la seule règle d’emplacement qui compte, et c’est aussi la cause numéro un des fichiers qui « ne marchent pas » : ils existent, ils sont bien écrits, ils sont simplement au mauvais endroit.

Un cas particulier vaut d’être connu : si ton projet est découpé en plusieurs parties distinctes, chacune peut avoir son propre fichier. Les outils lisent alors le plus proche de l’endroit où ils travaillent. Utile plus tard ; inutile de s’en préoccuper au démarrage.

Ce qui se passe au démarrage

Le mécanisme est le même partout, et il tient en une phrase : le fichier est lu à l’ouverture, avant que tu tapes quoi que ce soit.

C’est ce qui le distingue radicalement d’une consigne donnée dans la conversation. Une phrase tapée en discutant vit le temps de la conversation puis disparaît. Une phrase écrite dans ce fichier est relue à chaque nouvelle session, sans que tu aies à y penser.

C’est aussi pour cette raison qu’une consigne répétée trois fois dans la même journée est un signal, pas une fatalité : elle n’est pas au bon endroit.

La longueur, et pourquoi elle joue contre toi

Le réflexe naturel, quand on découvre ce fichier, est d’y déverser tout ce qu’on sait. C’est contre-productif, et la documentation officielle le dit.

La recommandation est de rester court. La raison est mécanique et n’a rien à voir avec la discipline : ce fichier occupe une place dans l’espace de travail de l’outil, le même espace limité qui accueille votre conversation. Plus il est long, plus il pèse, et moins il est suivi.

Un fichier bref et net est mieux respecté qu’un pavé exhaustif. C’est contre-intuitif, et c’est ce que les éditeurs constatent.

Le seul test qui compte

Il prend dix secondes et il remplace toutes les suppositions.

Ferme tout. Rouvre. Demande à l’outil ce que fait ton projet.

S’il répond juste sans que tu aies rien réexpliqué, le fichier est lu, il est au bon endroit, et il fonctionne. Si l’outil te repose la question, inutile de chercher plus loin : le fichier est mal placé ou pas lu, et c’est ça qu’il faut corriger avant toute autre chose.

Refais ce test à chaque changement de dossier, de machine ou d’outil. Tant que tu ne l’as pas fait, tu supposes.

Ce qu’il faut retenir

Un seul fichier suffit pour commencer. Prends le format commun, il couvre le plus d’outils. N’ajoute un nom spécifique que si l’outil que tu utilises vraiment le réclame.

L’emplacement compte autant que le contenu. À la racine, sinon rien ne se passe.

Court bat exhaustif. Ce n’est pas une question de style, c’est une question de place disponible.

Le test décide. Fermer, rouvrir, demander. Le reste est de la croyance.