AGENTS.md commun à Claude Code, Codex et Cursor

Pour en savoir plus sur le service, consultez la documentation d’Ailoot.

Qu’est-ce qui change quand on utilise Claude Code, Codex et Cursor ensemble ?#

Dans l’exemple décrit, Claude Code est l’outil principal, tandis que Codex et Cursor servent à des tâches spécifiques. Mon fichier CLAUDE.md contient environ 250 lignes d’instructions : quoi lire et dans quel ordre, ce qu’il ne faut pas toucher, les commandes à utiliser pour le déploiement et les règles de format des commits. Quand j’ai essayé Codex CLI pour la première fois dans le projet, il ne connaissait aucune de ces règles : il a exécuté git push --force, fouillé dans .env et renommé des fichiers sans précaution.

J’ai d’abord copié CLAUDE.md dans AGENTS.md à la main. Deux semaines plus tard, j’ai découvert que le projet avait déjà quatre versions des mêmes instructions : dans CLAUDE.md, AGENTS.md, .cursorrules et .windsurf/rules/. Elles différaient toutes un peu. Ce n’est pas un problème propre à Claude ou à Cursor, mais le piège fondamental de tout système comportant plusieurs sources de vérité. J’aborde ce problème plus en détail dans le guide sur le travail multi-agent.

En juin 2026, la documentation d’Anthropic sur la mémoire de Claude Code proposait une solution : un fichier partagé plus un import. Depuis septembre 2026, Claude Code lit lui-même AGENTS.md si le projet ne contient pas de CLAUDE.md. Un import est nécessaire lorsque vous avez des règles spécifiques à Claude. Ci-dessous, j’explique quand un seul fichier AGENTS.md suffit, comment configurer un import et comment distinguer les règles communes de celles qui sont propres à Claude.

Claude Code lit-il AGENTS.md lui-même ?#

Avant septembre 2026, la réponse était « non ». Issue #6235, qui demandait la prise en charge de AGENTS.md, était ouverte depuis août 2025 et a été close le 17 août 2026. Pendant tout ce temps, la documentation sur la mémoire proposait une seule solution : créer un fichier CLAUDE.md et y inclure AGENTS.md sous forme d’import. Depuis la version 2.1.277, la documentation indique autre chose :

Les fichiers lus par Claude Code dépendent précisément de ceux qui se trouvent dans le projet :

Pour cette vérification, les fichiers CLAUDE.md, .claude/CLAUDE.md et CLAUDE.local.md présents dans le répertoire de travail et dans tous les répertoires parents sont pris en compte. Un fichier personnel ~/.claude/CLAUDE.md, un fichier d’entreprise géré de manière centralisée et les règles de .claude/rules/ ne sont pas pris en compte : ils sont chargés en parallèle d’AGENTS.md.

En l’absence de CLAUDE.md, Claude Code lit au démarrage tous les fichiers AGENTS.md et .claude/AGENTS.md situés dans le répertoire de travail et dans les répertoires parents. Il charge aussi un fichier AGENTS.md dans un sous-répertoire lorsqu’il y ouvre un fichier. Les imports @path dans AGENTS.md fonctionnent également. Claude Code ne lit pas AGENTS.local.md, AGENTS.override.md ni le contenu du répertoire .agents/.

Le piège : un fichier personnel CLAUDE.local.md est également pris en compte. Si vous en créez un pour conserver vos règles non commitées, Claude Code cesse silencieusement de lire AGENTS.md. Le réglage ci-dessous résout le problème.

Le comportement se modifie dans /config, sous Project instructions :

Si vous souhaitez conserver CLAUDE.local.md sans perdre AGENTS.md, sélectionnez claude-md-and-agents-md. Il n’y aura pas de double lecture : si AGENTS.md est déjà inclus via la ligne @AGENTS.md ou un lien symbolique, Claude Code ne le charge pas une deuxième fois, quel que soit le réglage.

