Maîtriser CLAUDE.md

La plupart des conseils sur CLAUDE.md ratent l'essentiel. Tu lis partout qu'il faut "introduire Claude à ton projet". Lister la stack technique. Ajouter les commandes clés. Esquisser l'arborescence. Certains guides poussent même à tenir le fichier sous 60 lignes.

Cette vision se trompe sur ce que le fichier fait vraiment.

Pense à CLAUDE.md comme un fichier de contrôle qui gouverne le comportement de Claude. Il définit comment le modèle tourne, comment une conversation est gérée, et comment le travail circule entre l'agent central et ses assistants. Les détails sur ta stack ont leur place ailleurs. Les skills, c'est cet ailleurs. Ils se chargent à la demande, apportent exactement ce qu'il faut, puis s'effacent quand c'est fait.

Deux Paradigmes : Introduction vs. Orchestration

L'Approche Inférieure : Introduction au Projet

La lecture classique, c'est que CLAUDE.md devrait "introduire Claude à ton projet". Tu réponds à trois questions pour le modèle : QUOI (la stack), POURQUOI (le projet existe), et COMMENT (le faire tourner). Certains guides poussent à tenir le tout sous 60 lignes.

Ça casse plusieurs choses quand tu procèdes ainsi :

Saturation des priorités : Tout ce qui est dans CLAUDE.md est traité à haute priorité dans la fenêtre de contexte. Le modèle considère tout le fichier comme faisant autorité. Bourre-le de règles et chaque ligne se bat pour cette même position dominante. Tes notes React entrent en collision avec tes conventions API pendant que tu travailles sur une migration de base de données. Quand tout est prioritaire, rien ne l'est vraiment.

Gaspillage de contexte : Un CLAUDE.md rempli de patterns React pour ton appli React se charge quand même à chaque session. Même celles où le boulot est un script de déploiement ou un changement de schéma.

Zéro contrôle comportemental : Lister la stack ne dit rien sur la façon dont Claude devrait aborder un problème. Rien sur la délégation. Rien sur le rythme d'un travail en plusieurs étapes.

Répétition entre projets : Chaque nouveau dépôt engendre un nouveau CLAUDE.md, et chaque nouveau CLAUDE.md dérive du précédent. L'IA finit par se comporter différemment d'un projet à l'autre.

Connaissances statiques : La doc de projet vieillit mal. Un pattern API écrit il y a six mois n'a peut-être plus rien à voir avec le code actuel.

L'introduction cadre Claude comme un prestataire briefé sur le boulot du matin. L'orchestration cadre Claude comme un système en marche qui a besoin de ses paramètres réglés.

L'Approche Supérieure : Couche d'Orchestration

CLAUDE.md devrait définir :

1. Workflows opérationnels - La séquence que Claude suit pour chaque requête
2. Stratégie de gestion du contexte - Comment conserver et allouer le contexte efficacement
3. Patterns de délégation - Quand utiliser des sous-agents vs. gérer directement
4. Standards de qualité - Pratiques de code, gestion d'erreurs, exigences de sécurité
5. Protocoles de coordination - Comment gérer le travail parallèle vs. séquentiel

Ta stack, tes patterns, tes conventions vivent dans des skills qui se chargent dynamiquement quand ils sont pertinents. Cette séparation t'apporte :

• Comportement IA cohérent sur tous les projets
• Utilisation efficace du contexte - les connaissances métier se chargent seulement quand nécessaire
• Expertise portable - les skills se transfèrent entre projets
• Connaissances maintenables - mets à jour un skill une fois, le bénéfice est partout

Structurer Ton CLAUDE.md

Section Principes Fondamentaux

Commence par les comportements fondamentaux que tu veux de ton IA. Ces comportements doivent s'appliquer universellement, quel que soit le projet ou la tâche.

## Core Principles
 
### Skills-First Workflow
 
**EVERY user request follows this sequence:**
 
Request → Load Skills → Gather Context → Execute
 
Skills contain critical workflows and protocols not in base context.
Loading them first prevents missing key instructions.
 
