CLAUDE.md et AGENTS.md : mes conseils après 42 projets

Mise à jour (9 novembre 2026) : Claude Fable 5.2 et Mythos 5.2 sont sortis - prix, accès et benchmarks dans mon guide Claude Fable 5.2.

👁 113 lectures

Sur mon disque, j’ai 42 fichiers d’instructions pour agents IA : 16 fichiers CLAUDE.md et 26 fichiers AGENTS.md, chacun dans un dossier de projet différent. Le plus court tient sur une ligne, le plus long en compte 402. Ce dernier fait deux fois la longueur recommandée par Anthropic. Je commence par lui, car il montre bien ce qu’on met réellement dans ce type de fichier.

À quoi sert un fichier CLAUDE.md ?

C’est un fichier Markdown ordinaire que Claude Code lit au début de chaque session. Chaque conversation avec l’agent repart de zéro : tout ce qu’il ne peut pas déduire du code doit lui être expliqué à nouveau. CLAUDE.md s’en charge : commandes de test, règles du projet, actions interdites et pièges déjà rencontrés.

La documentation de Claude Code précise qu’il s’agit de contexte, pas d’une configuration stricte. L’agent suit généralement les instructions du fichier, mais il n’y est pas obligé. Pour interdire systématiquement une action, comme supprimer des fichiers ou déployer sur un serveur, utilisez des hooks et les autorisations dans les paramètres, pas une phrase dans CLAUDE.md.

Où placer CLAUDE.md et quels fichiers sont lus ?

Plusieurs fichiers peuvent être lus simultanément. Claude Code n’en choisit pas un seul : il rassemble tous ceux qu’il trouve, du plus général au plus proche du dossier de travail.

Les fichiers situés dans les dossiers parents du répertoire où vous lancez l’agent sont lus immédiatement. Ceux des sous-dossiers ne le sont que lorsque l’agent commence à y lire ou modifier des fichiers. Ainsi, dans un grand dépôt, les instructions pour le frontend ne prennent pas de place lorsque l’agent travaille sur la base de données.

Vous pouvez générer une première version avec la commande /init. Claude examine le code et consigne les commandes et conventions qu’il repère. C’est un bon point de départ, mais j’ajoute toujours le reste à la main : les lignes les plus utiles sont celles qu’on ne peut pas déduire du code.

Mon fichier le plus long : 402 lignes

La documentation recommande de limiter chaque fichier CLAUDE.md à moins de 200 lignes : un fichier plus long consomme du contexte et l’agent suit moins bien ses instructions. Le fichier de mon projet Jantaris fait 402 lignes et 46 095 octets. Sur mes 16 fichiers CLAUDE.md, c’est le seul qui dépasse cette limite ; la médiane est de 35 lignes.

Il ne s’est pas écrit d’un seul coup. Je l’ai enrichi de pièges rencontrés après chaque erreur : comment le serveur met les images en cache et pourquoi le remplacement d’un fichier sous le même nom n’arrive aux utilisateurs qu’une semaine plus tard, combien d’inscriptions par heure le mécanisme de protection autorise et comment les tests doivent le réinitialiser, où se trouve le serveur et comment les e-mails sont envoyés. Chaque ligne garde la trace d’un problème concret. À la fin, le fichier était devenu trop long.

À mes yeux, CLAUDE.md n’est pas la documentation du projet, mais une carte des pièges. L’agent peut trouver dans le code et le README comment l’application fonctionne. CLAUDE.md doit contenir ce que le code ne révèle pas, mais qui a déjà posé problème. Quand le fichier dépasse 200 lignes, je le répartis dans des fichiers thématiques sous .claude/rules/. L’import avec @fichier.md aide à organiser le contenu, mais le fichier importé est tout de même chargé en entier.

Un exemple de 34 lignes pour Claude Code