Vous pouvez vérifier si le fichier a été détecté avec la commande /memory : à partir de la version 2.1.280, le chemin d’accès à AGENTS.md apparaît dans la liste. Dans les versions antérieures à la 2.1.277 et dans les sessions où le plugin intégré agents-md est désactivé, Claude Code ne lit que CLAUDE.md et aucun élément Project instructions n’apparaît dans /config. Avant la version 2.1.281, les sessions via Amazon Bedrock et celles où la télémétrie était désactivée se comportaient de la même manière. Lors de la première session après une mise à jour depuis une ancienne version, AGENTS.md peut aussi ne pas être détecté ; il le sera dès la session suivante.

Qu’est-ce que cela implique pour un setup à fichier unique ? Si vous n’avez pas de règles propres à Claude, vous pouvez vous passer de CLAUDE.md : AGENTS.md suffit, et Claude Code, Codex et Cursor le liront. Si vous avez de telles règles (mode plan pour les répertoires à risque, skills, hooks), il vous faut CLAUDE.md, et Claude Code cessera de lire AGENTS.md de lui-même. Incluez alors AGENTS.md dans CLAUDE.md avec la ligne @AGENTS.md ; ce setup fonctionnera comme avant septembre. Il est également compatible avec les anciennes versions de Claude Code. J’explique cela en détail plus bas.

Comment importer @AGENTS.md dans CLAUDE.md ?#

Voici un exemple minimal fonctionnel tiré de la documentation officielle :

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Voici ce qui se passe. La première ligne, @AGENTS.md, est une directive d’import. Lorsque Claude Code analyse CLAUDE.md au début d’une session, il trouve cet import et insère à sa place l’intégralité du contenu d’AGENTS.md. Vient ensuite le titre ## Claude Code : c’est du simple Markdown, mais il sert de section « ajouts propres à Claude ». La règle qui suit ne s’applique qu’à Claude Code : utiliser le mode plan pour les changements dans le répertoire de facturation. Codex CLI ou Cursor n’ouvre pas ce fichier ; ils utilisent le fichier AGENTS.md tel quel.

Une citation de la documentation sur le fonctionnement des imports :

Quelques détails pratiques :

• Chemins relatifs et absolus. @AGENTS.md est relatif au fichier qui contient l’import. @/Users/me/shared/rules.md ou @~/.claude/personal.md sont des chemins absolus. J’utilise @~/.claude/personal.md pour les préférences personnelles que je ne veux pas mettre dans le dépôt.
• Profondeur de quatre niveaux. AGENTS.md peut importer @docs/coding-style.md, qui peut à son tour importer un autre fichier, jusqu’à quatre niveaux. C’est suffisant pour toute structure réelle.
• Les backticks bloquent les imports. Si le texte contient `@README`, il s’agit simplement d’une mention du nom, pas d’un import. C’est utile pour expliquer aux lecteurs le fonctionnement des imports sans en déclencher un.
• Autorisation pour les fichiers hors du projet. Si un import pointe hors du répertoire de travail, par exemple @~/.claude/personal.md, Claude Code affiche pour la première fois une boîte de dialogue répertoriant ces fichiers. Si vous refusez, les imports externes restent désactivés et la boîte de dialogue ne réapparaît pas. @AGENTS.md à la racine du projet ne déclenche aucune boîte de dialogue. Cela évite de charger accidentellement un fichier sans rapport dans le contexte.

Après être passé à ce setup dans le projet décrit, mon CLAUDE.md est passé de 250 à 60 lignes : @AGENTS.md plus cinq à sept règles propres à Claude Code (mode plan pour les répertoires à risque, éléments à ne pas toucher dans la zone d’administration et formulation des commits). Toutes les règles communes se trouvent dans AGENTS.md, que Codex et Cursor lisent.

Quand choisir un lien symbolique et quand choisir un import ?#

La documentation présente ainsi l’option du lien symbolique :

ln -s AGENTS.md CLAUDE.md

Et elle donne immédiatement un avertissement sans détour au sujet de Windows :

Tableau comparatif :

J’utilise des imports dans le projet décrit. Voici pourquoi :

