Si vous utilisez Claude Code pour l’analytics engineering, vous avez probablement remarqué qu’il lui arrive de… deviner. Mauvaises conventions de nommage. Syntaxe SQL legacy sur BigQuery. Il oublie que votre équipe utilise des doubles underscores dans les noms de modèles.

La solution s’appelle CLAUDE.md, et une fois que j’ai compris comment ce fichier fonctionne vraiment, ça a changé ma façon d’utiliser Claude Code pour les projets dbt.

Voici tout ce que j’ai appris pour le faire fonctionner en analytics engineering.

Ce qu’est vraiment CLAUDE.md

Voyez-le comme une mémoire persistante pour Claude Code. À chaque nouvelle session, Claude lit automatiquement ce fichier et l’utilise comme contexte pour tout ce qu’il fait ensuite. Plus besoin de ré-expliquer vos conventions, votre structure de dossiers, ou cette particularité BigQuery qui piège tout le monde.

Le fichier se place à la racine de votre projet (ou dans un dossier .claude/), et Claude le découvre automatiquement. Vous pouvez aussi avoir un fichier personnel à ~/.claude/CLAUDE.md pour les préférences qui s’appliquent à tous vos projets.

Un point important : Claude Code charge ces fichiers de façon hiérarchique. Il commence par votre dossier home, parcourt les répertoires parents, et termine par votre répertoire de travail actuel. Dans un monorepo, vous pouvez donc avoir des conventions globales à la racine et des conventions spécifiques dans les sous-répertoires.

Le principe du « moins c’est plus »

C’est la leçon la plus importante que j’ai apprise : les fichiers CLAUDE.md courts fonctionnent mieux.

D’après mon expérience, Claude suit correctement environ 150-200 instructions avant que la qualité ne se dégrade. Le contenu de votre CLAUDE.md rivalise avec tout le reste de la fenêtre de contexte. Si vous y mettez l’intégralité de votre guide de style SQL, les points importants se noient dans la masse.

Le consensus dans la communauté tourne autour de 300 lignes maximum, beaucoup recommandant moins de 60 lignes pour le fichier principal. Mon approche : inclure uniquement les conventions qui :

1. Provoquent souvent des erreurs quand Claude improvise
2. Sont propres à mon projet (pas des bonnes pratiques génériques)
3. Ne peuvent pas être gérées par des linters comme SQLFluff

Tout le reste ? Je renvoie vers des docs externes : « Voir docs/testing-standards.md pour le guide complet des tests. » Claude ira les consulter au besoin.

Ce qui mérite vraiment d’y figurer

Après pas mal de tâtonnements, voici ce que j’ai trouvé le plus utile pour les projets dbt :

Les commandes courantes avec leur contexte. Pas juste dbt run, mais dbt run --select $model_name avec une note sur quand l’utiliser. Claude s’en sert pour vérifier son travail.

Les conventions de nommage importantes. Le pattern base__<source>__<entity> avec doubles underscores. Les préfixes int__ et mrt__. Le nommage des clés primaires. Ce sont exactement les choses que Claude va mal deviner sans indications.

Les pièges propres à votre data warehouse. GoogleSQL vs legacy SQL sur BigQuery. La clause USING buggée de Snowflake dans les jointures. L’obligation de filtrer sur la partition. Ça évite de vrais bugs.

Votre workflow. Comment vous voulez que Claude aborde les changements — vérifier l’impact en aval d’abord, mettre à jour la doc YAML, lancer les tests avant de commiter. Ça cadre sa façon de travailler.

Ce que j’ai arrêté d’inclure : les règles de formatage SQL complètes (SQLFluff s’en charge), les schémas de base de données (trop de contexte), tout ce qui est auto-généré sans relecture.

Un template qui fonctionne

Voici ce que j’utilise comme point de départ pour les projets dbt :

# Contexte Analytics Engineering

Projet dbt sur BigQuery. Lancer `dbt compile` avant de proposer des modifications de modèle.

## Commandes
- `dbt run --select -s model_name` : Build uniquement les modèles spécifiés
- `dbt test --select model_name+` : Tester le modèle et tout ce qui est en aval
- `dbt compile` : Valider SQL/Jinja avant d'exécuter (à faire en premier)
- `sqlfluff lint models/` : Vérifier la conformité au style

## Nommage
- Base : `base__<source>__<entity>.sql` (double underscore)
- Intermediate : `int_<entity>_<verb>.sql`
- Marts : `mrt__`
- Clés primaires : `<object>__id` (customer__id, pas id)

## Patterns SQL
- Virgules en fin de ligne, indentation 4 espaces
- Toujours utiliser `AS` pour les alias
- Imports CTE en haut : `WITH model_name AS (SELECT * FROM {{ ref('...') }})`

## Tests
- Les clés primaires nécessitent unique + not_null
- Ajouter des commentaires expliquant pourquoi chaque test existe

## Workflow
1. Vérifier l'impact : `dbt ls --select +model_name+`
2. Faire les changements dans la bonne couche (base/intermediate/marts)
3. Mettre à jour schema.yml avec les descriptions
4. Compile → run → test → lint