Voici un exemple utile : le fichier CLAUDE.md du projet « Base de réparations », une application pour un atelier automobile que nous construisons de zéro dans ma formation Créer un SaaS en un week-end avec Claude Code. Voici le fichier complet, sans raccourci. Le texte ci-dessous est la traduction du fichier d’origine, rédigé en polonais.

# Base de réparations - notes pour l’agent

Produit, écrans et règles : @SPEC.md
Construis uniquement la section INDISPENSABLE de SCOPE.md. Toute idée qui n’y figure pas doit être ajoutée à PLUS TARD, avec une condition de reprise, puis soumise à mon approbation.

## Stack technique
- Node 22.13+, aucune dépendance npm : node:http, node:sqlite, node:test, fetch.
- SQLite dans data/app.db, migrations dans migrations/NNN_nom.sql.
- HTML rendu côté serveur, JavaScript natif dans le navigateur.

## Commandes
- npm run dev                 serveur sur le port 8080, redémarrage après modification d’un fichier
- npm test                    node --test "test/*.test.js" (glob entre guillemets)
- npm run reset               base recréée + données de test + comptes de test
- python tools/captures.py URL captures en 1440 px et 390 px dans data/shots/

## Règles
- Montants stockés en unités monétaires entières (INTEGER). Jamais de nombres à virgule flottante.
- Les limites des offres (R1-R3) sont vérifiées par le serveur. Le navigateur les affiche seulement.
- Chaque règle R de SPEC.md doit avoir un test dont le nom contient son numéro.
- Enregistre les fichiers texte avec des fins de ligne LF.
- Dans les contenus, utilise uniquement le trait d’union "-". Un test vérifie tous les modèles.

## Interdictions
- Ne lis pas .env. Ne déploie pas. Ne fais pas git push, git reset ou git clean.
- Ne lance pas les tests sur data/app.db (les tests utilisent une base en mémoire).
- N’importe pas de données propriétaires (Autodata, HaynesPro, portails des fabricants) :
  licences des fabricants et protection des bases de données dans l’UE.

## Pièges
- Git Bash transforme les chemins : ajoute MSYS_NO_PATHCONV=1 avant une commande avec /...
- Pour les fichiers contenant des expressions régulières, utilise un outil d’écriture de fichiers,
  pas un heredoc dans bash (les antislashs disparaissent).

Chaque section répond à un besoin précis :

• Un renvoi vers les spécifications. La description du produit se trouve dans SPEC.md, que CLAUDE.md importe. La consigne de s’en tenir à la section INDISPENSABLE évite que l’agent s’éloigne du périmètre. Sans elle, vous pouvez vous retrouver une heure plus tard avec des fonctionnalités que personne n’a demandées.
• Des commandes avec leur syntaxe exacte. Mettre le glob entre guillemets dans la commande de test est un détail facile à oublier, alors qu’il détermine si tous les fichiers de test seront exécutés.
• Des règles vérifiables. Des montants en unités entières, des limites vérifiées côté serveur et un test pour chaque règle. « Écris du code propre » ne se vérifie pas.
• Des interdictions. Je répète les plus importantes dans les paramètres d’autorisations, car le fichier ne fait que formuler une demande.
• Les pièges liés à l’environnement. Windows et Git Bash altèrent les chemins qui commencent par une barre oblique. L’agent ne le sait pas tant qu’une commande n’échoue pas.

La ligne qui m’a coûté une relecture éditoriale

Un exemple illustre bien l’intérêt de ces instructions. Le 30 octobre, pendant la révision des textes du magazine DYGOT, un script qui récupère l’état actuel depuis le serveur a été lancé entre deux corrections, avant l’envoi des fichiers. Il a écrasé les modifications locales et fait perdre la première passe de révision. Depuis, le fichier d’instructions du projet contient cette phrase : « À lancer UNIQUEMENT avant le travail : entre la modification et l’envoi, le script écrasera tes changements. » Aucun générateur ne l’aurait ajoutée : le code du script ne dit pas quand il est prudent de le lancer.

