CLAUDE.md minimal : guide pratique pour Claude Code

Phrase d’accroche — un CLAUDE.md bien fait évite des erreurs récurrentes des agents et accélère les tâches de devs.

Tu as déjà vu un agent qui modifie le mauvais package, lance la mauvaise commande ou oublie où sont les tests ? Un CLAUDE.md minimal et ciblé règle souvent ces problèmes en moins de 10 lignes.

---

Pourquoi créer un CLAUDE.md minimal

Les agents qui lisent ton dépôt ont besoin d’instructions précises : quel package cibler, quelles commandes lancer, et ce qu’il ne faut pas toucher. Un fichier long ou vague augmente le bruit contextuel et la consommation de tokens.

Valeur immédiate : un fichier CLAUDE.md packagé correctement réduit les aller-retour inutiles de l’agent et diminue les erreurs de contexte quand tu demandes une tâche sur un sous-module.

Ce que doit contenir un CLAUDE.md minimal

1. Le package ciblé (chemin clair)
2. Les commandes exactes et reproductibles (install, dev, test, build)
3. Où chercher le code critique (chemins précis)
4. Les limites à ne pas toucher (migrations, infra)
5. Une petite section “Claude-specific” : quick debug steps et commandes de smoke-test

Exemple minimal (copier-coller)

# CLAUDE.md

## Package ciblé
packages/frontend

## Commandes (exactes)
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm --filter=@myorg/frontend dev`
- Test: `pnpm --filter=@myorg/frontend test -- --runInBand`

## Où chercher
- `packages/frontend/src`
- `packages/frontend/components`

## Limites : NE PAS TOUCHER
- `prisma/migrations/`
- `infra/terraform/`

## Claude-specific
- Pour debug : `cat logs/last-error.log` puis ouvrir `packages/api/src`

Ce template vient du référentiel de templates internes et a fait ses preuves sur des monorepos (voir nos références).

Checklist d’intégration rapide (5 minutes)

• Place le fichier à la racine du package (packages/frontend/CLAUDE.md).
• Raccourcis : 10–20 lignes maximum.
• Test : demande à l’agent “corrige le bug X dans packages/frontend” et vérifie qu’il suit les commandes listées.

Cas d’usage concrets

• Reproduire un bug localement (l’agent te donne la commande exacte à lancer).
• Refactorer un composant sans toucher la base de données (le champ “NE PAS TOUCHER” guide l’agent).
• Générer un patch testable : l’agent exécute pnpm --filter=@myorg/frontend test avant d’ouvrir une PR draft.

Les pièges courants (et comment les éviter)

• Trop d’informations : le file devient « autoguide » et l’agent s’y perd — garde le focus package-by-package.
• Instructions vagues : écrire “regarde les tests” est insuffisant — indique le chemin exact.
• Duplicate context : évite la duplication avec AGENTS.md ; référence-le au besoin (@AGENTS.md).
• Fichiers sensibles : marque explicitement les dossiers à ne pas modifier.

Intégration avec claude-mem et outils agents

• Si tu utilises claude-mem (repo cité dans nos références), un CLAUDE.md court réduit le “context noise” que la mémoire réinjecte.
• Pour les monorepos, préfère plusieurs CLAUDE.md par package plutôt qu’un seul fichier massif.

Et maintenant ? (ce qu’il faut retenir)

• Règle d’or : précis > exhaustif.
• Commence par le package le plus critique, teste l’agent, puis généralise.
• 10–20 lignes suffisent dans la majorité des cas.

---

Sources et lectures recommandées

• Template interne : references/claude-md-monorepo-template.md (template réutilisable)
• claude-mem (GitHub) — outil de mémoire pour Claude (référence dans nos notes)
• Claude Code best practices — documentation officielle (lien dans nos références)
• Études récentes sur le bruit contextuel et les mémoires d’agents (voir nos références arXiv mentionnées)

Questions fréquentes

Q: Où mettre le CLAUDE.md pour un monorepo ? R: Dans le dossier du package ciblé (ex: packages/frontend/CLAUDE.md) — évite un seul fichier racine si le repo est grand.

Q: Combien de lignes maximum ? R: Vise 10–20 lignes. Si tu as besoin de plus, c’est que le scope doit être réduit.

Q: Est-ce que l’agent doit exécuter les commandes depuis la racine ? R: Indique la commande exacte avec le filtre de package (pnpm --filter=...) pour éviter toute ambiguïté.