CLAUDE.md : le fichier mémoire IA de votre projet expliqué

Qu'est-ce que CLAUDE.md ?

CLAUDE.md est un fichier Markdown qui fournit à Claude Code des instructions et un contexte spécifiques au projet. Considérez-le comme de la documentation d'intégration pour votre programmeur binôme IA.

Quand Claude Code démarre, il lit automatiquement :

1. →CLAUDE.md du projet : .claude/CLAUDE.md ou CLAUDE.md à la racine de votre projet
2. →CLAUDE.md utilisateur : ~/.claude/CLAUDE.md pour les préférences personnelles sur tous les projets
3. →Répertoires parents : les fichiers CLAUDE.md dans les dossiers parents (pour les monorepos)

Ce système en couches vous permet de définir des préférences globales tout en les remplaçant par projet.

Pourquoi CLAUDE.md est important

Sans CLAUDE.md, Claude Code :

• →Ne connaît pas vos conventions de codage
• →Peut suggérer des patterns qui ne correspondent pas à votre base de code
• →Nécessite des explications répétées de votre architecture
• →Pourrait toucher des fichiers qu'il ne devrait pas

Avec un CLAUDE.md bien conçu, Claude Code :

• →Suit les standards de codage de votre équipe
• →Comprend votre architecture et vos patterns
• →Sait quelles zones sont interdites
• →Fournit une assistance cohérente et adaptée au projet

