CLAUDE.md pour l'analytics engineering

Ce hub connecte les notes couvrant chaque couche de configuration CLAUDE.md pour les analytics engineers travaillant sur dbt et BigQuery.

Le concept de base

CLAUDE.md comme mémoire de projet couvre le fonctionnement du fichier : chargement hiérarchique du répertoire home jusqu’à la racine du projet, la contrainte de budget d’instructions (~150-200 instructions avant que la qualité se dégrade), et l’approche réactive. Commencez sans CLAUDE.md, utilisez Claude Code, et ajoutez des lignes lorsque Claude fait de vraies erreurs.

Configuration spécifique à dbt

CLAUDE.md pour les projets dbt couvre ce qui appartient réellement au CLAUDE.md d’un projet dbt — les quatre catégories qui méritent leur place :

Commandes avec contexte — pas seulement dbt run, mais quand utiliser dbt ls --select +model_name+ pour vérifier les dépendances d’abord
Conventions de nommage — le séparateur double-underscore, les préfixes de couche (base__, int__, mrt__), le nommage des clés primaires
Particularités spécifiques à l’entrepôt — les règles qui préviennent les bugs, pas les préférences de style
Séquence de workflow — vérifier l’impact → modifier → mettre à jour schema.yml → compiler → tester

Couvre également ce qu’il ne faut pas inclure : les guides de style SQL exhaustifs (SQLFluff s’en charge), les schémas de base de données complets, la documentation dbt générique et le contenu auto-généré par /init.

Ajouts spécifiques à BigQuery

Spécificités BigQuery dans CLAUDE.md couvre la section BigQuery qui prévient les erreurs les plus coûteuses :

Application du dialecte GoogleSQL vs legacy SQL
Exigences de filtre de partition (celle qui coûte de l’argent lorsqu’elle est oubliée)
Le bloc de configuration du modèle incrémental avec insert_overwrite et require_partition_filter=true
Conventions de guillemets de chaînes et d’opérateurs de comparaison

Au-delà de CLAUDE.md : hooks et commandes slash

CLAUDE.md fournit des directives que Claude devrait suivre. Pour une application plus stricte, deux outils complémentaires :

Hooks Claude Code — des commandes shell déterministes qui s’exécutent à des points du cycle de vie. Utilisez les hooks pour exécuter automatiquement SQLFluff après chaque modification (PostToolUse), bloquer les modifications des fichiers mart de production (PreToolUse), ou compiler automatiquement les modèles immédiatement après les changements.

Commandes slash Claude Code pour dbt — des workflows réutilisables stockés dans .claude/commands/ et commités dans git. /generate-tests, /document-model, /debug-test-failure — des workflows partagés en équipe qui encodent la connaissance institutionnelle dans des fichiers plutôt que dans des invites individuelles.

Les trois couches fonctionnent ensemble : CLAUDE.md pour le contexte et les conventions, les hooks pour les garde-fous durs, les commandes slash pour les workflows répétables.

CLI vs. MCP

L’article sur lequel ce hub s’appuie note que le CLI dbt est suffisant pour la plupart des workflows. Claude Code lit les commandes dans votre CLAUDE.md, exécute dbt ls, dbt compile, dbt test et bq ls naturellement — aucune configuration supplémentaire n’est requise.

CLI vs MCP pour les agents IA couvre les compromis généraux. Pour dbt spécifiquement : le CLI fonctionne bien parce que Claude a des données d’entraînement extensives sur les commandes dbt et la syntaxe CLI de BigQuery. Un serveur MCP ajoute une surcharge qui ne vaut la peine que sur de très grands projets où l’analyse du manifeste permettrait d’économiser un temps significatif.

La boucle d’itération

Exécuter Claude Code sur un projet avec un CLAUDE.md minimal ou inexistant
Remarquer quand Claude fait une erreur (mauvaise convention de nommage, mise à jour schema.yml manquante, mauvais dialecte SQL)
La corriger dans la session
Appuyer sur # pour ouvrir la commande mémoire et ajouter l’instruction à CLAUDE.md
Répéter

Après quelques semaines, le résultat est un fichier de 30-50 lignes où chaque instruction remonte à un vrai problème.