1. L’équipe est hétérogène. Je travaille sur Mac ; dans l’exemple, l’équipe est composée à peu près à parts égales de personnes utilisant Windows et Mac. Si un lien symbolique se trouve dans le dépôt, les utilisateurs de Windows sans mode développeur le récupèrent comme un simple fichier texte contenant une seule ligne, AGENTS.md. Cela provoque des bogues étranges : parfois les règles fonctionnent, parfois non, sans qu’on sache pourquoi.
2. Je veux des règles propres à Claude. Sous @AGENTS.md, mon CLAUDE.md contient une section « Claude Code » avec des règles : utiliser --effort high pour les tâches d’architecture, exécuter npm run build avant git push et ne pas appeler /api/v1/deploy manuellement. Codex ne comprend pas ces commandes.
3. C’est plus facile à déboguer. Quand quelque chose ne va pas, j’ouvre CLAUDE.md et je vois l’import et mes personnalisations. Avec un lien symbolique, rien n’indique « ceci a été ajouté ici ». Pour en savoir plus sur le débogage des réglages de Claude Code, consultez le guide du mode sécurisé.

Si vous n’avez pas de règles propres à Claude, le lien symbolique n’est plus nécessaire à partir de la version 2.1.277 : supprimez CLAUDE.md et Claude Code lira lui-même AGENTS.md. Ne gardez le lien symbolique que si un membre de l’équipe utilise une version antérieure à 2.1.277 et ne peut pas la mettre à jour. Si vous avez des règles propres à Claude, un import est plus pratique neuf fois sur dix.

Que lisent Codex, Cursor, Copilot, Windsurf et Gemini CLI ?#

Carte des sept principaux outils (basée sur la documentation officielle de chacun) :

Qu’est-ce que cela implique ? Si un dépôt contient AGENTS.md (et, lorsque des règles propres à Claude sont nécessaires, un CLAUDE.md avec un import), cinq des sept outils reçoivent automatiquement des instructions à jour. Cursor et Windsurf disposent de leurs propres fichiers natifs. Vous pouvez les conserver tels quels (AGENTS.md est également lu par ces outils) ou y ajouter un import @AGENTS.md — mais leur syntaxe diffère et n’est pas toujours prise en charge.

La stratégie la plus simple pour un nouveau projet :

1. Placez toutes les règles communes dans AGENTS.md : 95 % des règles vont là.
2. Créez CLAUDE.md si vous avez besoin de règles propres à Claude : mettez @AGENTS.md sur la première ligne, puis ajoutez une section avec les règles propres à Claude. S’il n’y en a pas, CLAUDE.md est inutile ; Claude Code lit lui-même AGENTS.md depuis la version 2.1.277.
3. Gardez .cursor/rules/ pour Cursor dans les rares cas où des éléments spécifiques à Cursor sont nécessaires (ses commandes @Codebase et @Docs).
4. Faites de même pour Windsurf : oubliez l’ancien .windsurfrules et n’utilisez .windsurf/rules/ que si vous avez besoin de règles adaptées à sa syntaxe.

Cette approche apporte 80 % des bénéfices pour 20 % du travail. D’après mon expérience, lorsque je mettais de l’ordre dans des équipes mixtes chez « Antigravity », la gestion de plus de deux sources de vérité (communes et propres à Claude) devenait pénible. Si une personne de l’équipe ajoute une règle dans .cursorrules et oublie AGENTS.md, une semaine plus tard Cursor et Codex ne seront plus d’accord.

Comment /init dans Claude Code reprend-il un AGENTS.md existant ?#

Anthropic décrit ainsi /init dans sa documentation :

Qu’est-ce que cela signifie en pratique ? Le dépôt décrit contenait un fichier .cursorrules datant de mes essais avec Cursor (environ 80 lignes) et un fichier AGENTS.md (120 lignes) assemblé à la main. Lorsque j’ai lancé claude /init, la commande a repris les deux fichiers, dédoublonné les règles similaires et composé un CLAUDE.md propre en une minute. Je l’ai vérifié ensuite et y ai apporté de légères modifications : j’ai supprimé les éléments obsolètes et ajouté une structure avec des titres. C’était plus rapide que de tout réécrire depuis le début.

Le mode interactif, dans lequel /init lit aussi AGENTS.md, s’active à l’aide d’une variable d’environnement :

CLAUDE_CODE_NEW_INIT=1 claude

