Pourquoi CLAUDE.md est la clé pour des agents IA performants

Tu as déjà eu l'impression que ton agent IA oublie tout entre deux conversations ?

C'est normal. Les LLMs n'ont pas de mémoire persistante. À chaque conversation, tu dois ré-expliquer qui tu es, ton projet, tes conventions. C'est comme briefer un nouveau dev à chaque fois.

CLAUDE.md : la mémoire de ton agent

C'est là qu'intervient CLAUDE.md. Le fichier principal d'un système de mémoire que Claude Code charge automatiquement à chaque conversation.

L'équipe engineering d'Anthropic ne mâche pas ses mots :

"CLAUDE.md is the single most important file in your codebase for using Claude Code effectively. This file is the agent's 'constitution,' its primary source of truth."

C'est la constitution de ton agent. Sa source de vérité. Le document qui définit qui il est et comment il doit travailler.

Sans ce fichier, ton agent est amnésique. Avec ce fichier, il te connaît.

Et AGENTS.md ?

Tu verras peut-être passer AGENTS.md, un standard ouvert porté par la Linux Foundation. Même concept : un fichier markdown qui donne du contexte à ton agent. La différence ? AGENTS.md est compatible avec plusieurs outils (GitHub Copilot, Cursor, Codex...), alors que CLAUDE.md est spécifique à Claude Code.

Si ton équipe utilise plusieurs outils, rien n'empêche d'avoir les deux.

Un exemple concret

Voici à quoi ressemble un CLAUDE.md simple mais efficace, tiré du blog Anthropic Engineering :

# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker
- npm test: Run tests

# Code style
- Use ES modules (import/export) syntax
- Destructure imports when possible
- Prefer const over let

# Testing
- Run tests before committing
- All new features need tests
- Mock external APIs in tests

Simple. Clair. Efficace. En 15 lignes, l'agent sait comment builder, tester et coder sur ton projet.

Les 3 règles d'or

Trois règles pour optimiser ton CLAUDE.md.

Règle #1 : Moins c'est plus

Selon HumanLayer :

"Keep CLAUDE.md to fewer than 300 lines; aim for less than 60 lines."

Pourquoi ? Les LLMs peuvent suivre environ 150 à 200 instructions de manière fiable. Le system prompt de Claude Code en consomme déjà une cinquantaine. Si ton CLAUDE.md fait 500 lignes, une bonne partie sera ignorée.

Garde ton fichier léger. Va à l'essentiel. Si une règle n'est pas critique, elle n'a pas sa place dans le CLAUDE.md principal. On verra plus bas comment organiser les règles secondaires dans des fichiers séparés.

Règle #2 : Chaque erreur devient une règle

L'équipe Anthropic utilise cette méthode :

"Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time."

Claude push sur main sans demander ? Ajoute "JAMAIS push sur main sans accord explicite".

Ton CLAUDE.md évolue avec le temps. C'est un document vivant. Et si ça semble contredire la règle #1, on va voir juste après comment organiser tout ça.

Règle #3 : Donne des alternatives, pas juste des interdictions

Mauvais :

Ne jamais utiliser le flag --force

Bon :

Ne jamais utiliser --force. Utiliser --force-with-lease à la place.

Pourquoi ? Parce que si tu dis juste "ne fais pas X", l'agent va se retrouver bloqué quand il pensera devoir utiliser X. Donne toujours une alternative.

Organiser avec plusieurs fichiers

Claude Code propose plusieurs niveaux de fichiers (enterprise, projet, local...). Mais le plus utile pour organiser tes règles sans polluer le CLAUDE.md principal, c'est .claude/rules/.

.claude/
├── CLAUDE.md           # Instructions principales (concis)
└── rules/
    ├── code-style.md   # Conventions de code
    ├── testing.md      # Comment tester
    └── security.md     # Règles de sécurité

Tous les fichiers .md dans ce dossier sont automatiquement chargés avec la même priorité que CLAUDE.md. L'avantage ? Tu gardes ton fichier principal court (les infos critiques), et tu organises le reste par thème. Quand une règle devient obsolète, tu la supprimes du bon fichier sans toucher au reste.

Cibler des fichiers spécifiques

La fonctionnalité la plus puissante des rules : le ciblage par chemin. Tu peux faire en sorte qu'une règle ne s'applique que quand Claude travaille sur certains fichiers.

---
paths: src/api/**/*.ts
---
# Règles API
- Valider tous les inputs avec Zod
- Retourner des erreurs cohérentes

Avec ce frontmatter YAML paths, ces règles ne s'activent que quand Claude édite des fichiers dans src/api/. Tes règles API ne polluent pas le contexte quand tu travailles sur du React.

Tu peux cibler plusieurs patterns :

paths:
  - src/components/**/*.tsx
  - src/hooks/**/*.ts

Quelques patterns utiles :

src/api/**/*.ts : tous les fichiers TypeScript dans src/api
*.test.ts : tous les fichiers de test
**/*.css : tous les fichiers CSS du projet

Réutiliser ta doc existante avec les imports

Tu as déjà un README, une doc d'architecture, des guidelines ? Pas besoin de tout recopier dans ton CLAUDE.md ou tes rules. La syntaxe @ permet d'importer n'importe quel fichier.

# Mon Projet

Voir @README.md pour l'overview.
Conventions Git : @docs/git-workflow.md
Architecture : @docs/architecture.md

Au lieu de dupliquer ta documentation, tu pointes vers les fichiers existants. Claude Code les charge automatiquement.

Quelques détails importants de la doc officielle :

Chemins relatifs et absolus supportés
Home directory : @~/.claude/mes-preferences.md pour des fichiers perso pas versionnés
Imports récursifs : un fichier importé peut en importer d'autres (max 5 niveaux)
Ignore le code : @fichier dans un bloc de code n'est pas importé

Tu peux voir tous les fichiers chargés avec la commande /memory.

Commence simple

Crée un fichier CLAUDE.md à la racine de ton projet (ou utilise /init)
Ajoute tes commandes de base (build, test, lint)
Ajoute tes conventions de code principales
Chaque fois que Claude fait une erreur, ajoute une règle (dans .claude/rules/ si ça grossit)

La différence entre un agent qui te fait perdre du temps et un agent qui te rend productif ? Souvent, c'est juste ce fichier.

Sources :