CLAUDE.md pour les projets dbt

Un CLAUDE.md pour un projet dbt se construit à partir de vraies erreurs plutôt qu’écrit à l’avance à partir de scénarios hypothétiques. Cette note couvre le template concret, les catégories qui méritent leur place et les anti-patterns qui diluent le fichier.

L’approche réactive

Commencez sans aucun CLAUDE.md. Utilisez Claude Code sur votre projet dbt pendant quelques sessions. Lorsqu’il fait une erreur — utilise stg_ au lieu de base__, crée un modèle dans le mauvais dossier, écrit un alias de colonne sans AS, oublie de mettre à jour schema.yml après avoir modifié un modèle — c’est le moment d’ajouter une ligne.

Cela compte pour deux raisons. Premièrement, chaque instruction gagne sa place en résolvant un vrai problème que vous avez rencontré. Deuxièmement, vous évitez de gaspiller le budget d’instructions sur des choses que Claude déterminerait de toute façon en lisant votre base de code. Claude peut découvrir votre structure de dossiers à partir de vos fichiers ; il ne peut pas découvrir la convention de nommage spécifique de votre équipe sans en être informé.

La touche # dans Claude Code fait surface la commande mémoire en milieu de conversation. Lorsque Claude fait une erreur, corrigez-la, puis appuyez immédiatement sur # et Claude vous demandera quel fichier CLAUDE.md mettre à jour. C’est le workflow réel : rencontrer un problème, le corriger, l’encoder pour qu’il ne se reproduise plus.

Ce qu’il faut inclure

Un CLAUDE.md dbt mature couvre quatre catégories. Pas plus.

Commandes avec contexte

Pas seulement les commandes, mais quand les utiliser. Claude les utilise pour vérifier son travail :

## Commands
- `dbt run --select -s model_name`: Build specific models only
- `dbt test --select model_name+`: Test model and everything downstream
- `dbt compile`: Validate SQL/Jinja before running (do this first)
- `dbt ls --select +model_name+`: Check upstream and downstream impact
- `sqlfluff lint models/`: Check style compliance

L’annotation à côté de chaque commande compte. “Do this first” avant dbt compile indique à Claude l’ordonnancement, pas seulement la commande.

Conventions de nommage importantes

C’est là que Claude fait le plus d’erreurs sans guidance. La convention de nommage avec double-underscore et les préfixes de couche sont la source d’erreurs la plus courante :

## Naming
- Base: `base__<source>__<entity>.sql` (double underscore, not single)
- Intermediate: `int_<entity>_<verb>.sql`
- Marts: `mrt__<domain>__<entity>.sql`
- Primary keys: `<object>__id` (customer__id, not id or customer_id)

Sans cela, Claude adopte les conventions de la communauté : stg_, dim_, fct_, underscores simples. Correct pour les projets dbt génériques. Faux pour le vôtre.

Particularités spécifiques à l’entrepôt

Des règles qui préviennent de vrais bugs plutôt que des préférences de style. Pour BigQuery (voir Spécificités BigQuery dans CLAUDE.md pour la section complète) :

## BigQuery
- Use GoogleSQL syntax (not legacy SQL)
- Single quotes for strings, `!=` for inequality
- Always filter on partition column in WHERE clauses
- For large tables, use incremental with insert_overwrite

Pour Snowflake, la clause USING défaillante dans les jointures est l’exemple canonique — Claude génèrera du SQL ANSI valide qui échoue sur Snowflake sans cette instruction explicite.

Séquence de workflow

Comment Claude devrait aborder les changements — vérifier l’impact en aval d’abord, mettre à jour les docs YAML, exécuter les tests avant de commiter :

## Workflow
1. Check impact: `dbt ls --select +model_name+`
2. Make changes in correct layer (base/intermediate/marts)
3. Update schema.yml with descriptions
4. Compile → run → test → lint

Cela façonne la façon dont Claude structure son travail, pas seulement le code qu’il écrit. La séquence compte : vérifier l’impact avant de faire des changements prévient l’erreur courante de modifier un modèle sans réaliser que cinq marts en dépendent.

Un template complet

Voici à quoi ressemble un CLAUDE.md mature après des semaines d’itération sur un projet dbt/BigQuery. Chaque ligne existe parce que Claude a fait une erreur spécifique :

# Analytics Engineering Context