Après le lancement de /init, Claude pose une série de questions de clarification : quels éléments configurer (CLAUDE.md, skills, hooks), quelle stack utilise le projet et quelles commandes employer pour les tests. Ensuite, un sous-agent explore la base de code — en lisant package.json, README.md et les fichiers de configuration — et complète les éléments manquants. À la fin, il affiche une proposition que vous pouvez modifier avant de l’enregistrer. Pour en savoir plus sur la configuration de Claude Code au démarrage d’un projet, consultez le guide dédié.

Voyons maintenant l’inconvénient. Si le projet contient déjà un AGENTS.md actif, /init crée à côté un CLAUDE.md qui en reprend les règles. À partir de là, Claude Code ne lit par défaut que CLAUDE.md, et il y a de nouveau deux sources de vérité : vous mettez à jour AGENTS.md, tandis que Claude continue de travailler avec l’ancienne copie. La commande /import fait quelque chose de similaire : elle ajoute une copie ponctuelle d’AGENTS.md à CLAUDE.md. Pour conserver une source unique, placez l’import @AGENTS.md sur la première ligne de CLAUDE.md après /init, puis supprimez de CLAUDE.md tout ce qui répète AGENTS.md.

/init est un bon point de départ pour un nouveau projet ou pour un projet que vous migrez depuis Cursor ou Copilot. Inutile de chercher en ligne le « meilleur modèle de CLAUDE.md » : Anthropic tient déjà compte du contenu du dépôt. Si le projet contient déjà un AGENTS.md actif et qu’il n’y a pas de règles propres à Claude, /init est inutile : Claude Code lira AGENTS.md lui-même.

Comment séparer les instructions communes de celles propres à Claude ?#

Je les sépare selon ce principe. Voici les règles communes qui vont dans AGENTS.md :

• Ce qu’il ne faut pas toucher dans le code. .env, node_modules, les dossiers prisma/migrations (uniquement via prisma migrate), .next/, .git/.
• Comment nommer les éléments. Branches : feat/, fix/, chore/. Commits : préfixes feat:, fix:, docs: suivis d’une brève description. Fichiers de composants en kebab-case.
• Commandes de test et de lint. npm run build, npm run lint, npm test. La commande à exécuter avant git push.
• Principes d’architecture. Ce qui va dans src/lib/ et src/components/, où se trouve la logique métier et où se trouve l’interface utilisateur.
• Sécurité. Ne jamais commiter de secrets. Accéder à la base de données de production uniquement via prod-psql. Accéder à la production par SSH uniquement via l’alias prod, et non via root@IP.

Les règles propres à Claude à mettre dans CLAUDE.md (sous @AGENTS.md) :

• Mode plan. Utiliser le plan mode pour les changements dans les répertoires à risque (par exemple, src/billing/).
• Niveau d’effort. Utiliser --effort high pour les tâches d’architecture et medium pour les tâches courantes.
• Skills. Quels agents IA et quels skills exécuter dans quelles situations. Par exemple : « pour travailler sur un guide, exécuter le skill build-masterskaya-guide. »
• Mémoire de Claude. Que mettre dans la mémoire automatique et que mettre dans CLAUDE.local.md. Pour en savoir plus sur la mémoire de Claude, consultez le guide sur Memory et CLAUDE.md.
• Hooks. Si .claude/settings.json contient des hooks configurés, décrivez dans CLAUDE.md leur fonction (Codex et Cursor ne les connaissent pas et n’ont pas besoin de les connaître).
• Skills et commandes. Une liste des commandes slash que j’utilise souvent (/init, /cd, /memory, /plan).

La frontière n’est pas toujours nette. Par exemple, « ne jamais exécuter git push --force sur main » est clairement une règle commune qui va dans AGENTS.md. En revanche, « avant d’exécuter git push sur une branche urgente, utiliser d’abord le mode plan » est spécifique à Claude Code et va dans CLAUDE.md. Le test à faire : « Si je supprimais Claude Code demain et ne gardais que Codex, cette règle s’appliquerait-elle encore ? » Si oui, mettez-la dans AGENTS.md. Sinon, mettez-la dans CLAUDE.md.

Que mettre dans AGENTS.md, et que mettre dans CLAUDE.md ou .claude/rules ?#

