02 - CLAUDE.md : donner un cerveau persistant a ton IA
Ce que tu vas apprendre
- Ce qu'est CLAUDE.md et pourquoi c'est le fichier le plus important de ton setup
- Les trois scopes : projet, utilisateur, organisation
- Quoi mettre dedans (et quoi ne pas y mettre)
- Un exemple réel avec des regles RTK
Prerequisites
Le problème sans CLAUDE.md
Tu ouvres Claude Code sur ton projet. Tu lui demandes de créer un nouveau composant React. Il te généré un composant avec des classes CSS inline. Sauf que ton projet utilise Tailwind. Tu corriges. Session suivante, meme problème. Il ne se souvient de rien.
Sans CLAUDE.md, chaque session repart de zero. Claude decouvre ton projet a chaque fois. Il ne sait pas que tu utilises Bun au lieu de npm, que tes routes API sont dans api/src/routes/, que ton blog est généré depuis du Markdown dans sites/blog/content/.
CLAUDE.md corrige ca. C'est un fichier d'instructions en Markdown charge automatiquement a chaque session. Une mémoire permanente.
Les trois scopes
CLAUDE.md existe a trois niveaux :
Projet (.claude/CLAUDE.md a la racine du repo) : les regles spécifiques a ce projet. Commande de build, stack technique, conventions de nommage. C'est le plus utilise. Tu le commits dans git, toute l'équipe en beneficie.
Utilisateur (~/.claude/CLAUDE.md) : tes préférences personnelles, communes a tous tes projets. Par exemple, la configuration RTK que j'utilise partout (on verra RTK dans un article dédié).
Organisation : gere par ton entreprise, applique a tous les projets de l'org. Utile pour des regles de sécurité ou des conventions d'équipe transverses.
Les trois scopes se cumulent. Le projet hérité de l'utilisateur, qui hérité de l'org. En cas de conflit, le plus spécifique gagne.
Quoi mettre dans CLAUDE.md
Sois concret. Chaque ligne doit etre une instruction actionnable. Voici ce qui marche :
markdown# Projet paltemps.fr
## Stack
- Runtime : Bun
- API : Elysia (TypeScript)
- Frontend : Vanilla HTML/CSS/JS (pas de framework)
- Blog : Markdown + static generation (build.ts)
- Reverse proxy : Caddy (auto-SSL)
- Mail : docker-mailserver
- Deploy : GitLab CI + Docker Compose sur VPS OVH
## Commandes
- Dev : bun run --watch api/src/index.ts
- Build : bash build.sh
- Deploy : git push (GitLab CI auto-deploy)
## RTK (Rust Token Killer)
Toujours prefixer les commandes avec `rtk` :
- rtk git status, rtk git diff, rtk git log
- rtk cargo build, rtk vitest run
## Conventions
- Noms de fichiers : kebab-case
- API routes : un fichier par domaine dans api/src/routes/
- Sites : un dossier par sous-domaine dans sites/
- Pas de console.log en prod
## Ce qu'il ne faut PAS faire
- Ne modifie JAMAIS les fichiers .env
- Ne touche pas aux fichiers dans mail/config/opendkim/
- Ne lance pas npm ou yarn (c'est Bun ici)
Tu vois le schema : c'est factuel, direct, sans ambiguite. Claude ne devine pas, il suit les instructions.
Le répertoire .claude/rules/
Pour les regles qui ne s'appliquent qu'a certains fichiers, utilise .claude/rules/. Chaque fichier dans ce répertoire peut cibler un chemin spécifique grace au frontmatter :
markdown---
path: "src/api/**"
---
Les fichiers dans src/api/ suivent le pattern controller/service/repository.
Chaque controller a un fichier .dto.ts pour les Data Transfer Objects.
Les validations se font dans les DTOs avec class-validator.
Ca évité de surcharger le CLAUDE.md principal avec des regles qui ne concernent que 10% du projet.
Un vrai exemple : la config RTK
Voici un extrait du ~/.claude/CLAUDE.md que j'utilise sur tous mes projets. C'est la configuration RTK (Rust Token Killer), un outil qu'on détaillé dans l'article 06 :
markdown# RTK - Golden Rule
Toujours prefixer les commandes avec `rtk`.
Meme dans les chaines avec && :
Correct : rtk git add . && rtk git commit -m "msg"
Incorrect : git add . && git commit -m "msg"
Cette instruction fait que Claude utilise systématiquement RTK pour toutes ses commandes. Le résultat : 60 a 90% de tokens economises sur chaque commande, des sessions plus longues, des coûts reduits. Sept lignes dans un fichier. Un impact direct sur chaque session.
Les erreurs courantes
Trop long. J'ai vu des CLAUDE.md de 500 lignes. Claude les lit, mais ca dilue les informations. Garde le fichier sous 200 lignes. Si tu depasses, deplace les regles spécifiques dans .claude/rules/.
Trop vague. "Ecris du bon code" ne sert a rien. "Utilise des noms de variables en anglais, en camelCase, avec un prefixe is/has pour les booleens" est utile. La precision fait toute la différence.
Pas mis à jour. Un CLAUDE.md qui référencé une stack ou des commandes obsolètes fait plus de mal que de bien. Claude va suivre des instructions fausses avec confiance. Mets-le à jour quand tu changes de stack ou de conventions.
Des opinions au lieu de regles. "React est mieux que Vue" ne change rien au comportement de Claude. "Ce projet utilise React 19, ne propose jamais de code Vue/Angular" change tout.
La mémoire automatique
Claude Code a aussi un système de mémoire automatique. Quand tu lui dis "souviens-toi que les tests doivent toujours utiliser des factories et jamais des fixtures", il ajoute cette instruction dans le CLAUDE.md du projet. Tu peux vérifier ce qu'il a retenu en ouvrant le fichier.
C'est pratique pour les ajouts ponctuels. Mais je préféré éditer le fichier moi-meme pour les regles structurantes. La mémoire automatique a tendance a accumuler des instructions en vrac sans organisation. Un CLAUDE.md écrit a la main, avec des sections claires, reste plus fiable.
Article précédent : 01 - Installer Claude Code
Article suivant : 03 - Les MCP servers : connecter Claude au monde extérieur