Maîtriser CLAUDE.md — Partie 2 : Conventions et patterns

Dans le premier article de cette série, tu as découvert le rôle du fichier CLAUDE.md et son mécanisme d'injection dans les prompts. Aujourd'hui, on passe à la pratique : comment dimensionner ton CLAUDE.md, quelles conventions documenter, et comment exploiter la hiérarchie multi-niveaux pour un projet Symfony.

La taille idéale : le sweet spot

Un CLAUDE.md trop court et Claude manque de contexte. Trop long et tu gaspilles des tokens à chaque requête. La zone optimale se situe entre 200 et 500 lignes. Au-delà de 1 000 lignes, il est temps de découper.

• ~100 lignes — Minimum viable : architecture + patterns essentiels
• 200-500 lignes — Sweet spot : complet mais concis
• ~1 000 lignes — Maximum : au-delà, externalise dans docs/ ou .claude/rules/

Un point crucial : ne compresse jamais ton CLAUDE.md. Une étude montre qu'une compression de 18 000 tokens à 122 tokens fait chuter la précision de 66,7 % à 57,1 %. Mieux vaut ajouter des entrées structurées que de tout condenser.

Documenter tes conventions de code

Le CLAUDE.md n'est pas un remplacement de ton linter. Les règles de style de code (PSR-12, espacement, etc.) appartiennent à PHP-CS-Fixer et PHPStan, pas à CLAUDE.md. En revanche, ce que ton linter ne peut pas capturer — les décisions architecturales, les patterns métier, les conventions de nommage sémantiques — c'est exactement ce qui doit y figurer.

Voici ce qui a sa place dans ton CLAUDE.md :

• Naming sémantique — Classes suffixées par leur rôle : CreateUserCommand, UserRepository, OrderStatus
• Patterns architecturaux — CQRS, architecture hexagonale, factory methods obligatoires
• Règles métier — Ne jamais exposer les IDs internes, toujours valider les inputs avec des Value Objects
• Commandes projet — make test, make lint, make db-migrate
• Erreurs à éviter — Pas de logique métier dans les controllers, pas de any/mixed en PHP

La hiérarchie à 4 niveaux

Claude Code charge les fichiers CLAUDE.md selon une hiérarchie stricte. Chaque niveau surcharge le précédent :

# Niveau 1 (priorité basse) — Global, tous projets
~/.claude/CLAUDE.md

# Niveau 2 — Projet, partagé en équipe (committé dans Git)
./CLAUDE.md

# Niveau 3 — Sous-répertoire (chargé à la demande)
./frontend/CLAUDE.md

# Niveau 4 (priorité haute) — Local, préférences personnelles
./CLAUDE.local.md    # Ajouté automatiquement au .gitignore

Le niveau 3 est particulièrement intéressant : les fichiers CLAUDE.md des sous-répertoires ne sont chargés que lorsque Claude accède à ce dossier. C'est du lazy loading natif qui économise des tokens sur les gros projets.

--add-dir : le multi-repo enfin propre

Depuis la version 2.1.20, le flag --add-dir permet de charger des fichiers CLAUDE.md depuis des répertoires externes. C'est idéal pour centraliser les standards d'équipe dans un repo dédié :

# Charger les conventions d'équipe en plus du projet
claude --add-dir ~/team-standards

# Plusieurs sources
claude --add-dir ~/team-standards --add-dir ~/company-rules

# Le CLAUDE.md du projet a toujours priorité en cas de conflit

Exemple production : CLAUDE.md pour un projet Symfony

Voici un CLAUDE.md complet et réaliste pour un projet Symfony en architecture hexagonale. Il fait ~350 lignes — pile dans le sweet spot.

# Projet MonApp

## Stack
- PHP 8.3, Symfony 7.2, PostgreSQL 16, Redis
- Architecture hexagonale (Domain / Application / Infrastructure)
- CQRS avec Symfony Messenger

## Architecture
src/
├── Domain/          # Logique métier pure (zéro dépendance framework)
│   ├── Entity/      # Entités avec factory methods
│   ├── ValueObject/ # Immutables, readonly
│   ├── Repository/  # Interfaces uniquement
│   └── Event/       # Domain events
├── Application/     # Use cases
│   ├── Command/     # Write operations
│   └── Query/       # Read operations
├── Infrastructure/  # Doctrine, Symfony, services externes
└── Presentation/    # Controllers slim, DTOs

## Patterns obligatoires
- Entités : constructeur privé + factory method create()
- Value Objects : final readonly class
- Repositories : interface dans Domain/, implémentation dans Infrastructure/
- Controllers : maximum 10 lignes, délègue au CommandBus/QueryBus

## Commandes
make test            # PHPUnit
make lint            # PHP-CS-Fixer + PHPStan level max
make db-migrate      # Doctrine migrations
make quality         # Tout en une fois

## Règles critiques
- JAMAIS de logique métier dans les controllers
- JAMAIS de dépendance Symfony/Doctrine dans Domain/
- TOUJOURS declare(strict_types=1)
- TOUJOURS des tests pour tout nouveau code
- TOUJOURS valider les inputs avec des DTOs + Assert

Organisation avancée avec .claude/rules/

Quand ton projet grandit, déplace les conventions détaillées dans des fichiers séparés. Claude les charge via les @mentions ou les Skills :

projet/
├── CLAUDE.md                    # Lean : stack + architecture + règles critiques
├── CLAUDE.local.md              # Préférences personnelles (non committé)
└── .claude/
    └── rules/
        ├── architecture.md      # Détails hexagonale
        ├── security.md          # OWASP, voters, validation
        ├── testing.md           # Standards PHPUnit
        └── api-design.md        # Conventions REST

Avec cette approche, ton CLAUDE.md principal reste sous 150 instructions directes — le budget recommandé — tandis que les détails sont chargés à la demande.

Dans le prochain article de la série, on passera aux commandes custom et aux agents : comment créer tes propres slash commands, structurer le répertoire .claude/commands/, et utiliser le système de Skills pour un lazy loading intelligent. Si tu veux aller plus loin dès maintenant, notre formation Claude Code Mastery couvre l'ensemble de ces techniques en profondeur.