Prompting Claude Code pour dbt

Un prompting efficace pour le travail dbt ne concerne pas des formules magiques ou des prompts système élaborés. C’est une question d’un seul principe : éliminer les suppositions. Chaque décision que Claude doit prendre sans orientation est une décision qui pourrait ne pas correspondre à votre intention. Les bons prompts ne laissent pas à Claude la place de deviner.

Le revers : maîtriser des prompts efficaces prend plusieurs semaines d’utilisation réelle. Vous devez rencontrer les échecs — le modèle générique qui ne correspond pas à vos conventions, le refactoring qui a manqué la moitié des références, le test qui vérifie la mauvaise chose — avant d’intérioriser pleinement l’information dont Claude a réellement besoin.

Les quatre propriétés des prompts efficaces

1. Spécificité sur les résultats

Ne décrivez pas un processus. Décrivez un résultat.

Faible : “Crée un modèle intermédiaire qui joint les commandes aux clients.”

Fort : “Crée int_orders__enriched qui joint base__shopify__orders à base__shopify__customers sur customer__id. Grain de sortie : une ligne par commande. Inclure toutes les colonnes de commande plus customer__email, customer__country, et customer__first_order_date. Matérialiser en table. Test de clé primaire sur order__id.”

Le deuxième prompt spécifie : le nom exact du modèle, les modèles sources, la clé de jointure, le grain de sortie, quelles colonnes inclure, la matérialisation, et le test. Rien n’est laissé à la supposition.

2. Contraintes et exigences explicites

Dites ce que vous ne voulez pas aussi clairement que ce que vous voulez. Les contraintes sont souvent plus précieuses que les instructions positives.

Crée un modèle de base pour source_shopify.orders.

Contraintes :
- Dédupliquer sur order__id avec ROW_NUMBER() QUALIFY, pas une sous-requête WHERE
- Inclure les colonnes de métadonnées _loaded_at et _source_table
- N'ajoute PAS de logique business (pas de catégorisation de commande, pas de niveaux de chiffre d'affaires)
- N'utilise PAS SELECT *
- Caster les montants financiers en FLOAT64

La liste d’interdictions empêche Claude de faire des choses qui semblent raisonnables dans l’abstrait mais ne correspondent pas aux conventions de votre projet. “N’ajoute PAS de logique business” compte pour les modèles de base car Claude ajoute parfois de la catégorisation CASE WHEN pour être utile. Vous ne voulez pas ça dans les modèles de base.

3. Références aux patterns existants de la base de code

“Suis le pattern dans models/base/base_shopify__orders.sql” est plus puissant que n’importe quelle explication de ce à quoi ressemble un bon modèle de base. Claude lit le fichier réel et extrait le pattern — structure CTE, conventions de nommage, bloc config, style de test — directement depuis votre code.

C’est pourquoi la réplication de pattern est l’une des capacités les plus fortes de Claude Code avec dbt. Le principe du “bon exemple unique” : avoir un modèle correctement écrit, le référencer dans les prompts suivants, laisser Claude répliquer le pattern.

Crée un test singulier pour mrt__product_performance en suivant le pattern
dans tests/assert_revenue_never_negative.sql

Crée une macro pour générer des clés de substitution en suivant le style dans
macros/utils/generate_surrogate_key.sql

Le modèle de référence fait plus de travail pédagogique qu’aucune description ne pourrait le faire.

4. Définition claire de “bon” résultat

Dites à Claude ce à quoi la sortie doit être vérifiable. Pas seulement “crée un modèle” mais “crée un modèle qui passe dbt build --select nom_modele+.”

Crée un modèle intermédiaire int_customers__aggregated qui :
- Prend base__shopify__orders comme entrée
- Agrège à une ligne par client
- Inclut : customer__id, total_orders, total_revenue_usd, first_order_date, last_order_date
- S'exécute avec succès avec dbt build --select int_customers__aggregated

Lance dbt build pour vérifier avant de terminer.

Quand Claude sait que le critère de succès est un build vert, il boucle lui-même — lançant la commande, voyant l’erreur s’il y en a une, la corrigeant, et relançant. Vous obtenez du code fonctionnel, pas du code syntaxiquement plausible.

Le problème de la mémoire sans session

Claude Code n’a pas de mémoire entre les sessions. Cela piège les utilisateurs qui ont eu une bonne première session et supposent que le contexte persiste.

Ceci ne fonctionne pas :

Comme on en a parlé hier, mets à jour le modèle de chiffre d'affaires pour utiliser
la nouvelle logique d'attribution

