# AGENTS.md commun à Claude Code, Codex et Cursor
> Une source unique pour Claude Code, Codex et Cursor en 2026 : quand Claude Code lit AGENTS.md lui-même, importer @AGENTS.md dans CLAUDE.md, utiliser un lien symbolique et /init.
Source: https://ailoot.ai/blog/fr/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/fr/agents-md-claude-md-one-instruction-file/
Language: fr
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-dc7b3f7607c7b9c43e0ba51aab3189b30b0c5fbe6892baeb1c19304a1ac77f61
Pour en savoir plus sur le service, consultez la [documentation d’Ailoot](https://ailoot.ai/docs/).
## Qu’est-ce qui change quand on utilise Claude Code, Codex et Cursor ensemble ?
À retenir
En 2026, le setup typique d’un vibe coder ne se limite pas à un outil, mais en compte 3–5. Claude Code comme outil principal, Codex pour les longues tâches autonomes, Cursor pour les modifications rapides dans l’IDE. Chacun a son propre fichier d’instructions : `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Si vous les synchronisez manuellement, vous modifiez une ligne à cinq endroits, vous oubliez de mettre Cursor à jour et, une semaine plus tard, Claude et Codex donnent des résultats différents pour le même prompt.
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](https://ailoot.ai/blog/fr/claude-code-codex-together/).
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 ?
À retenir
Oui, à partir de la version 2.1.277, publiée le 18 septembre 2026, mais seulement s’il n’existe aucun fichier `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` dans le répertoire de travail ni dans les répertoires parents. Si `CLAUDE.md` existe, Claude Code ne lit par défaut que ce fichier, et `AGENTS.md` est inclus avec la ligne `@AGENTS.md` dans `CLAUDE.md` ou avec un lien symbolique. Le comportement se modifie dans `/config`, sous Project instructions. Avant septembre, Claude Code ne lisait pas du tout `AGENTS.md`, et l’import était le seul moyen.
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 :
Claude Code peut lire AGENTS.md comme fichier d’instructions du projet : un dépôt déjà configuré pour d’autres agents fonctionne donc sans CLAUDE.md, import ni configuration.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Les fichiers lus par Claude Code dépendent précisément de ceux qui se trouvent dans le projet :
| Fichiers dans le projet | Fichiers lus par Claude Code |
|----|----|
| `AGENTS.md`, sans `CLAUDE.md` ni `CLAUDE.local.md` dans le répertoire de travail ou ses répertoires parents | `AGENTS.md` |
| `AGENTS.md` et `CLAUDE.md` (ou `CLAUDE.local.md`) dans le répertoire de travail ou ses répertoires parents | Uniquement `CLAUDE.md` |
| `CLAUDE.md` contenant la ligne `@AGENTS.md` | `CLAUDE.md`, et `AGENTS.md` à l’intérieur via l’import |
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 :
| Réglage | Fichiers lus par Claude Code |
|----|----|
| `claude-md-or-agents-md` (par défaut) | `CLAUDE.md` ou, s’il n’existe ni `CLAUDE.md` ni `CLAUDE.local.md`, `AGENTS.md` |
| `claude-md-and-agents-md` | Les deux fichiers : dans chaque répertoire, d’abord `CLAUDE.md`, puis `AGENTS.md` |
| `claude-md` | Uniquement `CLAUDE.md` |
| `managed-only` | Uniquement le `CLAUDE.md` d’entreprise géré de manière centralisée et la mémoire automatique |
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 ?
À retenir
Un import est nécessaire lorsque le projet contient un fichier `CLAUDE.md` : s’il existe, Claude Code ne lit pas `AGENTS.md` de lui-même par défaut. Pour le configurer, écrivez la ligne `@AGENTS.md` en haut du fichier `CLAUDE.md`. Au démarrage d’une session, Claude Code remplace cette ligne par le contenu d’`AGENTS.md` et lit le tout comme un seul texte. Sous l’import, vous pouvez ajouter une section « Claude Code » contenant les règles qui ne s’appliquent qu’à Claude. Les imports fonctionnent avec des chemins relatifs et absolus et peuvent être imbriqués sur quatre niveaux au maximum.
Voici un exemple minimal fonctionnel tiré de la documentation officielle :
```markdown
@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 :
Les fichiers CLAUDE.md peuvent importer des fichiers supplémentaires avec la syntaxe @path/to/import. Les fichiers importés sont développés et chargés dans le contexte au démarrage de la session, avec le fichier CLAUDE.md qui y fait référence.
— Anthropic, https://code.claude.com/docs/en/memory
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 ?
À retenir
Anthropic propose deux mécanismes : un import via `@AGENTS.md` ou un lien symbolique, `ln -s AGENTS.md CLAUDE.md`. Un lien symbolique est plus simple : c’est juste un alias et il ne nécessite aucune modification de fichier. Mais il présente trois inconvénients : sous Windows, il faut des privilèges d’administrateur ; vous ne pouvez pas ajouter de règles propres à Claude dans `CLAUDE.md` ; et Git affiche parfois le lien symbolique comme un élément parasite dans le diff. L’import est la solution universelle. Si vous n’avez pas de règles spécifiques à Claude, vous n’avez besoin ni de l’un ni de l’autre à partir de la version 2.1.277 : Claude Code lira lui-même `AGENTS.md`.
La documentation présente ainsi l’option du lien symbolique :
```bash
ln -s AGENTS.md CLAUDE.md
```
Et elle donne immédiatement un avertissement sans détour au sujet de Windows :
Si vous ou une personne qui clone le dépôt travaillez sous Windows, utilisez l’import `@AGENTS.md`. La création d’un lien symbolique nécessite des privilèges d’administrateur ou le mode développeur. De plus, si `core.symlinks` n’est pas activé dans Git, un lien commité est récupéré comme un simple fichier texte : le `CLAUDE.md` de cette copie ne contient alors qu’une ligne au lieu des instructions.
— Anthropic, https://code.claude.com/docs/en/memory
Tableau comparatif :
| Critère | Import `@AGENTS.md` | Lien symbolique `ln -s` |
|----|----|----|
| **Fonctionne sous Windows sans privilèges d’administrateur** | oui | non (mode développeur requis) |
| **Possibilité d’ajouter des règles propres à Claude** | oui, sous l’import | non, le fichier est identique |
| **Apparaît dans Git comme du Markdown ordinaire** | oui | comme un lien (selon `core.symlinks`) |
| **Possibilité d’importer plusieurs fichiers** | oui, jusqu’à quatre niveaux | non, un lien entre deux fichiers |
| **Mise en cache/invalidation dans Claude Code** | standard pour CLAUDE.md | fonctionne, mais les liens symboliques présentent des pièges liés aux métadonnées |
| **Choix par défaut** | convient à tout le monde | seulement si la compatibilité multiplateforme n’est pas importante |
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é](https://ailoot.ai/blog/fr/claude-code-safe-mode-recovery/).
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 ?
À retenir
Chaque outil lit son propre fichier, parfois plusieurs. Claude Code lit `CLAUDE.md` et, depuis septembre 2026, lit également `AGENTS.md` si le projet ne contient pas de `CLAUDE.md`. Codex CLI lit `AGENTS.md` ainsi que `AGENTS.override.md`. Cursor lit l’ancien format `.cursorrules` ou le nouveau `.cursor/rules/*.mdc` et, depuis l’été 2026, lit aussi `AGENTS.md`. Copilot lit `.github/copilot-instructions.md` ou `.github/instructions/*.instructions.md`. Windsurf lit l’ancien `.windsurfrules` ou le nouveau `.windsurf/rules/`. Gemini CLI lit `GEMINI.md`. Aider et Cline ont déjà adopté `AGENTS.md`.
Carte des sept principaux outils (basée sur la documentation officielle de chacun) :
| Outil | Principal fichier d’instructions | Alternatives | Lit-il AGENTS.md ? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, politique gérée | oui, si le projet ne contient pas de `CLAUDE.md` (depuis 2.1.277), sinon via un import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | oui (nativement) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (obsolète) | oui |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | via des extensions |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (obsolète) | oui |
| **Gemini CLI** | `GEMINI.md` | \- | non |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | oui (nativement) |
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 ?
À retenir
`/init` crée un `CLAUDE.md` à partir du contenu déjà présent dans le dépôt et fait gagner 20–30 minutes de travail manuel. Par défaut, il reprend les règles de Cursor (`.cursor/rules/`, `.cursorrules`) et de Copilot (`.github/copilot-instructions.md`), tandis qu’il lit `AGENTS.md`, `.windsurfrules` et `.clinerules` en mode `CLAUDE_CODE_NEW_INIT=1`. Ce même mode lance un parcours interactif en plusieurs phases : il pose des questions, explore le code avec un sous-agent et propose un plan avant d’écrire. Depuis septembre 2026, `/init` a un inconvénient dans un projet avec `AGENTS.md` : un nouveau fichier `CLAUDE.md` désactive la lecture directe d’`AGENTS.md`, et les règles se retrouvent dans deux fichiers.
Anthropic décrit ainsi `/init` dans sa documentation :
L’exécution de /init lit les fichiers d’instructions des autres outils et transfère les éléments pertinents dans le fichier CLAUDE.md généré : les règles de Cursor provenant de .cursor/rules/ ou `.cursorrules`, celles de Copilot provenant de .github/copilot-instructions.md et, avec CLAUDE_CODE_NEW_INIT=1, également `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` ou `.windsurfrules`, ainsi que `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
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 :
```bash
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é](https://ailoot.ai/blog/fr/spec-kit-claude-code-spec-driven-development/).
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 ?
À retenir
Placez dans `AGENTS.md` les règles compréhensibles par n’importe quel agent IA : ce qu’il ne faut pas toucher, comment nommer les branches, le fait que `.env` contient un secret et les commandes à utiliser pour les tests. Placez les règles propres à Claude Code dans `CLAUDE.md` (sous l’import) : mode plan, skills, hooks, références aux skills et noms des modèles selon leur version. La distinction est simple : si une règle commence par « Claude doit », elle appartient à `CLAUDE.md`. Si elle commence par « l’outil doit », elle appartient à `AGENTS.md`.
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](https://ailoot.ai/blog/fr/claude-memory-claude-md-auto-memory/).
- **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 ?
À retenir
Pour un grand projet, un seul fichier `AGENTS.md` ne suffit pas : il devient trop volumineux et chaque agent intègre du contenu inutile à son contexte. La solution consiste à créer un répertoire `.claude/rules/` avec des fichiers distincts par sujet et un frontmatter YAML `paths:` pour les déclenchements en fonction des chemins. Par exemple, une règle d’API ne s’applique que lorsque Claude travaille dans `src/api/`. Cela économise beaucoup de place dans la fenêtre de contexte. L’équivalent pour Cursor est `.cursor/rules/`, et pour Windsurf, `.windsurf/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 :
```markdown
---
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) :
| Niveau | Emplacement | Usage |
|----|----|----|
| **Politique gérée** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Règles d’entreprise, IT/DevOps |
| **Utilisateur** | `~/.claude/CLAUDE.md` | Préférences personnelles pour tous les projets |
| **Projet** | `./CLAUDE.md` ou `./.claude/CLAUDE.md` | Règles de l’équipe projet |
| **Local** | `./CLAUDE.local.md` (dans `.gitignore`) | Préférences personnelles pour un projet donné |
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 ?
À retenir
Si `AGENTS.md` a été assemblé en 2025 pour Codex ou Aider et n’a pas été modifié depuis, ouvrez le projet dans Claude Code et demandez à Claude de modifier le fichier. `AGENTS.md` est un document vivant ; la spécification de la Linux Foundation évolue. La règle principale pour le maintenir à jour : chaque règle doit répondre à la question « Qu’est-ce que je suis fatigué de répéter à Claude/Codex ? » Si elle n’y répond pas, archivez-la.
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 ?
À retenir
L’import `@AGENTS.md` ne rend pas les différents outils identiques. Chacun a ses particularités : Codex CLI ne connaît ni `.claude/rules/` ni les hooks. Cursor dispose de son propre moteur de complétion automatique, qui ne lit pas CLAUDE.md pendant la saisie. Copilot suit `.github/copilot-instructions.md`, et les seules règles présentes dans AGENTS.md ne lui suffisent pas. Il ne s’agit pas de « un fichier = un comportement », mais d’« une source pour les règles de base, puis des ajouts propres à chaque outil ».
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](https://github.com/marketplace?type=apps&category=copilot-extensions) 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`.
### Sources
- [Documentation de Claude Code sur la mémoire – section AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) – quand Claude Code lit AGENTS.md lui-même, réglages Project instructions, imports et liens symboliques, comportement de `/init`.
- [Documentation de Claude Code sur la mémoire – importer des fichiers supplémentaires](https://code.claude.com/docs/en/memory#import-additional-files) – syntaxe `@path/to/file`, profondeur de quatre niveaux, chemins relatifs et absolus.
- [agents.md – standard de la Linux Foundation](https://agents.md/) – standard officiel AGENTS.md et liste des outils compatibles.
- [Documentation des règles de Cursor](https://docs.cursor.com/context/rules-for-ai) – fichiers lus par Cursor (`.cursor/rules/*.mdc`, AGENTS.md).
- [Instructions personnalisées pour GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) – format de `.github/copilot-instructions.md`.
- [Spécification AGENTS.md de la Linux Foundation](https://aaif.io/projects/agents-md/) – spécification évolutive.
Le setup complet de vibe coding pour une soirée : **clone IA + Second Brain + ingénierie du contexte**.
Découvrez [Ailoot](https://ailoot.ai/).
## Questions fréquentes : AGENTS.md commun à Claude Code, Codex et Cursor
### Quand préférer un import à un lien symbolique ?
Utilisez @AGENTS.md dans CLAUDE.md pour des ajouts propres à Claude ou des collègues sous Windows. Un lien symbolique donne le même contenu aux deux noms et ne permet pas une section Claude séparée.
### Comment vérifier le chargement des consignes partagées ?
Lancez /memory et examinez les fichiers listés. Si CLAUDE.md ou CLAUDE.local.md bloque le chargement direct d’AGENTS.md, ajoutez l’import ou choisissez le réglage chargeant les deux, puis ouvrez une nouvelle session.
## Ailoot · L’entreprise et son portefeuille de projets
Ailoot s’appuie sur une expérience opérationnelle éprouvée, une large clientèle, un service stable et un suivi continu des KPI.
L’entreprise et son portefeuille de projets : des millions de clients ; des ventes qui se chiffrent en milliards chaque mois.
Ailoot met cette expérience opérationnelle au service de l’accès API aux fonctions d’IA dans les produits des clients, leurs agents, applications et automatisations.