Après que le scaffolding et la propagation gèrent les parties mécaniques de la documentation, les colonnes restantes nécessitent de vraies descriptions. 50% des praticiens utilisent déjà l’IA pour cette étape (rapport dbt Labs 2025 State of Analytics Engineering). Tous les outils ci-dessous partagent une limitation fondamentale : ils décrivent ce que le SQL fait, pas ce que les données signifient pour l’entreprise. Combler cet écart avec le contexte métier est ce qui distingue une documentation utile d’un simple reformatage des noms de colonnes.
dbt Copilot
dbt Copilot est passé en GA en mars 2025, disponible sur les plans Starter, Enterprise et Enterprise+. Il génère de la documentation YAML en utilisant les métadonnées du projet — lignée, relations de schéma, SQL des modèles — sans accéder aux données au niveau des lignes. Un clic dans l’IDE dbt Cloud vous donne des descriptions pour un modèle et ses colonnes.
Ce qu’il voit : Votre SQL, les métadonnées, les relations de lignée et les informations de schéma.
Ce qu’il ne voit pas : Vos PRDs, conversations Slack, glossaire métier ou tout contexte extérieur au projet dbt.
Le résultat : Des descriptions exactes sur la transformation technique mais qui peuvent manquer la signification métier. La documentation dbt est transparente à ce sujet : « Révisez toujours le contenu généré par l’IA, car il peut être incorrect. »
Idéal pour : Les équipes déjà sur dbt Cloud qui veulent de la documentation sans outillage supplémentaire. Vous obtenez Copilot avec votre abonnement existant.
Claude Code avec le Serveur MCP dbt
Pour les équipes sur dbt Core, Claude Code avec le serveur MCP dbt (GA octobre 2025) se connecte au contexte de votre projet : lignée, relations au niveau des colonnes, contrats, tests, métadonnées de fraîcheur. Combiné avec un CLAUDE.md bien configuré, il génère de la documentation qui respecte les conventions de votre équipe.
La bibliothèque open source Agent Skills de dbt Labs fournit des instructions sélectionnées qui ont amélioré la précision sur les tâches dbt de 56% à 58,5%. Pas spectaculaire, mais significatif quand multiplié sur des centaines de modèles.
Ce qu’il voit : Tout ce que le serveur MCP expose (lignée, relations de colonnes, contrats, tests, fraîcheur) plus tout ce que vous mettez dans CLAUDE.md et les fichiers de votre projet.
Ce qu’il ne voit pas : Les bases de connaissances internes, sauf si vous copiez le contexte pertinent dans CLAUDE.md ou configurez un pipeline RAG.
Le résultat : Des descriptions qui respectent les conventions de votre équipe (si ces conventions sont encodées dans CLAUDE.md) et reflètent les transformations SQL. Le pattern codegen + Claude Code produit les résultats les plus cohérents : construisez d’abord le squelette YAML, puis laissez Claude remplir les descriptions.
Idéal pour : Les équipes dbt Core qui utilisent déjà Claude Code pour le développement. Le serveur MCP ajoute du contexte de documentation sans changer votre éditeur ou votre workflow.
Altimate AI (dbt Power User)
L’extension dbt Power User d’Altimate AI offre une génération de documentation en masse avec trois personas (technique, métier, général) et un support multilingue. Via la tarification de Paradime à 25-55 $/utilisateur/mois, c’est l’option de documentation IA la plus abordable pour les équipes utilisant VS Code ou Cursor.
Ce qu’il voit : Vos fichiers de projet dbt, votre schéma et tout contexte que l’extension peut extraire.
Idéal pour : Les équipes qui veulent une documentation IA sans changer leur éditeur ou workflow, en particulier celles déjà dans Cursor ou VS Code.
Choisir Entre Eux
Commencez par ce que vous avez déjà.
| Si vous utilisez… | Commencez avec… |
|---|---|
| dbt Cloud | dbt Copilot (inclus dans l’abonnement) |
| dbt Core + Claude Code | Claude Code + Serveur MCP |
| VS Code/Cursor sans Claude Code | Altimate AI / dbt Power User |
Ces outils ne sont pas mutuellement exclusifs. Copilot peut gérer la documentation initiale dans l’IDE Cloud ; Claude Code peut affiner localement. Altimate AI peut gérer la génération en masse ; Claude Code peut être utilisé pour les modèles nécessitant des descriptions plus nuancées.
Ce que Tous les Outils IA Ratent
Le blog Recce a documenté un échec instructif : Claude Code a filtré silencieusement les lignes avec des org_id manquants lors de la construction d’un modèle. Une décision de qualité des données prise par une IA, enfouie dans le code. Le même pattern apparaît dans la documentation :
- Reformatage du nom de colonne.
customer__segmentdécrit comme « Le segment du client. » Techniquement pas faux, complètement inutile. - Logique métier supposée. L’IA pourrait décrire une colonne comme « la valeur vie client » alors que votre entreprise calcule la LTV différemment de toute définition standard.
- Exclusions manquantes. Un champ de statut décrit sans mentionner que certains statuts sont exclus du reporting.
- Non-correspondances de conventions. Des styles de description différents selon les modèles parce que l’IA n’a pas reçu de règles de formatage cohérentes.
L’équipe Altimate AI a constaté que la principale source d’erreurs était les conventions non respectées, corrigée en ajoutant l’instruction « lire d’abord 2 à 3 modèles existants ». Chaque correction améliore le prochain cycle.
Construire une Boucle de Rétroaction
Traitez les descriptions générées par l’IA avec le même niveau de scrutin de revue de PR que les modifications SQL, car une description trompeuse cause des erreurs en aval tout aussi facilement qu’un mauvais JOIN. Chaque fois que vous détectez une erreur de documentation IA :
- Corrigez la description dans le schema.yml
- Ajoutez une règle dans votre CLAUDE.md ou fichier Skills qui prévient la même erreur
- Si l’erreur portait sur la logique métier, envisagez d’ajouter ce contexte dans votre CLAUDE.md ou pipeline RAG
Cette boucle de rétroaction est ce qui transforme la documentation IA d’un outil de génération ponctuelle en un système qui s’améliore avec le temps. La première passe peut nécessiter une revue approfondie. La cinquième passe, avec les corrections accumulées encodées dans la configuration de votre projet, en nécessite beaucoup moins.
Priorisation de la Couverture
L’IA génère le plus de valeur dans la plage de couverture 20 à 80%, où la transformation SQL raconte la plus grande partie de l’histoire. La plage 80 à 100% nécessite une revue humaine car les colonnes restantes tendent à avoir la logique métier la plus complexe — cas limites, définitions spécifiques à l’entreprise et significations de champs qui varient selon le contexte.
Commencez par les modèles les plus interrogés plutôt que d’essayer de tout documenter d’un coup. Dix modèles critiques soigneusement documentés, avec contexte métier et descriptions révisées, valent plus que 200 modèles avec des premières ébauches générées par l’IA que personne n’a vérifiées.