Si les règles dépassent 200 lignes, il est temps de les répartir dans plusieurs fichiers. La documentation d’Anthropic recommande de viser 200 lignes par fichier, car Claude commence à moins bien suivre, sans le signaler, les longs fichiers CLAUDE.md : on dirait qu’il les lit, mais il respecte moins souvent leur contenu.

Voici une structure qui me convient pour un grand projet :

my-project/
├── AGENTS.md                    # 100-150 lignes, règles communes
├── CLAUDE.md                    # 30-50 lignes : @AGENTS.md + règles propres à Claude
└── .claude/
    ├── CLAUDE.md                # alternative au fichier à la racine, même fichier
    └── rules/
        ├── api.md               # avec paths: ['src/api/**']
        ├── components.md        # avec paths: ['src/components/**']
        ├── testing.md           # sans paths, toujours actif
        └── security.md          # sans paths, toujours actif

Chaque fichier de .claude/rules/ peut contenir un frontmatter :

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude ne charge ces règles que lorsqu’il travaille sur des fichiers correspondant à ce modèle. S’il modifie src/components/Button.tsx, les règles d’API ne sont pas ajoutées au contexte. Ainsi, la fenêtre de contexte n’est utilisée que pour les éléments pertinents. Le répertoire .claude/rules/ fonctionne aussi sans CLAUDE.md : si le projet ne contient qu’un fichier AGENTS.md, les règles sont chargées en parallèle et ne désactivent pas la lecture directe d’AGENTS.md.

Cursor et Windsurf prennent en charge la même approche via leurs répertoires .cursor/rules/ et .windsurf/rules/. Le standard AGENTS.md peut faire référence à ces répertoires, mais la syntaxe inter-outils n’est pas encore entièrement stable. Il est plus sûr de laisser les règles communes dans AGENTS.md et de dupliquer les règles liées à des chemins dans .claude/rules/ et .cursor/rules/ : ce sont des cas particuliers, pas la majeure partie des règles.

Emplacements utiles pour CLAUDE.md (classés du plus général au plus spécifique) :

Un fichier ~/.claude/CLAUDE.md pourrait par exemple contenir deux règles : « répondre dans la langue préférée de l’utilisateur » et « orthographier Ailoot exactement ainsi ». Ces règles s’appliquent à tous les projets ; inutile de les recopier dans chaque dépôt.

Sur ces quatre niveaux, seuls un fichier CLAUDE.md au niveau du projet et un fichier CLAUDE.local.md désactivent la lecture directe d’AGENTS.md. Un fichier personnel ~/.claude/CLAUDE.md et une politique gérée de manière centralisée ne gênent pas : Claude Code les lit en parallèle d’AGENTS.md.

Que faire si AGENTS.md est déjà obsolète dans votre projet ?#

Dans le projet décrit, j’avais un fichier AGENTS.md datant de mai 2025 — 180 lignes, dont beaucoup étaient obsolètes (il mentionnait des points de terminaison de l’API Anthropic qui avaient changé depuis, des exemples avec une syntaxe claude --tools qui n’existe plus et des règles sur ~/.claude/projects/ fondées sur une structure dépassée).

Voici comment j’ai procédé pour le mettre à jour :

1. Le relire avec claude en mode plan. J’ouvre le dépôt, je lance claude --safe-mode et je demande : « Relis AGENTS.md et propose une liste des éléments obsolètes ou répétés. Ne le modifie pas ; dresse uniquement la liste. » En deux minutes, j’ai obtenu 23 éléments à examiner.
2. Supprimer les éléments manifestement obsolètes. Sur les 23 éléments, 9 étaient clairement dépassés : syntaxe des commandes, points de terminaison et noms d’options. J’ai supprimé ces lignes.
3. Regrouper les doublons. Six autres éléments répétaient la même chose avec des formulations différentes (« ne pas forcer le push », « ne jamais utiliser --force », « éviter git push -f »). Je les ai réunis en une seule ligne.
4. Ajouter de nouveaux éléments. J’ai ajouté les erreurs que j’avais remarqué que Claude/Codex commettaient régulièrement pendant le mois écoulé, selon la règle « une ligne par type d’erreur ». Cela a donné 8 nouveaux éléments.
5. Demander une dernière vérification à un sous-agent. J’ai demandé à Claude de « trouver les contradictions, ambiguïtés et doublons ». Il a repéré trois formulations qui pouvaient être clarifiées. Je les ai corrigées.

