Maîtriser CLAUDE.md — Partie 1 : Les fondamentaux

Si tu utilises Claude Code sans fichier CLAUDE.md, tu laisses de la performance sur la table. C’est comme conduire une voiture de sport en première : ça avance, mais tu n’exploites pas le potentiel de la machine. Dans cette série en 4 parties, on va décortiquer tout ce qu’il faut savoir sur CLAUDE.md. Aujourd’hui : les fondamentaux.

Qu’est-ce que CLAUDE.md ?

CLAUDE.md est un fichier Markdown placé à la racine de ton projet. Son contenu est injecté automatiquement dans le system prompt de Claude Code à chaque requête. C’est la mémoire de ton projet : il décrit l’architecture, les patterns à suivre, les commandes importantes et les erreurs à éviter.

Sans CLAUDE.md, Claude Code doit « deviner » les conventions de ton projet à chaque session. Avec un CLAUDE.md bien structuré, il génère du code cohérent avec ton architecture dès la première requête.

Comment Claude Code lit CLAUDE.md

Voici ce qui se passe sous le capot quand tu lances Claude Code dans un projet :

• Chargement de la config globale (~/.config/claude/)
• Chargement de la mémoire globale utilisateur
• Détection et chargement de CLAUDE.md à la racine du projet
• Chargement de l’historique de session (si reprise)
• Chargement des fichiers @mentionnés

Le prompt final envoyé à Claude ressemble à ceci : System Prompt + Mémoire Globale + CLAUDE.md + Historique + Fichiers + Input utilisateur. CLAUDE.md est donc lu à chaque requête, ce qui en fait l’outil le plus puissant pour guider le comportement de Claude.

La hiérarchie à 3 niveaux de mémoire

Claude Code utilise trois niveaux de mémoire qui se complètent :

• Mémoire globale (~/.claude/CLAUDE.md) — Tes préférences personnelles, valables sur tous tes projets. Exemples : « Je préfère les noms de variables en anglais », « Toujours utiliser des types stricts ».
• Mémoire projet (./CLAUDE.md) — Les règles spécifiques au projet, partagées avec l’équipe via Git. Architecture, patterns, commandes.
• Mémoire locale (./CLAUDE.local.md) — Tes ajustements personnels pour ce projet, non commités. Ajouté automatiquement au .gitignore.

En cas de conflit, la priorité est : Input utilisateur > CLAUDE.local.md > CLAUDE.md > Mémoire globale > System prompt. Le plus spécifique gagne toujours.

Un template minimal pour démarrer

N’essaie pas de tout documenter d’un coup. Commence avec ce template minimal et enrichis-le au fil du temps :

# Projet MonApp

## Architecture
src/
├── Controller/    # HTTP endpoints
├── Service/       # Logique métier
├── Repository/    # Accès données
├── Entity/        # Modèles Doctrine
└── DTO/           # Data Transfer Objects

## Patterns obligatoires
- Logique métier dans les Services, jamais dans les Controllers
- Injection de dépendances via le constructeur
- Types stricts partout (declare(strict_types=1))

## Commandes
make dev          # Lance l\'environnement Docker
make test         # Lance les tests PHPUnit
make quality      # PHPStan + CS Fixer + Tests

## Erreurs à éviter
- Pas de logique métier dans les Controllers
- Pas de requêtes Doctrine dans les Services
- Pas de var_dump/dd en production

Pourquoi le contexte détermine la qualité

Un LLM génère du code en fonction de son contexte. Si ton contexte est vide, le résultat sera générique. Si ton contexte est précis (architecture, patterns, erreurs à éviter), le résultat sera aligné avec les standards de ton projet. CLAUDE.md est le levier le plus simple et le plus efficace pour améliorer la qualité du code généré par Claude.

D’après les bonnes pratiques Anthropic, un CLAUDE.md optimal fait entre 200 et 500 lignes. Au-delà, il faut déléguer les détails dans des fichiers séparés (.claude/rules/) et utiliser les Skills pour le lazy loading.

La suite de la série

Dans les prochains articles, on abordera les techniques avancées : comment structurer un CLAUDE.md pour un gros projet, le pattern Document & Clear pour les sessions longues, et l’optimisation du contexte avec les Skills. Si tu veux aller plus vite et maîtriser l’ensemble des fonctionnalités de Claude Code, notre formation Claude Code couvre tout, du CLAUDE.md aux subagents en passant par les hooks et l’intégration CI/CD, sur les projets de ton équipe.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours