ServicesÀ proposNotesContact Me contacter →
EN FR
Note

CLAUDE.md comme Mémoire de Projet

Comment CLAUDE.md donne à Claude Code un contexte de projet persistant — ce qu'il faut inclure, ce qu'il faut omettre, et pourquoi les ajouts réactifs sont préférables à la documentation proactive

Planté
claude codeaiautomation

CLAUDE.md est un fichier Markdown ordinaire à la racine du projet que Claude Code lit automatiquement au début de chaque conversation. Il fournit un contexte de projet persistant — décisions architecturales, conventions de codage et connaissances contextuelles — sans avoir à les répéter dans chaque prompt.

Comment Claude Code Trouve CLAUDE.md

Claude lit les fichiers CLAUDE.md depuis plusieurs emplacements, et ils s’accumulent :

  • Global : ~/.claude/CLAUDE.md — instructions qui s’appliquent à tous vos projets (préférences personnelles, standards de formatage, etc.)
  • Racine du projet : CLAUDE.md — conventions d’équipe partagées, commitées dans git
  • Override personnel : CLAUDE.local.md — ignoré par git, pour les préférences individuelles qui ne devraient pas affecter les coéquipiers
  • Répertoires enfants : les fichiers CLAUDE.md dans les sous-répertoires se chargent à la demande quand Claude travaille dans cette partie du monorepo

Pour un projet dbt, le fichier à la racine du projet est là où l’essentiel de la valeur réside. C’est ce que toute votre équipe partage.

Le Budget d’Instructions

Voici la contrainte que la plupart des gens manquent : les LLMs frontier peuvent suivre de manière fiable environ 150 à 200 instructions à la fois. Le prompt système de Claude Code en contient déjà environ 50, ce qui laisse une capacité limitée pour vos instructions personnalisées. Remplir CLAUDE.md de toutes les commandes, conventions et cas limites possibles ne rend pas Claude plus intelligent — cela le rend moins bon pour suivre n’importe quelle instruction individuelle.

Cela signifie que CLAUDE.md doit être curé, pas exhaustif. Incluez ce qui est universellement applicable à chaque conversation. Référencez des fichiers séparés pour la documentation détaillée plutôt que de l’intégrer inline. Utilisez des pointeurs plutôt que de copier des extraits de code, parce que les extraits deviennent rapidement obsolètes et gaspillent le budget d’instructions sur du contenu que Claude pourrait découvrir en lisant le fichier réel.

Ce Qui Appartient à CLAUDE.md

Pour un projet dbt/BigQuery, les entrées efficaces de CLAUDE.md couvrent typiquement :

  • Conventions de nommage : Préfixes des modèles (base__, int__, mrt__), le séparateur double-underscore, les noms d’entités au singulier. Sans cela, Claude utilise par défaut les conventions de la communauté qui pourraient ne pas correspondre aux vôtres — stg_ au lieu de base__, par exemple.
  • Structure du projet : Où vivent les modèles, comment les dossiers sont organisés, quel schéma correspond à quelle couche. Voir Structure et nommage des projets dbt pour les conventions qui méritent d’être encodées.
  • Exigences de test : Attentes minimales de test (unique + not_null sur chaque clé primaire), paquets de test préférés, conventions de sévérité.
  • Style SQL : Patterns spécifiques au dialecte (quoting avec backticks BigQuery, SAFE_DIVIDE, formats PARSE_DATE), conventions de nommage des CTEs, préférences de style pour les jointures.
  • Ce qu’il NE FAUT PAS faire : Les interdictions explicites sont souvent plus précieuses que les instructions positives. « Ne jamais utiliser SELECT * dans les modèles. » « Ne jamais modifier les fichiers dans models/marts/prod/ sans confirmation. » « Ne jamais utiliser CURRENT_TIMESTAMP() sans gestion du fuseau horaire. »

Ce Qui N’Appartient Pas

  • Les connaissances SQL génériques que Claude connaît déjà. N’expliquez pas ce qu’est un LEFT JOIN.
  • Les exemples de code complets qui dupliquent des fichiers dans votre dépôt. Pointez vers le fichier à la place : « Voir macros/generate_schema_name.sql pour notre logique de nommage de schéma personnalisée. »
  • Les instructions pour les cas limites rares qui surviennent une fois par trimestre. Gérez-les en conversation quand ils se présentent.
  • Le contenu auto-généré par /init. La commande /init de Claude Code produit un CLAUDE.md en scannant votre projet, mais la sortie tend à être générique — des choses que Claude découvrirait de lui-même en lisant votre code. C’est au mieux un point de départ, pas un produit fini.

L’Approche Réactive

Les meilleurs fichiers CLAUDE.md sont construits de manière réactive, pas proactive. Commencez avec un fichier vide. Travaillez avec Claude Code pendant quelques sessions. Quand Claude se trompe répétitivement — utilise stg_ au lieu de base__, crée des modèles dans le mauvais répertoire, oublie d’ajouter des tests de clé primaire — ajoutez une instruction d’une ligne à CLAUDE.md qui adresse cette erreur spécifique.

Cette approche présente deux avantages. Premièrement, chaque instruction mérite sa place en résolvant un problème réel. Deuxièmement, vous évitez le piège des instructions spéculatives qui semblent utiles mais consomment le budget d’instructions sans prévenir des erreurs réelles.

Sur quelques semaines, un CLAUDE.md construit de cette façon converge vers les 20 à 30 instructions qui comptent vraiment pour votre projet. C’est une bien meilleure utilisation du budget d’instructions qu’un document de 200 lignes écrit le premier jour.

Un Exemple Pratique

Un CLAUDE.md mature pour un projet dbt/BigQuery pourrait ressembler à quelque chose comme :

# Project: analytics-warehouse


## Models
- Use `base__`, `int__`, `mrt__` prefixes (not stg/dim/fct)
- Double underscore separates prefix, source/domain, and entity
- Singular entity names: `customer` not `customers`
- All models in `models/{base,intermediate,marts}/`


## SQL
- BigQuery dialect: backtick-quote dataset references
- Always use SAFE_DIVIDE for division
- CTEs named descriptively, not `cte1`, `cte2`
- No SELECT * in any model


## Testing
- Every primary key: unique + not_null
- Every foreign key: relationships test
- Run dbt build --select <model>+ after changes


## Don't
- Never modify models/marts/prod/ without asking
- Never use CURRENT_TIMESTAMP without TIMESTAMP_TRUNC
- Never create ephemeral models

Remarquez la brièveté. Chaque ligne adresse une erreur spécifique et récurrente. Pas d’explications, pas d’exemples, pas de redondance. Claude le lit en quelques secondes et le porte tout au long de la conversation.

Relation avec les Hooks et les Commandes

CLAUDE.md fournit des conseils — Claude devrait les suivre, mais ce n’est pas appliqué de force. Pour les règles qui ne doivent jamais être enfreintes (comme bloquer les modifications sur les schémas de production), utilisez plutôt les hooks. Pour les workflows multi-étapes répétables (comme générer des tests ou de la documentation), utilisez les commandes slash Claude Code pour dbt. CLAUDE.md, les hooks et les commandes forment trois couches de configuration du projet : contexte, garde-fous et automatisation.