ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Commandes slash Claude Code pour dbt

Comment créer des commandes slash personnalisées dans Claude Code qui automatisent les workflows dbt répétables — génération de tests, documentation de modèles et validation d'invites

Planté
claude codedbtautomationai

Les commandes slash sont des invites réutilisables et partageables en équipe qui transforment des workflows Claude Code multi-étapes en invocations uniques. Au lieu d’écrire une invite détaillée à chaque fois que vous voulez générer des tests ou documenter un modèle, vous tapez /generate-tests mrt__sales__orders et Claude exécute un workflow prédéfini.

Les commandes vivent en tant que fichiers Markdown dans .claude/commands/ à la racine de votre projet. Comme ce sont des fichiers ordinaires dans votre dépôt, les commiter dans git signifie que tous les membres de votre équipe obtiennent les mêmes workflows, les mêmes garde-fous, les mêmes standards de qualité.

Anatomie d’une commande slash

Une commande slash comporte trois parties : le frontmatter YAML, un espace réservé optionnel pour les arguments et le corps de l’invite.

---
description: Generate comprehensive dbt tests for a model
allowed-tools: Read, Write, Bash(dbt:*)
argument-hint: [model_name]
---
Analyze $ARGUMENTS and generate appropriate tests:


1. Read the model SQL and existing schema.yml
2. Identify primary key columns → add unique + not_null
3. Find foreign key relationships → add relationships tests
4. Detect enum-like columns → add accepted_values
5. Find numeric ranges → add appropriate range tests


Update the schema.yml with new tests.

Le description apparaît lorsque vous tapez / dans Claude Code, vous aidant à trouver la bonne commande.

Le champ allowed-tools restreint les outils que Claude peut utiliser lors de l’exécution. Read et Write pour les opérations sur les fichiers, Bash(dbt:*) pour toute commande CLI dbt. C’est une limite de sécurité — vous pouvez créer des commandes qui lisent mais n’écrivent jamais, ou des commandes qui exécutent dbt mais ne touchent jamais directement le système de fichiers.

L’argument-hint indique aux utilisateurs ce qu’il faut passer. Lorsque vous tapez /generate-tests, Claude demande des arguments. L’indice [model_name] indique clairement que vous devez fournir un nom de modèle.

$ARGUMENTS dans le corps est remplacé par ce que l’utilisateur passe après le nom de la commande.

/generate-tests : Scaffolding de tests

La commande de génération de tests analyse un modèle existant et produit des tests dbt appropriés :

---
description: Generate comprehensive dbt tests for a model
allowed-tools: Read, Write, Bash(dbt:*)
argument-hint: [model_name]
---
Analyze $ARGUMENTS and generate appropriate tests:


1. Read the model SQL and existing schema.yml
2. Identify primary key columns → add unique + not_null
3. Find foreign key relationships → add relationships tests
4. Detect enum-like columns → add accepted_values
5. Find numeric ranges → add appropriate range tests


Update the schema.yml with new tests.

Enregistrez-la sous .claude/commands/generate-tests.md. Utilisation : /generate-tests mrt__sales__orders.

Claude lit le SQL du modèle, identifie les colonnes par leurs transformations, déduit les tests appropriés et met à jour le schema.yml. Il capture l’évident — tests de clé primaire, intégrité référentielle, validations d’énumérations — ce qui est exactement le type de travail fastidieux facile à ignorer manuellement. La sortie est un bon point de départ qui nécessite une revue avant la validation.

Cette commande se couple naturellement avec les workflows TDD : utilisez /generate-tests sur un modèle existant pour ajouter rétroactivement une couverture de tests, puis utilisez le pattern TDD pour les nouveaux modèles.

/document-model : Documentation de modèles

La documentation est toujours en retard. La commande /document-model s’attaque à la partie fastidieuse — lire le SQL et écrire des descriptions — afin que vous puissiez vous concentrer sur la revue et l’affinage :

---
description: Generate comprehensive dbt documentation for a model
allowed-tools: Bash(dbt:*), Read, Write
argument-hint: [model_name]
---
# Document Model: $ARGUMENTS


