Maîtrise de CLAUDE.md : guide complet d'ingénierie de

Pourquoi le contexte est important

Claude Code dispose d'une immense fenêtre de contexte de 200 000 tokens, mais l'utiliser judicieusement est crucial :

L'impact d'un bon contexte

Ce que CLAUDE.md apporte

1. →Mémoire persistante : Les connaissances du projet survivent entre les sessions
2. →Application du style : Patterns et conventions de code cohérents
3. →Garde-fous de sécurité : Prévention des opérations dangereuses
4. →Optimisation du workflow : Commandes et raccourcis pré-configurés

La réalité honnête sur CLAUDE.md, telle qu'elle remonte sur r/ClaudeAI et dans les repos open source qui en livrent un : 80 % de la valeur vient des 50 premières lignes, et 80 % des regrets viennent de tout ce qui suit la ligne 200. Les praticiens qui traitent CLAUDE.md comme un README — court, opiniâtre, maintenu — obtiennent des gains durables. Ceux qui en font un dépotoir de connaissances finissent par payer des tokens pour des informations que le modèle connaît déjà (« on utilise TypeScript », « on préfère les arrow functions ») tout en oubliant la seule ligne qui compte vraiment (« ne touche jamais à /apps/legacy, c'est autogénéré »).

Ce que la documentation officielle Claude Code suggère mais souligne rarement : CLAUDE.md est chargé à chaque session, donc chaque kilo-octet est une taxe récurrente. Les ingénieurs sur r/ExperiencedDevs ont documenté comment un CLAUDE.md trop volumineux dégrade subtilement la performance sur des tâches sans rapport — pas par hallucination, mais par ancrage. Le modèle se met à voir chaque problème à travers le prisme de vos conventions, y compris quand ces conventions sont hors sujet.

Ce sur quoi la communauté s'accorde : gardez CLAUDE.md sous 2 000 tokens, encodez des contraintes plutôt que des explications, préférez les règles négatives (« ne fais pas X ») aux positives (« fais toujours Y »), et renvoyez vers la doc détaillée via des chemins relatifs. Le modèle sait parfaitement suivre un lien vers docs/architecture.md quand la tâche l'exige — pas besoin de tout précharger.

Anatomie de CLAUDE.md

Un CLAUDE.md bien structuré comporte des sections distinctes, chacune servant un objectif précis :

# Projet : [NOM]

## Aperçu
[Description de haut niveau du projet]

## Stack technique
- Framework : [ex : Next.js 14]
- Langage : [ex : TypeScript 5.3]
- Base de données : [ex : PostgreSQL + Prisma]

## Style de code
[Conventions spécifiques à suivre]

## Architecture
[Structure des fichiers et patterns]

## Commandes
[Opérations courantes]

