CLAUDE.md : où le mettre, quoi écrire et comment il s’accorde avec AGENTS.md

Ce qu’est CLAUDE.md

Claude Code démarre chaque session sans souvenir de la précédente. CLAUDE.md est le moyen de lui donner le contexte dont un nouveau coéquipier aurait besoin : il est lu au lancement et envoyé à Claude comme un message après le system prompt. C’est donc du contexte, pas une configuration imposée. Claude le suit généralement, mais ce qui doit toujours ou jamais arriver relève des hooks ou des règles de permission.

• Du markdown simple, sans champ obligatoire : des titres et de courtes puces fonctionnent le mieux.
• Les fichiers se combinent, ils ne s’écrasent pas : chaque CLAUDE.md applicable est chargé, donc des lignes contradictoires laissent Claude en choisir une.
• Vérifiez ce qui a été chargé avec /context all, sous Memory files.

Où placer les fichiers CLAUDE.md et dans quel ordre ils se chargent

Claude Code les charge du plus large au plus précis, si bien que le fichier le plus proche de l’endroit où vous avez lancé la commande est lu en dernier. Il remonte aussi depuis votre répertoire de travail et charge le CLAUDE.md de chaque répertoire parent.

Comment écrire un CLAUDE.md efficace

1. Commencez par /init

   Lancez /init dans votre projet. Claude Code lit le code et écrit un CLAUDE.md de départ ; s’il en existe déjà un, il propose des améliorations au lieu de l’écraser. Il reprend aussi .cursorrules et les instructions Copilot.

2. Ne gardez que ce que Claude ne trouve pas seul

   Gardez les commandes exactes de build, de test et de lint (dont celle pour lancer un seul test), les endroits où le code est trompeur, les décisions qui ne sont écrites nulle part et tout ce que vous avez dû corriger deux fois. Retirez les arborescences de fichiers et l’architecture que Claude peut lire dans le dépôt. Anthropic recommande de rester sous 200 lignes.

   # Commandes
   - Installer : pnpm install
   - Un seul fichier de test : pnpm vitest run path/to/file.test.ts
   - Typecheck : pnpm tsc --noEmit
   
   # Conventions
   - Lève les erreurs avec les helpers de src/lib/errors.ts, jamais avec des chaînes brutes.
   - src/legacy/ est toujours en service, mais ne copie pas ses patterns.
   
   # Pièges
   - Les tests d’intégration ont besoin de DATABASE_URL (voir .env.example).

3. Soyez précis, sans crier

   Écrivez « Indente avec 2 espaces », pas « Formate bien le code ». La documentation actuelle juge IMPORTANT et les MAJUSCULES dépassés : ils poussent Claude à appliquer une règle à l’excès. Si une ligne est encore oubliée, raccourcissez le fichier ou transformez la règle en hook.

4. Découpez avec les imports et les règles

   @path/to/file importe un autre fichier (relatif au fichier qui importe, sur quatre niveaux au maximum) ; un @ entre backticks reste littéral. Les règles qui concernent une partie du code vont dans .claude/rules/ avec un glob paths, et ne se chargent que lorsque Claude touche des fichiers correspondants.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - Chaque handler valide son entrée avec le schéma de src/api/schemas/.

5. Déplacez les procédures dans des skills

   Les workflows en plusieurs étapes, comme publier une version, relèvent d’une skill (.claude/skills/<name>/SKILL.md), qui ne se charge que lorsqu’elle est pertinente. CLAUDE.md est lu à chaque tâche, donc chaque ligne coûte de l’attention.

6. Gardez-le à jour

   Ajoutez une ligne quand Claude répète une erreur ou qu’une relecture relève un problème, et modifiez le fichier avec /memory ou en demandant à Claude de le mettre à jour. /doctor propose des coupes quand le fichier devient trop long.

Source : documentation de Claude Code, How Claude remembers your project

CLAUDE.md et AGENTS.md

AGENTS.md est un format ouvert d’instructions pour les agents de code, utilisé par Codex, Cursor, Gemini CLI, l’agent de code de GitHub Copilot, opencode et bien d’autres. Claude Code le lit désormais aussi, mais par défaut seulement quand le projet n’a pas de CLAUDE.md.

Un seul fichier pour Claude Code et Codex

Si votre équipe utilise les deux agents, gardez les instructions communes dans AGENTS.md et faites-les importer par CLAUDE.md, avec en dessous les notes réservées à Claude. Il ne se charge jamais deux fois. Un lien symbolique (ln -s AGENTS.md CLAUDE.md) fonctionne aussi, mais pas pour les coéquipiers sous Windows, et un CLAUDE.md qui se contente de dire « lis AGENTS.md » en toutes lettres n’est pas fiable.

• Le dépôt de ce site fait exactement cela : son CLAUDE.md tient en une seule ligne, @AGENTS.md.
• Codex lit les fichiers AGENTS.md depuis la racine du dépôt jusqu’à votre répertoire de travail et plafonne leur taille cumulée à 32 KiB par défaut.

Limites et pièges

• Un CLAUDE.md chargé au lancement est lu en entier jusqu’à 4 MiB ; un fichier plus gros est ignoré.
• Les fichiers chargés à la demande, comme les CLAUDE.md de sous-répertoires et les règles par chemin, sont tronqués au-delà d’une limite par fichier (40 000 caractères avec une fenêtre de contexte de 200K).
• Les imports organisent un fichier mais n’économisent pas de contexte : le texte importé est tout de même chargé.
• Les imports hors du projet demandent une approbation une fois ; les commentaires HTML <!-- --> sont retirés et ne coûtent rien.
• Le CLAUDE.md à la racine du projet est relu après /compact.
• « Retiens ça » va dans l’auto memory (~/.claude/projects/<project>/memory/), pas dans CLAUDE.md.

CLAUDE.md dit comment travailler. Crewmark dit sur quoi travailler, et quand.

Un bon CLAUDE.md fait démarrer chaque session de Claude Code bien informée, mais la session attend toujours votre prochain message. Crewmark transforme une session Claude Code, Codex, DeepSeek Harness ou OpenCode en employé IA avec un rôle, un objectif et des horaires de travail, et la réveille à intervalle régulier (heartbeat) pour qu’elle prenne la prochaine issue d’un tableau.

1. Transformez une session en employé

   Choisissez un rôle, comme ingénieur logiciel ou spécialiste SEO, écrivez son objectif sous forme de chiffre et lancez la commande d’installation dans votre projet, là où se trouve déjà votre CLAUDE.md.

2. Laissez le heartbeat lancer le travail

   Pendant ses horaires de travail, l’employé se réveille toutes les 15, 30 ou 60 minutes dans la même conversation ; voir comment rendre Claude Code proactif. Plusieurs peuvent partager un dépôt, comme dans plusieurs agents Claude Code.

3. Assignez des issues et répondez à ses messages

   Mettez le travail sur le tableau ; l’employé le prend, commente au fil de l’eau et vous écrit quand il a besoin d’une décision. Lisez ce qu’est un employé IA.

FAQ CLAUDE.md