Claude n’a aucune idée de ce que vous avez discuté hier. Il ne sait pas quel modèle de chiffre d’affaires, quelle logique d’attribution, ou ce que “nouvelle” signifie. Ce prompt produit soit une réponse confuse soit une réponse confiante mais incorrecte.

Chaque prompt doit être autonome. Spécifiez le nom du modèle, énoncez les changements requis, fournissez le contexte :

Mets à jour mrt__marketing__attributed_revenue pour utiliser l'attribution au dernier contact
au lieu du premier contact. Actuellement le modèle attribue tout le chiffre d'affaires à la
première source de session. Change-le pour attribuer à la dernière source de session avant
la conversion. La colonne concernée est customer__attribution_source dans
int__sessions__attributed.

Même demande, résultat complètement différent.

CLAUDE.md comme mémoire de projet résout une partie de cela pour les conventions persistantes — Claude lit le fichier au début de chaque session et porte le contexte du projet. Mais CLAUDE.md gère les conventions, pas l’historique de conversation. Le contexte spécifique “ce qui a changé hier” doit toujours être réénoncé.

Anatomie d’un prompt fort

Pour la génération de modèles dbt, un prompt complet a ces composants :

[Action] [cible] [depuis les sources] [en suivant le pattern].
[Grain]. [Liste de colonnes]. [Contraintes].
[Exigences de test].
[Étape de vérification].

Appliqué :

Crée int_orders__pivoted depuis base__shopify__orders. Suis le pattern
dans int_customers__aggregated.

Grain : une ligne par commande.
Pivoter order_status en colonnes booléennes : is_pending, is_completed, is_cancelled.

Contraintes :
- Matérialiser en table
- Utiliser un nommage CTE cohérent : source, pivoted, final
- Pas de SELECT *

Tests : unique et not_null sur order__id, not_null sur toutes les colonnes booléennes.

Lance dbt build --select int_orders__pivoted pour vérifier.

Ce prompt est plus long que “fais-moi un modèle de commandes” mais la sortie ne nécessite aucune correction. Le gain de temps de moins de cycles de révision compense largement le temps supplémentaire de rédaction du prompt.

Quand écrire une commande slash à la place

Si vous vous retrouvez à écrire le même prompt détaillé plus de 2 à 3 fois, c’est un signal qu’il devrait devenir une commande slash. Les contraintes, les étapes de vérification, et les standards sont encodés une fois dans .claude/commands/ et deviennent reproductibles.

/generate-base-model source_stripe.charges

…remplace un prompt de 200 mots. L’équipe hérite des mêmes standards de qualité sans avoir à apprendre quoi inclure dans chaque prompt. Les commandes slash sont la façon dont les bonnes pratiques de prompting s’étendent au-delà de l’utilisation individuelle.

Ce qui ne fonctionne pas

Intention générique :

“Fais un modèle qui agrège les commandes”

Claude produira quelque chose, mais le grain, la sélection de colonnes, la logique d’agrégation, et le format de sortie seront tous des suppositions. Réviser et corriger une sortie générique prend plus de temps qu’écrire un prompt spécifique.

Référence au contexte implicite :

“Met à jour le modèle qu’on était en train de corriger la semaine dernière”

Pas de mémoire, pas de contexte, pas de sortie utilisable.

“Bon” non défini :

“Améliore la documentation dans models/marts/”

Améliore comment ? Plus de détails ? Un style différent ? Ajouter des colonnes manquantes ? Couvrir quels modèles ? Cela produit des changements arbitraires qui peuvent ne pas correspondre à vos standards.

Laisser des décisions non définies :

“Ajoute des tests au modèle de chiffre d’affaires”

Quels tests ? Des tests de schéma ou des tests singuliers ? Sur quelles colonnes ? À quelle sévérité ? Un prompt comme celui-là vous donne des tests, mais pas nécessairement les tests qui comptent pour la logique business de ce modèle.

Le principe sous-jacent

Claude Code gère l’implémentation, pas la conceptualisation. La réflexion sur ce qu’un modèle doit faire, à quel grain il doit être, quelle logique business il nécessite — tout cela reste humain. Claude convertit votre spécification en fichiers.

Quand un prompt échoue, la cause profonde est presque toujours que la spécification n’était pas complète. La correction est plus de spécificité, pas une formulation différente. Ajoutez la contrainte manquante, nommez le pattern à suivre, définissez ce que “terminé” signifie. La sortie s’améliore proportionnellement à la façon dont le prompt élimine les suppositions.