## Contraintes
[Ce qu'il ne faut PAS faire]

Éditeur interactif CLAUDE.md

Utilisez cet éditeur interactif pour construire votre fichier CLAUDE.md parfait. Choisissez un template, personnalisez-le et téléchargez le résultat :

Comprendre votre budget de contexte

Claude Code dispose d'une fenêtre de contexte de 200K tokens partagée entre plusieurs sources. Utilisez ce visualiseur pour comprendre comment le contexte est alloué :

Stratégie d'allocation du contexte

Signes que vous atteignez les limites du contexte

1. →Claude « oublie » des parties antérieures de la conversation
2. →Suggestions répétitives qui ignorent la discussion précédente
3. →Perte des conventions du projet en cours de session
4. →Temps de réponse plus lents

Stratégies d'atténuation

## Dans CLAUDE.md - Utilisez un format compact

### Commandes (une ligne)
dev: `npm run dev` | test: `npm test` | build: `npm run build`

### Patterns de fichiers (compact)
Composants: src/components/[Name]/index.tsx, [Name].module.css
Hooks: src/hooks/use[Name].ts
Services: src/services/[name].service.ts

Templates par framework

Next.js 14+ (App Router)

# Projet : [NOM]

## Stack
- Next.js 14 (App Router)
- TypeScript 5.3 (mode strict)
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL

## Patterns
- Composants serveur par défaut
- 'use client' uniquement si nécessaire
- Server Actions pour les mutations
- Route handlers pour les API externes

## Structure des fichiers
app/
├── (marketing)/     # Pages publiques
├── (dashboard)/     # Pages protégées
├── api/             # Route handlers
└── layout.tsx       # Layout racine

## Nommage
- Composants : PascalCase
- Fichiers : kebab-case
- Server Actions : verbe + Nom (createUser, updatePost)

## Jamais
- Data fetching côté client pour les chargements initiaux
- Prop drilling au-delà de 2 niveaux
- Styles inline (utiliser Tailwind)

Python FastAPI

# Projet : [NOM]

## Stack
- Python 3.11+
- FastAPI 0.100+
- SQLAlchemy 2.0 (async)
- Pydantic v2

## Patterns
- Async/await partout
- Injection de dépendances via Depends()
- Pattern Repository pour l'accès aux données
- Modèles Pydantic pour la validation

## Structure
src/
├── api/routes/      # Définitions des endpoints
├── core/            # Config, sécurité
├── models/          # Modèles SQLAlchemy
├── schemas/         # Schémas Pydantic
├── services/        # Logique métier
└── repositories/    # Accès aux données

## Style
- Annotations de type sur toutes les fonctions
- Docstrings (format Google)
- Longueur de ligne max : 88 (black)
- isort pour les imports

## Jamais
- SQL brut sans paramétrage
- I/O bloquant dans les fonctions async
- Capture d'exceptions génériques

React + TypeScript

# Projet : [NOM]

## Stack
- React 18
- TypeScript 5 (strict)
- Vite
- Zustand/Jotai pour l'état
- React Query pour l'état serveur

## Patterns
- Composants fonctionnels uniquement
- Hooks personnalisés pour l'extraction de logique
- Composants composés pour les UI complexes
- Render props quand nécessaire

## Nommage
- Composants : PascalCase.tsx
- Hooks : useCamelCase.ts
- Utils : camelCase.ts
- Types : PascalCase.types.ts

## Style
- Déstructurer les props dans la signature de fonction
- Préférer interface à type pour les objets
- Exporter les types aux côtés des composants
- Co-localiser les tests avec les composants

## Jamais
- Composants classes
- PropTypes (utiliser TypeScript)
- Fichiers index comme fichiers de composants
- Exports par défaut pour les composants

Bonnes pratiques

1. Gardez-le DRY

Ne répétez pas les informations disponibles dans votre base de code :

❌ Ne listez pas chaque endpoint API
✅ Référencez : "Voir src/api/routes/ pour les patterns d'endpoints"

❌ Ne dupliquez pas les scripts de package.json
✅ Utilisez : "Exécutez `npm run` pour voir les commandes disponibles"

2. Utilisez des exemples plutôt que des règles

❌ "Utilisez des noms de variables descriptifs"
✅ Exemples :
   - userAuthenticationToken (pas : token)
   - fetchUserProfile (pas : getData)
   - isEmailValid (pas : check)

3. Priorisez la sécurité

## Règles critiques
1. JAMAIS commiter les fichiers .env
2. JAMAIS exposer les clés API dans le code client
3. TOUJOURS valider les entrées utilisateur
4. TOUJOURS utiliser des requêtes paramétrées

4. Versionnez votre CLAUDE.md

Conservez-le dans git et mettez-le à jour à mesure que votre projet évolue :

# Bons messages de commit pour les modifications de CLAUDE.md
git commit -m "docs(claude): ajouter les nouveaux patterns API pour v2"
git commit -m "docs(claude): mettre à jour les conventions de tests"

5. Conventions d'équipe

Pour les projets d'équipe, établissez des patterns CLAUDE.md partagés :

## Standards de l'équipe
- Template de PR : .github/pull_request_template.md
- Labels d'issues : bug, feature, docs, refactor
- Nommage des branches : feature/ABC-123-description
- Format des commits : commits conventionnels

Testez vos connaissances

Prochaines étapes

Maintenant que vous comprenez CLAUDE.md et l'ingénierie de contexte :

1. →Créer des Skills personnalisés - Construire des capacités d'agent réutilisables
2. →Maîtriser les Hooks - Automatiser avec des hooks événementiels
3. →Explorer les serveurs MCP - Connecter plus de 50 services externes