AGENTS.md : des instructions pour plusieurs agents

AGENTS.md est un fichier d’instructions du même type, sous un nom lu par différents outils : Codex d’OpenAI, Cursor, Gemini CLI, l’agent GitHub Copilot et une dizaine d’autres. Le format est piloté par l’Agentic AI Foundation, au sein de la Linux Foundation. J’ai 26 fichiers AGENTS.md ; ils sont courts, avec une médiane de 8 lignes, car la plupart décrivent une tâche graphique précise pour Codex.

Claude Code sait aussi lire AGENTS.md depuis la version 2.1.277. Par défaut, il ne le fait que si le projet ne contient pas de fichier CLAUDE.md. Si les deux sont présents, Claude lit son propre fichier et ignore AGENTS.md. Pour que les deux outils reçoivent les mêmes règles, le plus simple est de les placer dans AGENTS.md et d’ajouter une ligne d’import @AGENTS.md dans CLAUDE.md. J’explique comment transférer l’ensemble, y compris les skills et les serveurs MCP, dans mon article comment passer de Claude Code à Codex.

Dans les projets où Claude et Codex se relaient, j’ajoute une autre règle à la fin du fichier : après son travail, l’agent doit ajouter une entrée au journal partagé, avec la date, le nom de l’agent et la liste des changements. L’agent suivant lit le journal avant de commencer et sait ce que le précédent a modifié. C’est plus simple que de synchroniser la mémoire des deux outils.

Ce que je ne mets pas dans CLAUDE.md

• Clés et mots de passe. Le fichier du projet se retrouve souvent dans le dépôt. Dans mes fichiers, j’interdis plutôt de lire .env que d’en recopier le contenu.
• Arborescence des dossiers. L’agent la découvre en quelques secondes ; une description dans le fichier devient obsolète au premier changement.
• Généralités. « Veille à la qualité » ne change rien. « Chaque règle doit avoir un test dont le nom contient son numéro » change les choses.
• Règles contradictoires. La documentation avertit qu’en présence de deux instructions opposées, Claude peut choisir l’une ou l’autre. Je relis mes fichiers de temps en temps et supprime ce qui n’est plus valable.
• Notes destinées aux humains. Si elles doivent rester dans le fichier, je les place dans un commentaire HTML <!-- -->. Claude Code retire ces commentaires avant de lire le fichier : ils ne consomment donc pas de contexte.

Par où commencer avec CLAUDE.md ?

Si vous débutez avec Claude Code, ne rédigez pas un fichier CLAUDE.md à l’avance. Lancez /init, gardez ce qui est pertinent, puis ajoutez une ligne chaque fois que l’agent commet la même erreur pour la deuxième fois. Au bout d’une semaine, vous aurez un fichier qui décrit votre projet, pas celui d’un guide. Je présente l’installation et les premières étapes dans le guide installer Claude Code, et le coût des offres dans l’article combien coûte Claude Code ?.

Dans ma formation Créer un SaaS en un week-end avec Claude Code, nous préparons pas à pas les spécifications et le fichier CLAUDE.md : 30 leçons, de la vérification de la demande pour une idée jusqu’au déploiement sur son propre serveur, en passant par la base de données, la connexion et les paiements.

Sources et date de vérification

Informations vérifiées le 6 novembre 2026.

• Fichiers CLAUDE.md et AGENTS.md de mes projets : 42 fichiers après exclusion des copies et des dépôts d’autres personnes, comptabilisés le 6 novembre 2026.
• Claude Code - documentation : How Claude remembers your project (CLAUDE.md, AGENTS.md, imports, limite de 200 lignes)
• AGENTS.md - présentation du format

// lire la suiteClaude Sonnet 5.5 vaut-il le coup pour votre projet ?ActualitésFrameworks pour agents IA : LangGraph, CrewAI, OpenAI ou Claude ?BenchmarksCréer un site avec Claude Code : méthode et tarifsGuides

Kinetyra