Documentation dbt avec Claude Code

Cette note décrit un pattern pour la documentation dbt avec Claude Code : combiner les outils de codegen existants de dbt avec l’IA pour produire des descriptions qui reflètent ce que le SQL fait réellement. L’approche couvre le scaffolding YAML, les blocs doc pour la réutilisation, les diagrammes de lignage, et une commande slash pour des exécutions de documentation répétables.

Le pattern en deux étapes : Codegen + Claude Code

L’approche comporte deux phases : générer le squelette YAML avec dbt codegen, puis remplir les descriptions avec Claude Code.

Phase 1 : Générer le scaffold

Le package dbt codegen produit la structure schema.yml avec tous les noms de colonnes extraits du modèle :

dbt run-operation generate_model_yaml --args '{"model_names": ["base__ga4__events"], "upstream_descriptions": true}'

Cela vous donne la structure YAML — nom du modèle, tous les noms de colonnes, et toutes les descriptions en amont qui existent déjà. Pas de descriptions pour les nouvelles colonnes, pas de tests, pas de documentation au niveau du modèle. Juste le squelette.

Le flag upstream_descriptions: true est important — il extrait les descriptions depuis les définitions de sources ou les modèles en amont, afin de ne pas re-décrire les colonnes qui ont déjà de la documentation.

Phase 2 : Remplir avec Claude Code

Maintenant, pointer Claude vers le scaffold et le SQL :

Lis le modèle base__ga4__events.sql et le scaffold schema.yml généré.
Pour chaque colonne :
1. Analyser la logique de transformation SQL
2. Déduire la signification métier
3. Rédiger une description claire et concise
4. Ajouter des tests appropriés

Suivre ces standards :
- Utiliser le présent
- Inclure le type de données dans la description
- Noter les limitations connues

Claude lit le SQL et rédige des descriptions qui reflètent la transformation réelle. La sortie nécessite une révision — Claude peut mal interpréter une logique métier complexe — mais réviser des descriptions générées par IA est plus rapide que d’écrire depuis zéro.

Pourquoi deux étapes plutôt qu’une ?

On pourrait se demander pourquoi ne pas simplement demander à Claude de générer l’ensemble du schema.yml directement. L’étape codegen ajoute de la valeur parce qu’elle garantit que chaque colonne est prise en compte. Claude lisant du SQL pourrait manquer des colonnes ou halluciner des noms de colonnes qui n’existent pas. Codegen extrait la liste de colonnes réelle du modèle compilé, donnant à Claude un template fiable à remplir.

Blocs doc : la même colonne, la même description, partout

Les mêmes colonnes apparaissent dans plusieurs modèles. customer_id apparaît à dix endroits. event_timestamp à vingt. Sans coordination, chaque entrée schema.yml obtient une description légèrement différente, rédigée par une personne différente (ou une session IA différente), dans un style différent.

Les blocs doc dbt résolvent cela en créant de la documentation réutilisable référencée plutôt que dupliquée :

{% docs customer_id %}
Identifiant unique pour un compte client.
Format : UUID généré à la création du compte.
Source : API client Stripe.
{% enddocs %}

{% docs event_timestamp %}
Horodatage de l'événement enregistré en UTC.
Précision à la microseconde depuis l'export BigQuery GA4.
{% enddocs %}

Sauvegarder ceci dans un fichier models/docs.md (ou plusieurs fichiers docs organisés par domaine). Puis les référencer dans votre schema.yml :

columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"
  - name: event_timestamp
    description: "{{ doc('event_timestamp') }}"

Vous pouvez demander à Claude d’analyser tous vos modèles, d’identifier les colonnes fréquemment répétées, de créer un fichier docs.md avec des blocs réutilisables, et de mettre à jour les fichiers schema.yml pour les référencer. Un seul prompt, et soudainement la même colonne a la même description partout :

Parcourir tous les fichiers schema.yml du projet. Trouver les colonnes qui apparaissent dans 3+ modèles.
Pour chaque colonne répétée :
1. Créer un bloc doc dans models/docs.md
2. Rédiger une description unique et faisant autorité
3. Mettre à jour toutes les références schema.yml pour utiliser {{ doc('nom_colonne') }}