Ce qui va vraiment dans un bon CLAUDE.md (et ce qui n'y va pas)

Le discours sur CLAUDE.md a significativement maturé depuis que le fichier est devenu une partie standard du workflow Claude Code d'Anthropic. Les threads sur r/ClaudeAI, r/ChatGPTCoding et r/ExperiencedDevs montrent un pattern : les équipes qui démarrent avec des fichiers CLAUDE.md exhaustifs les réécrivent en quelques semaines une fois qu'elles réalisent ce qui fait vraiment bouger l'aiguille.

Ce qui aide vraiment :

• →Les 3-5 décisions qui façonnent votre codebase. Choix de framework, philosophie de tests, style de gestion d'erreurs, patterns de base de données, conventions de nommage. Claude les utilise comme ancres quand il écrit du code.
• →Une brève liste « ne pas toucher ». Dossiers vendor, code généré, chemins sensibles spécifiques. La denylist a plus de valeur que l'allowlist parce que la plupart des fichiers sont OK.
• →Les commandes exactes pour lancer tests, lint, typecheck, build. Claude les utilise sans les ré-inférer, économisant des tokens et prévenant les erreurs de mauvaise commande.
• →Exemples nommés de bons patterns. « Voir src/api/users.ts pour la structure de controller canonique. » Le pointeur-vers-exemple bat la description en prose.
• →Invariants non-évidents. Tout ce qu'un ingénieur senior expliquerait le jour un qui n'est pas documenté ailleurs.

Ce qui fait mal discrètement :

• →Essais architecturaux complets. Claude lit CLAUDE.md à chaque démarrage. Les longs documents consomment le budget de contexte et diluent les sections à haut signal.
• →Information disponible en lançant l'outillage. Ne dupliquez pas le contenu de package.json, tsconfig ou ESLint config. Claude les lit nativement.
• →Standards aspirationnels que vous n'appliquez pas. Si la codebase viole régulièrement une règle, Claude le fera aussi, mais il gaspillera des tokens à prétendre la suivre. Soit appliquez-la en CI, soit retirez-la de CLAUDE.md.
• →Branding d'entreprise, historique de projet, copy marketing. Non pertinent pour la génération de code.
• →Secrets, credentials ou URLs internes. Traitez CLAUDE.md comme publiquement visible. Utilisez .env et git-secrets à la place.

Patterns avancés qui scalent vraiment :

• →Fichiers CLAUDE.md en couches. Un CLAUDE.md racine pour les conventions monorepo-wide ; des fichiers par-package pour le contexte spécifique. Les docs d'Anthropic décrivent le comportement de merge.
• →~/.claude/CLAUDE.md niveau utilisateur pour les préférences personnelles. Langue préférée, verbosité, style de message de commit. Garde les fichiers niveau projet focalisés sur la codebase.
• →Élagage périodique. Un CLAUDE.md qui a grandi organiquement est généralement 40% de bruit. Mettez un rappel trimestriel pour dépouiller tout ce qui ne mérite pas ses tokens.
• →.claudeignore est aussi important que CLAUDE.md. Gardez les fichiers auto-générés, lockfiles et gros fixtures de données entièrement hors du contexte de Claude.

Le cadrage honnête : CLAUDE.md est un outil de levier, pas un projet de documentation. Les meilleurs fichiers CLAUDE.md en 2026 sont plus courts que les premiers exemples, plus opinionnants et impitoyablement focalisés sur ce qui change la sortie de Claude. Si une section n'améliore pas mesurablement ce que Claude écrit, elle vous coûte des tokens et de l'attention pour zéro gain. Traitez-le comme du code de production : revoyez-le, élaguez-le, vérifiez qu'il marche.

Créer votre premier CLAUDE.md

Démarrage rapide avec /init

Le moyen le plus rapide de créer un CLAUDE.md est la commande /init :

> /init

Claude Code va :

1. →Scanner la structure de votre projet
2. →Identifier les frameworks, langages et patterns
3. →Générer un fichier CLAUDE.md personnalisé
4. →Vous demander si vous souhaitez le personnaliser

Création manuelle

Créez un fichier à la racine de votre projet :

touch CLAUDE.md
# ou
mkdir -p .claude && touch .claude/CLAUDE.md

Commencez avec ce template :

# Projet : [Nom de votre projet]

## Aperçu
[Brève description de ce que fait ce projet]

## Stack technique
- [Langage/Framework 1]
- [Langage/Framework 2]
- [Base de données]
- [Autres outils]

## Structure du projet
[Répertoires clés et leurs objectifs]

## Conventions
[Standards et patterns de codage à suivre]

## Notes importantes
[Ce que Claude doit savoir ou éviter]

Bonnes pratiques de structure du CLAUDE.md

1. Aperçu du projet

Commencez par la vue d'ensemble pour que Claude comprenne le contexte :

# Projet : Plateforme E-Commerce

## Aperçu
Une plateforme e-commerce B2B pour les distributeurs en gros. Gère la 
gestion des stocks, le traitement des commandes et les vitrines multi-locataires.

## Contexte métier
- Utilisateurs principaux : Responsables d'entrepôt et équipes d'approvisionnement
- Pic d'utilisation : Lundi-Vendredi, heures ouvrables
- Flux critiques : Passage de commande, synchronisation des stocks, génération de factures

2. Stack technique

Soyez précis sur les versions et configurations :

## Stack technique

### Frontend
- Next.js 14 avec App Router
- TypeScript 5.3 (mode strict)
- Tailwind CSS 3.4
- React Query pour le data fetching

### Backend
- Node.js 20 LTS
- Express.js avec TypeScript
- Prisma ORM 5.x
- PostgreSQL 15

### Infrastructure
- Vercel (frontend)
- Railway (backend + base de données)
- Redis pour le cache
- S3 pour le stockage de fichiers

3. Structure du projet

Décrivez la structure de vos répertoires :

## Structure du projet

- **apps/web/** - Frontend Next.js
- **apps/api/** - Backend Express
- **packages/ui/** - Bibliothèque de composants partagée
- **packages/config/** - Configuration partagée
- **packages/types/** - Types TypeScript partagés
- **prisma/schema.prisma** - Schéma de base de données
- **prisma/migrations/** - Fichiers de migration
- **scripts/** - Scripts de développement et déploiement

### Répertoires clés
- `apps/web/app/`: Pages et layouts Next.js App Router
- `apps/api/src/routes/`: Gestionnaires d'endpoints API
- `packages/ui/src/components/`: Composants UI réutilisables

4. Conventions de codage

Définissez les standards que Claude doit suivre :

## Conventions de codage

### TypeScript
- Utiliser le mode strict, pas de `any` sans justification
- Préférer les interfaces aux types pour les formes d'objets
- Utiliser Zod pour la validation à l'exécution

### Composants React
- Composants fonctionnels uniquement
- Hooks personnalisés dans le répertoire `hooks/`
- Utiliser les exports nommés, pas les exports par défaut

### Nommage
- Composants : PascalCase (ex : `UserProfile.tsx`)
- Utilitaires : camelCase (ex : `formatDate.ts`)
- Constantes : UPPER_SNAKE_CASE
- Tables de base de données : snake_case

### Organisation des fichiers
- Un composant par fichier
- Co-localiser les tests : `Component.tsx` → `Component.test.tsx`
- Types partagés dans le répertoire `types/`

### Git
- Commits conventionnels : `feat:`, `fix:`, `docs:`, `refactor:`
- Nommage des branches : `feature/`, `fix/`, `chore/`
- Squash merge vers main

5. Notes importantes et restrictions

Dites à Claude ce qu'il faut éviter :

## Notes importantes

### Zones interdites
- **NE PAS** modifier `/apps/api/src/billing/` - géré par l'équipe paiement externe
- **NE PAS** changer le schéma de base de données sans créer une migration
- **NE PAS** commiter les fichiers `.env` ou exposer les clés API

### Considérations critiques
- Tous les endpoints API doivent valider les entrées avec des schémas Zod
- Les requêtes de base de données doivent utiliser des transactions Prisma pour les mises à jour multi-tables
- Les routes frontend nécessitent un middleware d'authentification

### Problèmes connus
- Les routes legacy `/api/v1/` sont dépréciées mais encore utilisées par l'application mobile
- La connexion Redis échoue parfois en dev - redémarrer avec `npm run redis:restart`

### Dépendances externes
- Les signatures webhook Stripe doivent correspondre à `STRIPE_WEBHOOK_SECRET`
- Les templates SendGrid sont gérés dans leur dashboard, pas dans le code

6. Tâches courantes

Fournissez des consignes pour les opérations fréquentes :

## Tâches courantes

### Ajouter un nouvel endpoint API
1. Créer le gestionnaire de route dans `apps/api/src/routes/`
2. Ajouter le schéma Zod dans `apps/api/src/schemas/`
3. Enregistrer la route dans `apps/api/src/index.ts`
4. Ajouter les tests dans `apps/api/src/routes/__tests__/`

### Créer une migration de base de données
```bash
cd apps/api
npx prisma migrate dev --name description_du_changement

Lancer les tests

npm run test          # Tous les tests
npm run test:unit     # Tests unitaires uniquement
npm run test:e2e      # Tests de bout en bout

Développement local

npm run dev           # Démarrer tous les services
npm run dev:web       # Frontend uniquement
npm run dev:api       # Backend uniquement

---

## Patterns avancés du CLAUDE.md

### Contenu dynamique avec des commandes

Incluez des données en direct de votre projet :

```markdown
## Dépendances actuelles

Dépendances principales depuis package.json :
- Voir `package.json` pour la liste complète

## Modifications récentes

Vérifiez les commits récents avec :
```bash
git log --oneline -10

### Instructions spécifiques à l'environnement

```markdown
## Notes d'environnement

### Développement
- Utiliser `.env.local` pour les surcharges locales
- Base de données : PostgreSQL local sur le port 5432
- L'API tourne sur http://localhost:3001

### Staging
- Base de données : Instance Railway staging
- Nécessite un VPN pour l'accès

### Production
- Ne jamais exécuter les migrations directement
- Les modifications nécessitent une revue de PR par 2 membres de l'équipe

Rôles et responsabilités de l'équipe

## Responsabilités de l'équipe

| Domaine | Responsable | Notes |
|---------|-------------|-------|
| Frontend | @frontend-team | Tout `/apps/web/` |
| API | @backend-team | Tout `/apps/api/` |
| Base de données | @data-team | Les modifications de schéma nécessitent une revue |
| Paiements | @billing-team | Externe - ne pas modifier |
| DevOps | @platform-team | CI/CD et infrastructure |

Intégration avec les commandes personnalisées

Référencez vos commandes slash personnalisées :

## Commandes personnalisées

Nous avons des commandes slash personnalisées pour les workflows courants :

- `/deploy-staging` - Déployer la branche actuelle sur staging
- `/db-migrate` - Exécuter les migrations de base de données en attente
- `/generate-types` - Régénérer les types TypeScript depuis Prisma

Voir `.claude/commands/` pour les détails d'implémentation.

Pour en savoir plus sur les commandes personnalisées, voir Commandes Slash personnalisées dans Claude Code : créez les vôtres.

Emplacements et priorité de CLAUDE.md

Claude Code lit plusieurs fichiers CLAUDE.md dans un ordre spécifique :

CLAUDE.md au niveau utilisateur

Créez ~/.claude/CLAUDE.md pour les préférences personnelles :

# Préférences personnelles

## Style de codage
- Je préfère les annotations de type explicites
- Utiliser des noms de variables descriptifs
- Ajouter des commentaires pour la logique complexe

## Communication
- Explique ton raisonnement brièvement
- Montre les diffs pour les modifications de fichiers
- Demande avant de faire de gros refactorings

## Outils que j'utilise
- VS Code avec raccourcis Vim
- iTerm2 sur macOS
- Préfère npm à yarn

Pattern Monorepo

Pour les monorepos, utilisez plusieurs fichiers CLAUDE.md :

• →my-monorepo/CLAUDE.md - Racine : conventions partagées
• →apps/web/CLAUDE.md - Spécifique au frontend
• →apps/api/CLAUDE.md - Spécifique au backend
• →packages/ui/CLAUDE.md - Spécifique à la bibliothèque de composants

CLAUDE.md racine :

# Monorepo : Ma Plateforme

## Conventions partagées
- Tous les packages utilisent TypeScript en mode strict
- Types partagés dans `/packages/types/`
- Utiliser les dépendances workspace : `"@myorg/ui": "workspace:*"`

CLAUDE.md spécifique à l'application :

# Application Frontend

Hérite du CLAUDE.md racine.

## Conventions supplémentaires
- Utiliser les patterns Next.js App Router
- Composants serveur par défaut
- Composants client marqués avec 'use client'

Gérer CLAUDE.md avec /memory

La commande /memory fournit une interface pour éditer les fichiers mémoire :

> /memory

Cela ouvre un menu interactif pour :

• →Voir le contenu actuel du CLAUDE.md
• →Éditer le CLAUDE.md du projet
• →Éditer le CLAUDE.md utilisateur
• →Voir ce que Claude retient

Mettre à jour la mémoire en cours de session

Vous pouvez également ajouter à la mémoire de Claude pendant une conversation :

> Retiens que nous migrons de REST vers GraphQL. 
> Les nouveaux endpoints doivent utiliser GraphQL, mais maintenir la compatibilité REST.

Claude proposera d'ajouter ceci à votre CLAUDE.md.

Exemples de CLAUDE.md réels

Exemple 1 : SaaS React + TypeScript

# Projet : TaskFlow - SaaS de gestion de projet

## Aperçu
Une application de gestion de projet type Trello avec collaboration en temps réel.

## Stack technique
- Next.js 14 (App Router)
- TypeScript (strict)
- Prisma + PostgreSQL
- Socket.io pour le temps réel
- Tailwind + Radix UI

## Architecture
- Structure de dossiers par fonctionnalité : `/features/[feature]/`
- Chaque fonctionnalité a : components/, hooks/, api/, types/
- UI partagée dans `/components/ui/` (basée sur Radix)

## Conventions
- React Query pour l'état serveur
- Zustand pour l'état client
- Zod pour la validation (partagée entre client/serveur)
- Pas de type `any` - utiliser `unknown` et affiner

## Règles critiques
1. Toutes les écritures en base doivent être dans des transactions
2. Les événements temps réel passent par `/lib/realtime/emit.ts`
3. Ne jamais stocker de données sensibles dans l'état client
4. Toutes les routes API nécessitent un middleware d'authentification

Exemple 2 : Backend Python FastAPI

# Projet : API DataPipeline

## Aperçu
API REST pour la gestion de pipeline de traitement de données.

## Stack technique
- Python 3.11
- FastAPI + Pydantic v2
- SQLAlchemy 2.0 + PostgreSQL
- Celery + Redis pour les tâches asynchrones
- Docker Compose pour le développement local

## Structure du projet

- **src/api/** - Routes FastAPI
- **src/models/** - Modèles SQLAlchemy
- **src/schemas/** - Schémas Pydantic
- **src/services/** - Logique métier
- **src/tasks/** - Tâches Celery
- **src/utils/** - Utilitaires

## Conventions
- Annotations de type requises partout
- Docstrings pour les fonctions publiques (style Google)
- Async/await pour les opérations I/O
- Injection de dépendances via FastAPI Depends

## Commandes
- `make dev` - Démarrer le serveur de développement
- `make test` - Exécuter pytest
- `make lint` - Exécuter ruff + mypy

## Important
- Les tâches longues DOIVENT utiliser Celery, pas des endpoints synchrones
- Tous les endpoints nécessitent la documentation OpenAPI
- Migrations de base de données via Alembic uniquement

Exemple 3 : Application mobile (React Native)

# Projet : FitTrack Mobile

## Aperçu
Application de suivi fitness avec journalisation des entraînements et analyse de la progression.

## Stack technique
- React Native 0.73 + Expo SDK 50
- TypeScript
- React Query + Zustand
- React Navigation 6

## Conventions
- Composants fonctionnels avec hooks
- Styles : StyleSheet.create, pas inline
- Icônes : @expo/vector-icons uniquement
- Animations : Reanimated 3

## Notes de plateforme
- Tester sur iOS et Android avant la PR
- Utiliser Platform.select pour le code spécifique à la plateforme
- Gestion des zones sûres via react-native-safe-area-context

## Zones interdites
- Ne pas modifier les modules natifs sans l'approbation du tech lead
- Ne pas ajouter de dépendances natives sans vérifier la compatibilité Expo
- Les notifications push sont gérées par un service externe

## Tests
- Jest pour les tests unitaires
- Detox pour les E2E (exécution sur CI uniquement)

Résolution des problèmes CLAUDE.md

Claude ne suit pas les instructions

1. →Vérifiez l'emplacement du fichier : Doit être CLAUDE.md ou .claude/CLAUDE.md à la racine du projet
2. →Vérifiez la syntaxe : Assurez-vous que le formatage Markdown est valide
3. →Soyez précis : Des instructions vagues donnent des résultats vagues
4. →Redémarrez la session : Claude charge CLAUDE.md au démarrage de la session

Instructions en conflit

Si le CLAUDE.md utilisateur et celui du projet sont en conflit, le projet l'emporte. Soyez explicite :

## Remplacement des préférences utilisateur
Pour ce projet, ignorer les préférences personnelles concernant :
- Nous utilisons Yarn, pas npm
- Nous utilisons des tabulations, pas des espaces

CLAUDE.md devient trop long

Restez concentré. Déplacez la documentation détaillée ailleurs :

## Documentation
- Documentation API : `/docs/api/`
- Architecture : `/docs/architecture.md`
- Intégration : `/docs/onboarding.md`

Claude peut lire ces fichiers quand nécessaire.

En bref

1. →

   CLAUDE.md est la mémoire du projet : Il persiste le contexte entre les sessions pour que Claude comprenne votre projet en profondeur.

2. →

   Utilisez /init pour commencer : Laissez Claude générer un CLAUDE.md initial, puis personnalisez-le.

3. →

   Soyez précis et structuré : Des sections claires pour l'aperçu, la stack technique, les conventions et les restrictions.

4. →

   Superposez vos configurations : Niveau utilisateur pour les préférences personnelles, niveau projet pour les standards de l'équipe.

5. →

   Maintenez-le à jour : Mettez à jour CLAUDE.md à mesure que votre projet évolue, c'est de la documentation vivante.

Prêt à obtenir des sorties structurées de l'IA ?

Maintenant que Claude comprend votre projet grâce à CLAUDE.md, il est temps d'apprendre comment obtenir des réponses cohérentes et structurées.

Dans notre Module 2, Sorties structurées, vous apprendrez :

• →Comment obtenir du JSON, des tableaux et des réponses formatées de manière fiable
• →Les techniques pour un formatage de sortie cohérent
• →La définition et la validation de schémas
• →Des exemples concrets de prompting structuré

→ Explorer le Module 2 : Sorties structurées