Au bout d’une heure, AGENTS.md comptait 110 lignes à jour et je connaissais chacune d’elles. Il a été facile d’en tirer un CLAUDE.md de 30 lignes. Codex s’est aussi montré nettement plus soigneux avec les tests par la suite ; je soupçonne que certaines de ses décisions « étranges » venaient d’instructions obsolètes qu’il avait suivies de bonne foi.

Les grands principes pour maintenir AGENTS.md à jour :

• Chaque règle répond à une erreur récurrente. Si aucune règle ne m’est venue à l’esprit une seule fois au cours du mois, cela ne vaut pas la peine de la conserver.
• Formulez les règles comme des consignes, pas comme de la théorie. « Utiliser deux espaces » est une règle. « Le style du code doit être soigné » n’en est pas une.
• Privilégiez le concret au général. « Exécuter npm run build avant git push » est une règle. « Tester les modifications » n’en est pas une.

Qu’est-ce qui ne fonctionne DÉFINITIVEMENT PAS avec ce setup ?#

Quelques leçons apprises à la dure pendant six mois de travail avec ce setup :

1. La complétion automatique de Cursor n’utilise pas AGENTS.md. Quand Cursor propose de compléter une ligne dans l’éditeur, il ne lit pas AGENTS.md en temps réel : un moteur rapide distinct s’en charge. Les règles d’AGENTS.md ne comptent que lorsqu’on envoie une demande dans le chat de Cursor. Ainsi, écrire dans AGENTS.md « ne pas utiliser var, utiliser const » n’aura aucun effet sur la complétion automatique ; il faut configurer cela dans ESLint ou dans la configuration TypeScript.

2. Les hooks Claude Code dans AGENTS.md ne fonctionnent pas avec Codex. Si .claude/settings.json contient un hook PreToolUse configuré pour bloquer une action donnée, cette information n’est utile que pour Claude. Codex ne connaît pas les hooks ; pour lui, c’est comme si « l’outil décidait tout seul ». Il est logique d’écrire « ne pas faire X » dans AGENTS.md et « un hook bloque physiquement X » dans CLAUDE.md, sous l’import.

3. Copilot et .github/copilot-instructions.md. GitHub Copilot lit son propre fichier et ne lit toujours pas très bien AGENTS.md. Si votre équipe utilise activement Copilot, ajoutez un fichier .github/copilot-instructions.md distinct contenant une version abrégée des règles, ou utilisez des extensions Copilot qui connaissent AGENTS.md. La situation évolue rapidement ; elle pourrait être différente dans trois à six mois.

4. Git ne suit pas un lien symbolique comme une modification de CLAUDE.md. Si vous exécutez ln -s AGENTS.md CLAUDE.md et mettez à jour AGENTS.md une semaine plus tard, Git n’affiche un diff que pour AGENTS.md. C’est normal, mais un collègue qui examine la PR peut ne pas comprendre que CLAUDE.md a également été mis à jour via le lien symbolique. Solution : indiquez explicitement dans la description de la PR : « AGENTS.md mis à jour ; Claude Code voit le même fichier via le lien symbolique. »

5. Les imports imbriqués sont difficiles à déboguer. Si AGENTS.md importe @docs/coding-style.md, qui importe à son tour @docs/typescript.md, il est difficile de déboguer un conflit entre des règles. Je limite les imports à un seul niveau (CLAUDE.md → AGENTS.md) et je ne les imbrique pas davantage. Anthropic propose un hook InstructionsLoaded qui consigne les fichiers chargés, ce qui est utile pour déboguer les setups à plusieurs couches. Remarque : le hook se déclenche pour AGENTS.md inclus via un import ou un lien symbolique, mais pas lorsque Claude Code lit lui-même AGENTS.md.

Le setup complet de vibe coding pour une soirée : clone IA + Second Brain + ingénierie du contexte.

Découvrez Ailoot.