dbt project on BigQuery. Run `dbt compile` before suggesting any model changes.

## Commands
- `dbt run --select -s model_name`: Build specific models only
- `dbt test --select model_name+`: Test model and everything downstream
- `dbt compile`: Validate SQL/Jinja before running (do this first)
- `sqlfluff lint models/`: Check style compliance

## Naming
- Base: `base__<source>__<entity>.sql` (double underscore)
- Intermediate: `int_<entity>_<verb>.sql`
- Marts: `mrt__`
- Primary keys: `<object>__id` (customer__id, not id)

## SQL patterns
- Trailing commas, 4-space indent
- Always use `AS` for aliases
- CTE imports at top: `WITH model_name AS (SELECT * FROM {{ ref('...') }})`

## Testing
- Primary keys need unique + not_null
- Add comments explaining why each test exists

## Workflow
1. Check impact: `dbt ls --select +model_name+`
2. Make changes in correct layer (base/intermediate/marts)
3. Update schema.yml with descriptions
4. Compile → run → test → lint

Le fichier fait environ 40 lignes. Les fichiers CLAUDE.md courts sont suivis plus constamment que les longs.

Ce qui n’appartient pas au fichier

L’erreur la plus courante est d’ajouter des instructions qui semblent utiles à l’avance mais qui diluent le fichier :

Guides de style SQL exhaustifs. SQLFluff gère le formatage de manière déterministe. Des instructions comme “use trailing commas” ou “4-space indent” entrent en compétition pour l’attention avec les instructions dont Claude a réellement besoin pour prendre des décisions non évidentes. Si votre projet exécute SQLFluff en CI, vous pouvez supprimer la plupart des instructions de style de CLAUDE.md entièrement. Laissez les hooks exécuter le formateur automatiquement après chaque modification.

Schémas de base de données complets. Trop de contexte, change trop souvent. Laissez Claude découvrir le schéma via des requêtes ou le manifeste dbt. Si vous utilisez le serveur MCP dbt, la découverte du manifeste est automatique.

Documentation dbt générique. Claude sait déjà comment fonctionnent ref() et source(). Comment écrire une macro Jinja. À quoi sert schema.yml. Inclure cela gaspille le budget d’instructions sur des connaissances que Claude a déjà.

Contenu auto-généré par /init. La commande /init produit un CLAUDE.md en scannant votre projet, mais la sortie est principalement générique — des choses que Claude découvrirait de lui-même en lisant votre code. Un fichier vide qui grandit d’une ligne à la fois vous sert mieux qu’un fichier généré plein d’informations que Claude connaît déjà.

Instructions spécifiques à une tâche. Si une instruction ne s’applique qu’à un type de travail que vous faites occasionnellement, gérez-la en conversation lorsque ce travail se présente. La mémoire persistante devrait être réservée aux choses qui sont universellement pertinentes, session après session.

Partage en équipe

Committez votre CLAUDE.md dans le contrôle de version. C’est le moyen le plus simple de donner à chaque membre de l’équipe le même comportement de base de Claude Code — les mêmes conventions de nommage, la même séquence de workflow, les mêmes garde-fous.

Pour les préférences personnelles qui ne devraient pas être partagées (préférences de formatage différentes, chemins de fichiers locaux, workflows personnels), utilisez ~/.claude/CLAUDE.md dans votre répertoire home. Ce fichier se charge pour tous vos projets mais ne touche jamais au dépôt.

Pour les remplacements personnels temporaires dans un projet partagé, CLAUDE.local.md à la racine du projet est ignoré par git par défaut. Il se charge aux côtés du CLAUDE.md commité mais reste hors du contrôle de version.

Où cela s’inscrit dans la configuration globale

CLAUDE.md gère les directives — Claude devrait les suivre, mais c’est probabiliste. Pour les règles qui ne doivent jamais être violées (bloquer les modifications des schémas de production, toujours exécuter SQLFluff après chaque modification), utilisez les hooks à la place. Pour les workflows multi-étapes répétables (générer des tests, documenter des modèles), utilisez les commandes slash Claude Code pour dbt.

Les trois couches se complètent : CLAUDE.md fournit le contexte et les conventions, les hooks appliquent des limites dures, les commandes slash automatisent les workflows. Une configuration Claude Code mature pour dbt utilise les trois.