### Context Management Strategy
 
**Central AI should conserve context to extend pre-compaction capacity**:
 
- Delegate file explorations and low-lift tasks to sub-agents
- Reserve context for coordination, user communication, and strategic decisions
- For straightforward tasks with clear scope: skip heavy orchestration, execute directly
 
**Sub-agents should maximize context collection**:
 
- Sub-agent context windows are temporary
- After execution, unused capacity = wasted opportunity
- Instruct sub-agents to read all relevant files, load skills, and gather examples

Ce sont les comportements qui se déclenchent à chaque interaction. Pas des détails de projet qui peuvent ne pas être pertinents aujourd'hui.

Logique de Routing et de Délégation

Définis quand Claude doit gérer le travail directement vs. le déléguer à des spécialistes :

### Routing Decision
 
**Direct Execution**:
 
- Simple/bounded task with clear scope
- Single-component changes
- Quick fixes and trivial modifications
 
**Sub-Agent Delegation**:
 
- Complex/multi-phase implementations
- Tasks requiring specialized domain expertise
- Work that benefits from isolated context
 
**Lead Orchestrator**:
 
- Ambiguous requirements needing research
- Architectural decisions with wide impact
- Multi-day features requiring session management

Avec le routing écrit noir sur blanc, Claude prend de vraies décisions sur qui fait quoi. Plus question de tout gérer seul. Plus question de déléguer juste pour déléguer.

Protocoles Opérationnels

Définis comment Claude doit coordonner le travail, surtout quand le parallélisme est possible :

## Operational Protocols
 
### Agent Coordination
 
**Parallel** (REQUIRED when applicable):
 
- Multiple Task tool invocations in single message
- Independent tasks execute simultaneously
- Bash commands run in parallel
 
**Sequential** (ENFORCE for dependencies):
 
- Database → API → Frontend
- Research → Planning → Implementation
- Implementation → Testing → Security
 
### Quality Self-Checks
 
Before finalizing code, verify:
 
- All inputs have validation
- Authentication/authorization checks exist
- All external calls have error handling
- Import paths verified against existing codebase examples

Standards de Code et Pratiques

Inclure des principes de code universels qui doivent régir tout le travail :

## Coding Best Practices
 
**Priority Order** (when trade-offs arise):
Correctness > Maintainability > Performance > Brevity
 
### Task Complexity Assessment
 
Before starting, classify:
 
- **Trivial** (single file, obvious fix) → execute directly
- **Moderate** (2-5 files, clear scope) → brief planning then execute
- **Complex** (architectural impact, ambiguous requirements) → full research first
 
Match effort to complexity. Don't over-engineer trivial tasks or under-plan complex ones.
 
### Integration Safety
 
Before modifying any feature:
 
- Identify all downstream consumers using codebase search
- Validate changes against all consumers
- Test integration points to prevent breakage

Le Répertoire Rules : Instructions Modulaires

À partir de Claude Code v2.0.64, tu as une autre option pour organiser tes instructions : le répertoire .claude/rules/. Les rules règlent le problème de saturation en te permettant de répartir les instructions haute priorité dans des fichiers à portée étroite.

Insight clé d'Anthropic : Un fichier rules ride à la même haute priorité qu'un CLAUDE.md. Ce qui change, c'est que tu peux viser cette priorité avec un pattern de chemin. La règle ne s'active que lorsque les fichiers correspondants sont en portée.

Quand les Rules Battent CLAUDE.md

Les rules deviennent rentables dès que tes instructions ont des frontières de domaine :

.claude/rules/
├── api-guidelines.md     # Only relevant for API work
├── react-patterns.md     # Only relevant for frontend
├── testing-rules.md      # Only relevant for test files
└── security-rules.md     # Only relevant for auth/payment code

Chaque fichier vit en mémoire projet. La différence, c'est que tu peux épingler une règle à un pattern de fichier :

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes

Cette règle ne se déclenche que quand Claude touche un fichier API. Côté frontend, tes conventions API restent silencieuses.

La Hiérarchie de Priorité des Instructions

