CLAUDE.md contre AGENTS.md contre SKILL.md : Où placer quoi et pourquoi ?

Tout ceux qui commencent à utiliser Claude Code ont tendance à créer un CLAUDE.md et y mettre tout : la configuration du projet, les règles de codage, les bonnes pratiques pour les demandes de fusion, les détails du stack technique, ainsi que des notes d’intégration. Ensuite, AGENTS.md fait son apparition, suivi de SKILL.md, ce qui donne l’impression qu’il s’agit de trois fichiers pour la même tâche. Ce n’est pas le cas. Les confondre signifie payer pour des tokens qui ne vous sont d’aucune utilité.

Un modèle mental rapide

Imaginez une entreprise. CLAUDE.md est le manuel du salarié que chaque nouvel employé lit dès son premier jour, toujours en arrière-plan. AGENTS.md est le même manuel, rédigé de manière à ce que les prestataires extérieurs de n’importe quelle agence puissent le consulter, et non seulement le personnel permanent. SKILL.md est un manuel sur une étagère que l’on prend uniquement lorsque l’on doit effectuer une tâche spécifique. Trois fichiers, trois rôles et trois modes de chargement.

CLAUDE.md : toujours chargé

C’est le fichier de configuration principal de Claude Code. Au démarrage de la session, Claude le lit et le conserve dans son prompt système. Il est chargé une seule fois, devient partie intégrante du contexte utilisé tout au long de la session, et n’a pas besoin d’être récupéré depuis le disque à chaque message. Ainsi, lorsque vous tapez un salut, ces instructions sont présentes, et elles le restent également lorsque vous demandez plus tard une correction de bug.

La conséquence est qu’un fichier volumineux occupe de manière permanente une partie de la fenêtre de contexte, même pour des tâches où la majeure partie de son contenu est irrelevante. C’est pourquoi un fichier ciblé et court s’avère avantageux.

Trois niveaux

Les instructions proviennent de plusieurs niveaux et sont combinées :

1. Un fichier personnel situé à ~/.claude/CLAUDE.md, contenant des préférences applicables à tous les projets, comme le style d’indentation ou les habitudes pour les messages de commit. Les collègues ne le voient jamais.

Un fichier de projet, soit .claude/CLAUDE.md, soit un fichier situé à la racine du répertoire. Il est commité dans Git, de sorte que tous ceux qui clonent le répertoire reçoivent les mêmes règles. Les détails du stack, les commandes et les normes d’équipe y sont indiqués.

Règles spécifiques à un chemin, stockées sous .claude/rules/ avec une valeur paths dans le frontmatter. Un fichier de règles de test, par exemple, ne peut être chargé que lorsque des fichiers de test sont modifiés, ce qui évite que des indications non pertinentes n’apparaissent dans le contexte.

Des directives de projet plus spécifiques sont chargées après les instructions générales au niveau de l’utilisateur ; ainsi, en cas de conflit entre ces deux types de directives, la version du projet peut prévaloir. Règle pratique : les préférences personnelles sont placées dans la configuration personnelle, tandis que les conventions partagées par l’équipe sont définies dans le projet.

Qu’y figure-t-il ?

Résumez-le. Un objectif raisonnable est de rester sous les 200 lignes, bien que ce soit une indication et non une limite stricte. Ne mentionnez que ce dont Claude a besoin pour chaque tâche : la pile technologique, les commandes utilisées pour exécuter les tests et lancer le serveur de développement, des règles absolues comme ne jamais enregistrer les données des utilisateurs, ainsi que les principales décisions architecturales.

Omettez tout ce qui est spécifique à une tâche. Un guide détaillé pour l’examen d’un PR ou un catalogue de cas limites trouveront mieux leur place ailleurs, comme indiqué ci-dessous.

Un piège

Si vous modifiez CLAUDE.md au cours d’une session en cours, celle-ci ne le remarquera pas. Le fichier a été lu une seule fois au début, donc une nouvelle session est nécessaire pour que les modifications prennent effet. C’est la raison la plus fréquente pour laquelle une règle nouvellement ajoutée semble être ignorée.

AGENTS.md : pour les équipes utilisant plusieurs outils

AGENTS.md sert à la même fin, en contenant le contexte et les instructions du projet. Ce qui diffère, c’est qui peut le lire. Claude Code lit CLAUDE.md, tandis que OpenAI Codex, Cursor, Gemini CLI et GitHub Copilot lisent AGENTS.md.

D’après cette description, Claude Code ne prend pas en charge nativement AGENTS.md, mais un lien symbolique permet de résoudre ce problème en faisant pointer les deux noms vers le même fichier (vérifiez la documentation actuelle au cas où cette fonctionnalité aurait changé) :

ln -s AGENTS.md CLAUDE.md

Désormais, il n’y a qu’un seul fichier que tous les outils lisent, et rien ne s’écarte.

Quand c’est nécessaire

Si toute l’équipe utilise uniquement Claude Code, CLAUDE.md suffit. Si les utilisateurs emploient une combinaison d’outils, ou si le CI exécute un agent différent de celui utilisé localement par les développeurs, AGENTS.md devient votre source unique de vérité pour tous ces éléments.

