Débogage dbt avec Claude Code

L’approche efficace avec Claude Code est de laisser l’agent affronter les erreurs directement plutôt que de pré-collecter des preuves ou de coller des messages d’erreur pour interprétation. Claude Code exécute des commandes, lit des fichiers et effectue des modifications dans une boucle unique : il exécute dbt build, lit l’erreur, vérifie le SQL compilé, lit les modèles upstream si nécessaire, applique un correctif et relance. Le cycle de débogage se déroule sans gestion manuelle des étapes.

Erreurs de build

Pour les erreurs qui empêchent un modèle de se construire — problèmes de syntaxe SQL, appels ref() cassés, incompatibilités de types, échecs de compilation Jinja :

Run dbt build --select mrt__sales__orders and fix any errors.

C’est tout. Claude exécute la commande, lit la sortie d’erreur et enquête. Pour une erreur de build typique, le processus de Claude ressemble à :

1. Exécuter dbt build --select mrt__sales__orders
2. Voir l’erreur (ex. : “Column amount not found in table”)
3. Lire le SQL du modèle pour trouver la référence
4. Lire le modèle upstream pour vérifier le nom de colonne réel
5. Corriger la référence (amount → order_amount)
6. Exécuter à nouveau dbt build pour vérifier

Claude Code gère bien les erreurs inter-fichiers : renommages de colonnes dans des modèles upstream qui cassent des références en aval, changements d’arguments de macros en cascade, dérive de schéma dans les tables sources.

Problèmes de données : résultats incorrects, pas d’échecs de build

Les problèmes de données sont plus difficiles que les erreurs de build parce que le modèle s’exécute avec succès mais produit des résultats incorrects. L’approche est différente — décrivez le symptôme, pas la cause supposée :

The mrt__sales__orders model shows incorrect total_revenue for customer_id='ABC123'.
Trace through the upstream models to find where the calculation goes wrong.

L’investigation de Claude pour un problème de données est plus exploratoire :

1. Interroger mrt__sales__orders pour le client problématique afin de confirmer le problème
2. Lire le SQL du modèle pour comprendre le calcul de total_revenue
3. Identifier les dépendances upstream (appels ref())
4. Interroger les tables intermédiaires pour vérifier les valeurs à chaque étape de transformation
5. Trouver le point de divergence (“le revenu est correct dans int__orders__enriched mais incorrect dans le mart — l’agrégation double-compte les retours”)
6. Corriger la logique et vérifier la sortie

Le principe clé : décrivez le problème, pas les étapes de débogage. “total_revenue est incorrect pour ce client” donne à Claude la liberté d’enquêter de la manière qui fait sens. “Vérifiez s’il y a une jointure dupliquée dans le CTE n°3” contraint Claude à votre hypothèse, qui pourrait être fausse.

Sous-agents pour le débogage complexe

Certains bugs sont véritablement complexes : données arrivant en retard qui corrompent les modèles incrémentiels, conditions de course dans les exécutions dbt concurrentes, problèmes subtils de fuseau horaire qui ne se manifestent qu’à certaines dates. Pour ceux-ci, un contexte frais entièrement focalisé sur le débogage aide.

Créez un sous-agent de débogage dans .claude/agents/sql-debugger.md :

---
name: sql-debugger
description: Specialized agent for debugging SQL and dbt issues
---

You are an expert SQL debugger specializing in BigQuery and dbt.

## Your Approach

1. **Gather Evidence First**
   - Read error logs completely
   - Check compiled SQL
   - Review recent git changes to the model

2. **Form Hypotheses**
   - List possible causes ranked by likelihood
   - Consider: data issues, schema changes, logic errors

3. **Test Systematically**
   - Isolate the problem with minimal reproducing case
   - Use WHERE clauses to test on small data
   - Add CTEs to inspect intermediate results

4. **Fix and Verify**
   - Implement the minimum change to fix the issue
   - Add tests to prevent regression
   - Document the root cause

Invoquez-le quand votre conversation principale est encombrée d’un autre contexte :

Use the sql-debugger agent to investigate why int__ga4__sessions_attributed
is returning NULL for channel_grouping on 5% of sessions.

Le sous-agent obtient un contexte frais. Il ne porte pas le bagage de tout ce sur quoi vous travailliez dans la conversation principale. Cela importe car la capacité de Claude à se concentrer se dégrade dans des conversations très longues avec des sujets mixtes — l’investigation de débogage entre en compétition pour l’attention avec la construction de modèles, la documentation et d’autres tâches.

Quand les sous-agents aident vs. sont superflus

Utilisez la conversation principale pour :

• Les erreurs de build avec des messages d’erreur clairs
• Les problèmes de données simples avec des symptômes évidents
• Les erreurs dans les modèles sur lesquels vous travaillez activement

Utilisez les sous-agents pour :

• Les problèmes nécessitant une investigation sur plus de 5 fichiers
• Les problèmes où vous avez déjà passé plusieurs tours de conversation sans résolution
• Les sessions de débogage qui doivent coexister avec d’autres travaux en cours

La surcharge de démarrage d’un sous-agent (il doit relire le contexte depuis le début) ne vaut pas le coup pour une simple erreur “column not found”. Elle vaut largement pour “5 % des sessions ont une attribution NULL et nous ne savons pas pourquoi”.

Patterns de débogage qui fonctionnent bien

Boucles “fix and run”. Dites à Claude de corriger une erreur et de relancer le build en une seule instruction. Claude gère l’itération en interne, ce qui est plus rapide que de revoir chaque correctif avant la prochaine tentative.

Inspection du SQL compilé. Quand un modèle riche en Jinja produit des résultats inattendus, demandez à Claude de lire le SQL compilé dans target/compiled/. La version compilée montre exactement ce que BigQuery a reçu, en supprimant l’abstraction Jinja.

Débogage conscient de Git. “Ce modèle fonctionnait hier. Vérifiez ce qui a changé depuis et identifiez ce qui l’a cassé.” Claude peut exécuter git diff sur le modèle et ses dépendances pour trouver les changements récents corrélés avec l’échec.

Traçage upstream avec des requêtes. Pour les problèmes de données, Claude peut écrire et exécuter des requêtes de diagnostic à chaque étape de la chaîne de lignage. C’est plus rapide que d’écrire manuellement des requêtes car Claude lit le SQL et génère des instructions SELECT ciblées qui vérifient des valeurs spécifiques.

Après une session de débogage

Après que Claude a corrigé un bug :

1. Ajoutez un test qui détecte l’échec spécifique. La taxonomie des tests dbt couvre quel type de test convient à quel scénario.
2. Ajoutez un hook si le bug a été causé par une opération qui aurait dû être bloquée (modification d’un fichier protégé, exécution sans filtres de partition, etc.).
3. Mettez à jour CLAUDE.md si Claude répète plusieurs fois la même erreur qui conduit à des bugs (utilisation de la mauvaise fonction de date, oubli de la gestion des fuseaux horaires, etc.).

Chaque session de débogage devrait laisser derrière elle une défense permanente. Un test détecte la régression. Un hook empêche l’action. Une entrée CLAUDE.md empêche le pattern. Au fil du temps, les mêmes bugs cessent de réapparaître — non pas parce que vous vous souvenez de les éviter, mais parce que le système les empêche.