Après le nettoyage initial, les nouvelles descriptions référencent les blocs doc existants plutôt que d’introduire une nouvelle formulation pour les mêmes colonnes.

Standards de documentation

Encoder les standards dans vos commandes slash et CLAUDE.md rend la documentation cohérente quelle que soit la personne (ou l’entité) qui l’écrit.

Standards efficaces pour la documentation des modèles dbt :

• Les descriptions de modèles commencent par « Ce modèle… » et expliquent le grain. « Ce modèle contient une ligne par client avec leurs métriques d’achat cumulatif » est utile. « Données client » ne l’est pas.
• Les descriptions de colonnes incluent le type de données, la signification métier et la source. « Chaîne. Identifiant unique pour un compte client, généré à la création du compte dans Stripe. » dit au lecteur tout ce dont il a besoin.
• Cohérence de la terminologie. Si votre projet utilise « session » plutôt que « visite », chaque description devrait utiliser « session ». Documenter la terminologie dans votre dictionnaire de données et le référencer depuis CLAUDE.md.
• Présent. « Contient la valeur totale de la commande » et non « Contiendra » ou « Contenait ».
• Noter les limitations. Si une colonne n’est renseignée que pour certains types d’enregistrements, ou a des problèmes de qualité de données connus, le préciser. « Non renseigné pour les commandes en mode invité » évite des heures de débogage.

Documentation de lignage avec Mermaid

Claude Code peut générer des diagrammes Mermaid montrant le lignage de données dans votre architecture en trois couches :

Créer un diagramme Mermaid montrant le lignage depuis les événements GA4 bruts
jusqu'au modèle d'attribution marketing final. Inclure toutes les transformations
intermédiaires et la logique métier clé à chaque étape.

La sortie :

flowchart TD
    A[raw.ga4_events] --> B[base__ga4__events]
    B --> C[int__ga4_sessions_sessionized]
    C --> D[int__ga4_sessions_attributed]
    D --> E[mrt__marketing__attributed_conversions]

Ces diagrammes sont utiles pour :

• L’onboarding des nouveaux membres de l’équipe qui ont besoin de comprendre les chaînes de transformation
• Les révisions de PR où le relecteur a besoin de voir la portée des changements en contexte
• La réponse aux incidents lors de la traçabilité d’un problème de qualité de données dans le DAG
• La documentation qui vit aux côtés de vos modèles dans des fichiers Markdown

Claude génère ces diagrammes en lisant les appels ref() dans vos fichiers SQL, ce qui signifie que les diagrammes reflètent le DAG réel — pas un diagramme d’architecture aspirationnel qui a divergé de la réalité il y a six mois.

Le workflow /document-model

Encapsuler tout cela dans une commande slash en fait un processus en une étape. Sauvegarder comme .claude/commands/document-model.md :

---
description: Générer une documentation dbt complète pour un modèle
allowed-tools: Bash(dbt:*), Read, Write
argument-hint: [nom_du_modèle]
---
# Documenter le modèle : $ARGUMENTS

1. Lire le fichier SQL du modèle dans models/**/$ARGUMENTS.sql
2. Identifier toutes les colonnes et leurs transformations
3. Vérifier si schema.yml existe pour ce modèle
4. Générer ou mettre à jour le schema.yml avec :
   - Description du modèle expliquant la finalité métier
   - Descriptions des colonnes expliquant la signification et la source
   - Tests appropriés pour chaque colonne

## Standards de documentation
- Descriptions de modèles : Commencer par « Ce modèle... » et expliquer le grain
- Descriptions de colonnes : Inclure le type de données, la signification métier et la source
- Utiliser la terminologie cohérente de notre dictionnaire de données

Créer/mettre à jour le fichier schema.yml et afficher un résumé des changements.

Exécuter /document-model int__ga4_sessions_sessionized génère de la documentation en une commande. Réviser la sortie, ajuster ce que Claude a mal compris, et commiter. Pour les équipes adoptant Claude Code, c’est un point d’entrée à faible risque : la sortie est délimitée, vérifiable, et facile à affiner. Superposer les workflows de test une fois que l’équipe est à l’aise avec le pattern.