CLAUDE.md : le fichier qui fait ou défait ton workflow IA

La plupart des devs qui essaient Claude Code abandonnent au bout d'une semaine. Pas parce que l'outil est mauvais. Parce qu'ils le font tourner sur une codebase qui ne lui donne rien avec quoi travailler.

Le fix, ce n'est pas un meilleur prompt. C'est un fichier appelé CLAUDE.md.

Ce que CLAUDE.md fait vraiment

Chaque session Claude Code démarre avec une context window fraîche. CLAUDE.md, c'est la façon dont tu transportes de la connaissance à travers les sessions. C'est la première chose que Claude lit quand une session commence.

Tout ce qui est dans ce fichier devient son context de travail : ce qu'est le projet, comment il est structuré, quelles conventions suivre, ce qu'il ne faut pas faire. Sans ça, l'agent devine. Certaines suppositions sont bonnes. La plupart sont génériques.

Tu n'as pas à l'écrire à la main from scratch. Lance /init dans Claude Code et il analyse ta codebase pour générer un fichier de départ : les commandes de build, la structure du projet, les conventions qu'il découvre lui-même. Affine à partir de là avec les choses qu'il ne trouverait pas seul.

La règle des 200 lignes

La guidance officielle d'Anthropic : garde chaque fichier CLAUDE.md sous les 200 lignes. Ce n'est pas arbitraire. Le fichier se load dans la context window au départ de chaque session. Un CLAUDE.md bloaté brûle des tokens sur des instructions que Claude ne suivra pas de façon cohérente parce qu'elles sont trop enfouies.

Si tes instructions grandissent au-delà de ça, split-les. Mets les instructions spécifiques à un package dans un CLAUDE.md à l'intérieur du répertoire de ce package. Claude load les fichiers des sous-répertoires à la demande quand il lit des fichiers dans ce dossier.

Tight et spécifique bat thorough à tous les coups.

Ce qui va dedans

Ce qui marche, après avoir itéré sur quelques projets :

Overview du projet en deux phrases. Pas un README. Ce que fait le projet, c'est quoi la tech stack. L'agent a besoin de context, pas de documentation.

Structure du repo. Quels dossiers comptent, quoi vit où. Si tu as un monorepo avec apps/, packages/, libs/, mappe-le. L'agent navigue les fichiers en permanence. Il devrait savoir où vivent les choses avant de commencer à les déplacer.

Conventions de nommage et de style. Si tes composants utilisent des props variant, dis-le. Si tu utilises du kebab-case pour les noms de fichiers, dis-le. L'agent peut suivre une règle si tu lui dis la règle.

Ce qu'il ne faut pas faire. C'est la section la plus sous-utilisée. « N'ajoute pas de nouvelles dépendances sans demander. » « Ne touche pas au module auth, il est en refactor actif. » « Les mock data vivent dans __fixtures__, pas inline. » Ces contraintes préviennent des erreurs coûteuses.

Les commandes que l'agent devrait connaître. Comment lancer les tests. Comment build. Comment checker les types. L'agent va essayer de valider son propre travail si tu lui donnes les bons outils.

Voilà à quoi ressemble le mien pour un projet React Native :

# CLAUDE.md
 
React Native app (Expo, TypeScript). Music practice app with real-time audio features.
 
## Structure
- `apps/mobile/`. main RN app
- `packages/ui/`. shared components
- `packages/core/`. business logic, no native code
 
## Conventions
- Components: PascalCase files, named exports
- Props: use `variant` not `type` for style variants
- Hooks live in `hooks/`, not colocated with components unless specific to one screen
 
## What to avoid
- No new dependencies without checking first
- Don't modify `packages/core/audio/`. in active refactor
- Don't add console.logs to production code paths
 
## Useful commands
- `pnpm test`. runs unit tests
- `pnpm typecheck`. tsc --noEmit
- `pnpm lint`. eslint

Pas de philosophie. Pas de mission statement. Juste ce dont l'agent a besoin pour opérer sans faire d'erreurs coûteuses.

La fondation, pas le plafond

CLAUDE.md change le mode d'échec. Sans lui, tu es en mode correction en permanence. L'agent fait des choix plausibles-mais-faux, tu les attrapes, tu les expliques, tu redémarres. Avec lui, les erreurs qui arrivent sont des erreurs intéressantes : erreurs de logique, edge cases. Pas « mauvais nom de fichier » ou « ce n'est pas comme ça qu'on fait les props ».

Mais c'est le floor, pas le système.

Une fois que CLAUDE.md est solide, il y a toute une couche d'outils que Claude Code supporte par-dessus : des slash commands custom pour l'orchestration de workflow, des subagents avec des contexts isolés pour les tasks spécialisées, des skills (des fichiers markdown qui se loadent à la demande), des hooks qui tournent sur des events spécifiques en dehors de la boucle agentic, et des MCPs pour les intégrations externes live.

CLAUDE.md est le prérequis. Tout le reste construit à partir de là.

Commence simple

Un CLAUDE.md d'une page qui couvre la structure, les conventions, et deux ou trois contraintes explicites surperformera largement l'absence de CLAUDE.md. Tu n'as pas besoin de la version parfaite au jour un.

Écris ce que tu sais aujourd'hui. Update-le quand quelque chose casse.

Le fichier qui change la façon dont ton agent travaille n'est pas complexe. Il doit juste exister.