Perte silencieuse des instructions

Les pipelines multi-agents présentent un mode de défaillance particulièrement problématique. Imaginez qu’une étape s’exécute dans Claude Code et une autre dans un outil d’un fournisseur différent. Si vos règles se trouvent uniquement dans CLAUDE.md, le deuxième outil les ignore sans aucun message d’erreur ou d’avertissement. L’agent fonctionne normalement mais ne respecte pas les conventions que vous pensiez en vigueur. Les résultats deviennent incohérents, le comportement évolue de manière imprévisible, et comme rien ne semble défaillant, il est difficile d’identifier la cause. En utilisant AGENTS.md comme référence commune, chaque outil du pipeline peut voir les mêmes règles.

SKILL.md : chargé sur demande

Celui-ci fonctionne différemment. Les deux autres se chargent au début de chaque session et restent dans le contexte. Une compétence n’est chargée que lorsque la tâche en cours correspond à sa description.

Une compétence est un dossier contenant un SKILL.md. Le fichier commence par une courte en-tête YAML indiquant le nom de la compétence ainsi qu’une description d’une seule ligne, et c’est cette description que Claude lit pour déterminer si la compétence convient. Lorsque vous envoyez un message, Claude le compare aux descriptions de toutes vos compétences et charge celle qui correspond. Une fois la tâche terminée, la compétence est supprimée. Voici à quoi peut ressembler le frontmatter :

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Pourquoi cela économise des tokens

Disons que vous avez documenté dix workflows. Placez-les tous dans CLAUDE.md et ils seront chargés pour chaque message, même pour une demande de correction d’erreur. Parmi les compétences disponibles, seule celle pertinente est chargée, tandis que les neuf autres n’ont aucun coût. Lors de sessions longues combinant différents types de tâches, cela permet de maintenir un contexte épuré axé sur le travail en cours.

La description est la plus importante

Claude s’appuie sur la description pour choisir. Une description vague comme « aide avec le code » ne sera jamais activée ou le sera pour tout. Une description précise, par exemple examiner les demandes de pull en Python à la recherche de vulnérabilités telles que l’injection SQL ou des secrets stockés en dur, se déclenchera de manière fiable et uniquement lorsque c’est pertinent. Le nom du dossier est destiné à vous ; la description est destinée à Claude, alors écrivez-la pour lui.

Deux options utiles de frontmatter

allowed-tools limite ce que Claude peut faire tant que la compétence est active. Pour une compétence qui explore un codebase, en le configurant pour lire, effectuer des recherches grep et glob, Claude peut examiner le contenu sans modifier ou écrire de fichiers, et cette restriction s’applique même si vous demandez une modification.

context: fork exécute le travail de la compétence dans un contexte isolé. Les étapes intermédiaires restent cachées et seul le résultat final est renvoyé à la session principale, ce qui convient aux tâches générant beaucoup de contenu que vous n’avez pas besoin de lire, comme l’analyse de cinquante fichiers pour en obtenir un résumé.

Rendez également les compétences compactes

Une compétence volumineuse consomme plus de contexte une fois chargée. Si un flux de travail nécessite beaucoup de documentation, d’exemples ou de matériel de référence, placez-les dans des fichiers séparés et faites en sorte que la compétence les charge selon les besoins. Les instructions principales doivent rester dans le flux de travail lui-même.

Comparaison des trois méthodes

Comment choisir

• Une règle applicable à chaque tâche lors de chaque session doit être placée dans CLAUDE.md.
• Si l’équipe utilise plusieurs outils de codage IA, ou si le processus les combine, faites de AGENTS.md la source de vérité et liez-y CLAUDE.md.

Un flux de travail spécifique que vous répétez fréquemment, comme l’examen des PR, la création d’un résumé ou la recherche dans la documentation, devrait devenir une compétence.

Si Claude doit rester en mode lecture seule pour un flux de travail, définissez-le comme une compétence avec allowed-tools.

Si vous souhaitez déclencher quelque chose manuellement avec une seule commande, utilisez une commande à barre oblique dans .claude/commands/.

Un layout ordonné

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md reste court car il ne contient que ce dont chaque tâche a réellement besoin. Les compétences gèrent les workflows complexes spécifiques à chaque tâche. AGENTS.md s’assure que tout continue de fonctionner lorsque un collègue change d’outil.

Règle générale

Si CLAUDE.md dépasse 200 lignes, ou environ 1 200 à 1 500 tokens, vous payez probablement pour des instructions inutiles dans la plupart des messages. Classez les instructions en fonction du moment où elles sont nécessaires : « toujours » signifie CLAUDE.md, « entre différents outils » signifie AGENTS.md, et « uniquement pour un type de tâche » signifie une compétence. Votre fenêtre de contexte est comme un budget : le fichier principal en consomme une partie à chaque message, tandis que les compétences n’en consomment qu’au moment où elles sont utilisées, donc concevez votre organisation en fonction de cela.