1. Read the model SQL file at models/**/$ARGUMENTS.sql
2. Identify all columns and their transformations
3. Check if schema.yml exists for this model
4. Generate or update the schema.yml with:
   - Model description explaining business purpose
   - Column descriptions explaining meaning and source
   - Appropriate tests for each column


## Documentation Standards
- Model descriptions: Start with "This model..." and explain the grain
- Column descriptions: Include data type, business meaning, and source
- Use consistent terminology from our data dictionary


Create/update the schema.yml file and show a summary of changes.

Enregistrez sous .claude/commands/document-model.md. Utilisation : /document-model int__ga4_sessions_sessionized.

La section des standards de documentation est l’endroit où les conventions d’équipe sont encodées. “Start with ‘This model…’” assure la cohérence entre les modèles. “Include data type, business meaning, and source” garantit que les descriptions sont réellement utiles, pas seulement des reformulations du nom de colonne.

Pour un regard plus approfondi sur le workflow de documentation — y compris le pattern codegen en deux étapes et les blocs de docs pour la cohérence — voir Documentation dbt avec Claude Code.

/test-prompt : Validation d’invites

Avant d’exécuter une invite complexe sur des modèles de production, validez-la sur un modèle sandbox :

---
description: Test a prompt on a sandbox model before production use
allowed-tools: Read, Bash(dbt:*)
argument-hint: [prompt to test]
---
Run the following prompt on the sandbox model `test__sandbox__example`:


$ARGUMENTS


After execution, validate:
1. Output uses correct BigQuery syntax
2. All ref() and source() calls resolve
3. No SELECT * patterns
4. Document any edge cases or unexpected behavior


Report results. Do not modify any production models.

C’est particulièrement utile lors de la création de nouvelles commandes slash. Testez la logique de l’invite sur un modèle jetable avant de la déployer dans tout votre projet.

Sous-agents : commandes spécialisées

Pour les tâches complexes et ciblées, vous pouvez créer des définitions de sous-agents dans .claude/agents/. Un sous-agent obtient un contexte frais — sans le bagage de la conversation en cours — et se concentre entièrement sur sa tâche.

---
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 avec une invite comme : “Use the sql-debugger agent to investigate why int__ga4__sessions_attributed is returning NULL for channel_grouping on 5% of sessions.”

Le pattern de sous-agent est le plus utile lorsque votre conversation principale est encombrée d’autres contextes et que vous avez besoin que Claude se concentre entièrement sur un problème. Voir Débogage dbt avec Claude Code pour plus d’informations sur quand les sous-agents aident lors du débogage.

Distribution en équipe

La vraie puissance des commandes slash est la standardisation en équipe. Committez .claude/commands/ dans git et chaque membre de l’équipe obtient :

  • Le même workflow de génération de tests
  • Les mêmes standards de documentation
  • Les mêmes contrôles de qualité
  • Le même contexte de projet

Les nouveaux membres de l’équipe n’ont pas besoin d’apprendre les bonnes invites. Ils tapent / et voient ce qui est disponible. La connaissance institutionnelle vit dans les commandes, pas dans les têtes individuelles.

Concevoir de bonnes commandes

Quelques principes qui rendent les commandes plus fiables :

Être précis sur le format de sortie. “Update the schema.yml with new tests” est meilleur que “generate some tests.” Claude sait exactement quel artefact produire.

Contraindre avec allowed-tools. Une commande de documentation n’a probablement pas besoin d’un accès Bash. Une commande de tests n’a probablement pas besoin d’un accès Write aux fichiers non-YAML. Des périmètres plus restreints signifient moins de surprises.

Inclure des standards, pas seulement des étapes. “Model descriptions: Start with ‘This model…’” encode une convention. Sans cela, Claude génère des descriptions dans le style qui lui semble naturel pour cette conversation.

Utiliser $ARGUMENTS uniquement pour la partie variable. Les étapes du workflow, les standards de qualité et les contraintes doivent être fixes. Seul le nom du modèle ou la cible spécifique doit venir de l’utilisateur.

Tester les nouvelles commandes sur des modèles sandbox d’abord. Utilisez le pattern /test-prompt — ou exécutez simplement la commande manuellement sur un modèle non critique — avant de lui faire confiance avec du code de production.