Visualise-la comme des couches. Chaque couche associe un niveau de priorité à une règle de chargement :

CLAUDE.md contient le comportement universel que tu veux à haute priorité constante. Rules contient les éléments spécifiques au domaine, et ils ont cette priorité uniquement lorsque les bons fichiers sont ouverts. Skills contient l'expertise portable à priorité moyenne, chargée à la demande.

Tu veux la version complète, avec le ciblage par chemin et les tactiques de migration ? Lis le guide du répertoire Rules.

Charger CLAUDE.md depuis des Répertoires Supplémentaires

Depuis Claude Code v2.1.20, Claude peut charger des fichiers CLAUDE.md depuis des répertoires extérieurs à ton projet actif. Utile pour les monorepos, les conventions d'équipe partagées, et les configurations multi-projets.

Comment ça fonctionne :

# Enable the feature and specify additional directories
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-standards
 
# Multiple directories work too
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ../team-rules

Avec le flag activé, Claude charge ces fichiers depuis chaque répertoire supplémentaire :

• Les fichiers CLAUDE.md
• Les fichiers .claude/CLAUDE.md
• Les fichiers .claude/rules/*.md

Pourquoi c'est mieux que de pointer Claude verbalement vers un fichier :

Via --add-dir, les fichiers CLAUDE.md externes deviennent une vraie mémoire système plutôt que du remplissage de conversation. Ils se chargent seuls, survivent aux redémarrages de session, et s'inscrivent dans la hiérarchie de priorité.

Cas d'usage pratiques :

Monorepo avec standards partagés :

company/
├── shared-standards/
│   └── CLAUDE.md          # Company coding guidelines
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web-specific rules
│   └── api/
│       └── CLAUDE.md      # API-specific rules

Depuis le répertoire web/ :

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../../shared-standards

Cohérence entre projets : Mets tes standards de développement personnels dans un dossier central et tire-les dans n'importe quel projet. Zéro fichier copié.

Onboarding d'équipe : Les nouveaux coéquipiers pointent vers un répertoire partagé de conventions d'équipe. Ça supprime le problème "chaque projet a un CLAUDE.md légèrement différent".

Hiérarchie de priorité mise à jour :

Note : La fonctionnalité ne s'active que lorsque CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 est défini. Seul, le flag --add-dir accorde juste l'accès aux fichiers de ces répertoires. Il ne charge pas les fichiers CLAUDE.md qui s'y trouvent.

Syntaxe @import : Une Alternative Plus Légère

--add-dir te donne un répertoire externe entier. Pour importer un fichier à la fois, il y a une option plus légère. Les fichiers CLAUDE.md supportent la syntaxe @chemin/vers/import pour une mémoire composable :

See @README for project overview and @package.json for available npm commands.
 
# Standards
 
- coding guidelines @docs/coding-standards.md
- git workflow @docs/git-instructions.md

Les chemins relatifs et absolus fonctionnent tous les deux. Un chemin relatif se résout depuis le fichier qui fait l'import, pas depuis ton répertoire de travail.

Différence avec --add-dir :

Première approbation : La première fois que Claude Code rencontre des imports dans un projet, une boîte de dialogue d'approbation apparaît listant chaque fichier. C'est un appel unique par projet. Refuse-le et la boîte ne revient plus. Ces imports restent désactivés.

Imports récursifs : Un fichier importé peut importer d'autres fichiers, avec une profondeur maximale de 5 niveaux. C'est comme ça qu'on construit des ensembles d'instructions en couches :

# CLAUDE.md imports standards.md
 
@.claude/standards.md
 
# standards.md imports sub-files
 
@.claude/standards/api.md
@.claude/standards/testing.md

Les imports sont ignorés à l'intérieur des spans de code inline et des blocs de code délimités. Un exemple de code qui mentionne @chemin ne déclenchera pas accidentellement un chargement.

CLAUDE.local.md : Préférences Personnelles de Projet

Pour les préférences que tu ne veux pas dans l'arbre partagé de l'équipe, utilise CLAUDE.local.md. Le fichier est automatiquement ajouté au .gitignore et se charge juste à côté de CLAUDE.md avec la même priorité.

Bons exemples :

• Tes URLs de serveur de dev local et endpoints sandbox
• Tes préférences de données de test personnelles
• Les conventions de nommage de branches que tu préfères
• Les configurations d'éditeur et d'outils spécifiques à ta machine

Astuce git worktree : CLAUDE.local.md ne vit que dans un seul worktree. Importe depuis ton répertoire home et les mêmes instructions personnelles t'accompagnent dans chaque worktree que tu crées :

# CLAUDE.local.md
 
@~/.claude/my-project-instructions.md

Voir la Mémoire Chargée avec /memory

Lance /memory pour lister les fichiers actuellement dans le contexte de Claude, ou pour ouvrir n'importe quel fichier mémoire chargé dans ton éditeur. Fais-y appel quand une instruction semble manquer dans le comportement du modèle. Fais-y appel encore quand tu veux vérifier qu'une chaîne d'imports et tes rules atterrissent correctement.

Skills : Où Vit la Connaissance Métier

Les skills sont l'autre moitié du tableau. CLAUDE.md définit comment Claude opère. Les skills fournissent ce que Claude sait sur un domaine spécifique.

L'Architecture des Skills

Anthropic formule la distinction directement : "Les projets disent 'voilà ce que tu dois savoir.' Les skills disent 'voilà comment faire les choses.'"

Les skills utilisent la divulgation progressive :

1. Les métadonnées se chargent en premier (~100 tokens) - juste assez pour savoir quand le skill est pertinent
2. Les instructions complètes se chargent quand nécessaire (<5k tokens)
3. Les fichiers/scripts groupés se chargent seulement si requis

Grâce à cette conception, tu peux avoir des dizaines de skills sans exploser la fenêtre de contexte. Claude attrape exactement la pièce dont il a besoin, au moment où il en a besoin.

Ce Qui Appartient aux Skills

Patterns technologiques :

• Conventions de framework (patterns React, design d'API)
• Opérations de base de données et migrations
• Stratégies de test et utilitaires

Workflows métier :

• Intégrations de traitement des paiements
• Implémentations d'authentification
• Procédures de déploiement

Contexte spécifique au projet :

• Guides de navigation du codebase
• Documentation d'architecture
• Conventions d'équipe

Exemple : Séparer les Préoccupations

Au lieu de mettre ça dans CLAUDE.md :

## About This Project
 
FastAPI REST API for user authentication.
Uses SQLAlchemy for database operations.
 
## Commands
 
uvicorn app.main:app --reload
pytest tests/ -v

Crée un skill backend-api :

# Backend API Development Skill
 
## Framework
 
FastAPI with SQLAlchemy ORM, Pydantic validation.
 
## Development Commands
 
- `uvicorn app.main:app --reload` - Start dev server
- `pytest tests/ -v` - Run test suite
- `alembic upgrade head` - Apply migrations
 
## Patterns
 
[Detailed patterns, examples, conventions...]

Ton CLAUDE.md référence le système de skills :

### Key Skills
 
`backend-api`, `frontend-react`, `database-ops`, `deployment`
 
Load relevant skills before beginning domain-specific work.

Maintenant les détails backend n'apparaissent que pendant le travail backend. Le contexte reste libre pour le reste du boulot.

Le Débat sur le Nombre de Lignes

Un avis populaire dit que CLAUDE.md devrait tenir sous 60 lignes, parce que Claude "ignorerait" prétendument tout ce qui est plus long. Cette lecture du fonctionnement du contexte de Claude est fausse.

La réalité : Anthropic recommande que les fichiers de skills restent sous 500 lignes. Si un skill qui ne se charge qu'à la demande peut utiliser utilement 500 lignes, un CLAUDE.md toujours chargé peut certainement absorber 200 à 400 lignes de détails opérationnels.

La brièveté n'est pas le bon critère d'optimisation. La pertinence l'est. Soixante lignes de détails de projet qui ne s'appliquent pas à la tâche du jour mangent plus de contexte effectif que 300 lignes de règles opérationnelles universelles.

La zone idéale est 200-400 lignes de :

• Workflows opérationnels (toujours pertinents)
• Logique de routing (toujours pertinente)
• Standards de qualité (toujours pertinents)
• Protocoles de coordination (toujours pertinents)

Soixante lignes de spécificités de projet, dont la moitié est inutile pour chaque requête, c'est le pire des deux mondes.

Évolution du Framework

Intègre des instructions d'auto-amélioration dans le fichier :

### Framework Improvement
 
**Recognize patterns that warrant updates:**
 
**Update existing skill when**:
 
- A workaround was needed for something the skill should have covered
- New library version changes established patterns
- A better approach was discovered during implementation
 
**Create new skill when**:
 
- Same domain-specific context needed across 2+ sessions
- A payment processor, API, or tool integration was figured out
- Reusable patterns emerged that will apply to future projects
 
**Action**: Prompt user with: "This [pattern/workaround/integration] seems
reusable. Should I update [skill] or create a new skill to capture this?"

Le résultat, c'est un système auto-améliorant. Claude signale les moments qui valent la peine d'être transformés en nouveau skill ou en mise à jour d'un existant.

Pourquoi Cette Approche Fonctionne

Orchestration Multi-Agents

Le travail moderne avec Claude Code s'appuie de plus en plus sur des sous-agents : des instances spécialisées qui effectuent des tâches distinctes. Ton CLAUDE.md, c'est ce qui dit au modèle central comment faire tourner cette équipe.

Selon Anthropic, Opus 4.5 a été entraîné spécifiquement pour gérer une équipe de sous-agents. Mets cet entraînement au travail dans ton CLAUDE.md en précisant :

• Quand déléguer vs. gérer directement
• Comment construire les prompts des sous-agents
• Comment les résultats des sous-agents remontent dans la conversation principale

L'Économie du Contexte

Ta fenêtre de contexte a un plafond. Chaque octet de documentation de projet que tu verses dans CLAUDE.md est un octet qui ne peut pas être dépensé sur le vrai travail. L'orchestration, c'est comment tu dépenses bien ce budget :

• CLAUDE.md : Instructions opérationnelles (toujours nécessaires)
• Skills : Connaissances métier (chargées à la demande)
• Sous-agents : Contexte frais pour le travail spécialisé

Cohérence Entre Projets

Quand le fichier codifie le comportement plutôt que les détails de projet, l'IA se comporte de la même façon sur chaque boulot. Le routing, les standards de qualité, et les habitudes de coordination se transfèrent. Une appli React reçoit le même traitement qu'un outil CLI Python.

Référence Rapide

Request → Load Skills → Route Decision → Execute

Routing :

• Tâche simple/bornée → Exécution directe
• Complexe/multi-phase → Délégation à sous-agent ou gestion de session

CLAUDE.md Contient :

• Workflows opérationnels
• Stratégie de gestion du contexte
• Logique de routing et de délégation
• Standards de qualité
• Protocoles de coordination

Les Skills Contiennent :

• Spécificités de la stack technique
• Patterns de framework
• Conventions de projet
• Workflows métier

Prochaines Étapes

1. Audite ton CLAUDE.md actuel : C'est de la documentation de projet ou des instructions opérationnelles ?

2. Extrais la connaissance métier vers des skills : Déplace la stack, les patterns et les conventions hors de CLAUDE.md

3. Définis tes workflows opérationnels : Comment Claude devrait-il aborder chaque requête ?

4. Établis la logique de routing : Quand Claude devrait-il déléguer vs. gérer directement ?

5. Fixe les standards de qualité : Quelles pratiques doivent régir tout le travail ?

Souviens-toi : CLAUDE.md n'est pas un document que Claude lit. C'est le système sur lequel Claude tourne. Définis le comportement, pousse la connaissance vers les skills, et laisse le tout s'améliorer lui-même au fil du temps.

Tu veux le playbook complet par-dessus ces principes ? Lis nos 5 meilleures pratiques Claude Code qui distinguent les meilleurs développeurs.