Remarquez que ça fait environ 40 lignes. Tout ce qui compte, rien de superflu.

Ajouts spécifiques à BigQuery

Si vous êtes sur BigQuery, ces ajouts évitent les problèmes les plus fréquents :

## Spécificités BigQuery
- Utiliser la syntaxe GoogleSQL (pas le legacy SQL)
- Guillemets simples pour les chaînes, `!=` pour l'inégalité
- Toujours filtrer sur la colonne de partition dans les clauses WHERE
- Éviter SELECT * dans les modèles de production
- Pour les grandes tables, utiliser incremental avec insert_overwrite

## Template de partitionnement
{{ config(
  materialized='table',
  partition_by={"field": "created_at", "data_type": "timestamp", "granularity": "day"},
  require_partition_filter=true,
  cluster_by=["customer__id", "region"]
)}}

Le rappel sur le filtre de partition est crucial. Sans lui, Claude va tranquillement écrire des requêtes qui scannent des tables entières — le partition pruning ne fonctionne qu’avec des valeurs littérales dans les clauses WHERE.

La CLI suffit largement

Vous verrez peut-être des mentions de serveurs MCP pour l’intégration dbt : il existe un serveur dbt-mcp qui donne à Claude un accès direct à votre manifest et vos métadonnées. Franchement, c’est sans doute excessif pour la plupart des cas d’usage.

La CLI dbt ou bq fonctionne très bien avec Claude Code. Si votre CLAUDE.md inclut les bonnes commandes, Claude va tout simplement les utiliser. Il lancera dbt ls --select +model_name+ pour vérifier les dépendances, dbt compile pour valider le SQL, dbt test pour vérifier les changements, bq ls pour lister les objets dans BigQuery. Aucune configuration supplémentaire.

L’essentiel est que Claude sache quand utiliser chaque commande. D’où l’importance de la section workflow :

## Workflow
1. Vérifier l'impact : `dbt ls --select +model_name+`
2. Faire les changements dans la bonne couche
3. Mettre à jour schema.yml
4. Compile → run → test → lint

Claude suit cette séquence, exécute les commandes, lit les résultats, et s’adapte. Étonnamment efficace sans outillage sophistiqué.

Si vous travaillez sur un projet massif où parser le manifest ferait gagner beaucoup de temps, MCP mérite peut-être d’être exploré. Mais pour la plupart des projets dbt, la CLI fait très bien l’affaire.

Partage en équipe

Commitez votre CLAUDE.md dans le contrôle de version. Toute l’équipe bénéficie ainsi du même comportement de base avec Claude Code.

Pour les préférences personnelles qui n’ont pas à être partagées (un formatage différent, des chemins locaux), utilisez le fichier ~/.claude/CLAUDE.md dans votre répertoire home.

Vous pouvez aussi créer des commandes slash personnalisées dans .claude/commands/ pour les workflows récurrents. Par exemple /debug-test-failure qui déroule le processus de débogage standard de votre équipe.

Adopter une approche itérative

Soyons clairs : votre premier CLAUDE.md ne sera pas parfait du premier coup.

L’approche qui marche, c’est de commencer minimaliste, puis d’ajouter des instructions quand vous voyez Claude faire deux fois la même erreur. S’il continue d’utiliser la syntaxe legacy SQL, ajoutez une ligne sur GoogleSQL. S’il oublie de mettre à jour schema.yml, ajoutez ça à la section workflow.

La commande /init peut générer un point de départ en analysant votre projet, mais prenez-le comme un brouillon. Elle repère les patterns évidents mais passe à côté des subtilités de workflow qui font vraiment la différence.

Vous pouvez aussi ajouter des instructions à la volée pendant une session avec la touche #. Claude vous demandera dans quel fichier mémoire les enregistrer.

Ce que j’ai arrêté de faire

Quelques anti-patterns que j’ai abandonnés :

Les guides de style exhaustifs. SQLFluff gère le formatage bien mieux que n’importe quelle instruction. Laissez les outils déterministes faire le travail déterministe.

Les schémas de base de données. Trop de contexte, ça change trop souvent. Laissez Claude découvrir le schéma via des requêtes ou des connexions MCP.

Répéter la documentation dbt. Claude sait déjà comment fonctionnent ref() et source(). Concentrez-vous sur les patterns propres à votre projet.

Les instructions valables pour une seule tâche. Si ça ne s’applique qu’à un type de travail précis, ça n’a probablement pas sa place dans le fichier de mémoire persistante.

En résumé

CLAUDE.md est le plus utile quand il capture le savoir implicite de votre équipe — celui qui nécessiterait sinon d’être ré-expliqué en permanence. Les conventions, les pièges, le « on fait comme ça parce que » qui rend votre projet unique.

Gardez-le court, gardez-le ciblé, et faites-le évoluer en fonction des erreurs réelles de Claude. C’est aussi simple que ça.

Quelles conventions avez-vous trouvées les plus utiles dans votre CLAUDE.md ? Je cherche toujours à améliorer ma config.